Check Profile

Overview

The Profile Check API allows you to verify whether a user (identified by mobile number) is registered with various Account Aggregators (AAs) and whether they have linked financial accounts. This API aggregates data from multiple AAs into a unified response, enabling you to make informed decisions about user onboarding flows.

Key Features

Multi-AA Aggregation: Checks registration status across all enabled Account Aggregators in a single API call
Parallel Execution: Requests are sent to all AAs simultaneously for optimal performance
Selective AA Querying: Optionally filter to check only specific AAs
Unified Response Format: Consistent response structure regardless of underlying AA response formats

Use Cases

Smart User Onboarding: Determine which AAs a user is registered with to guide them to the appropriate consent flow
AA Selection Guidance: Help users choose an AA where they already have an account for faster onboarding
Pre-consent Validation: Verify user readiness before initiating consent requests

Authentication

This API requires the following authentication headers with every request:

Header	Type	Required	Description
`client_id`	string	Yes	API key issued to your organisation for authentication
`client_secret`	string	Yes	Secret API key for secure server-side authentication
`organisationId`	string	Yes	Unique identifier assigned to your organisation
`appIdentifier`	string	Yes	Unique identifier for your client application
`Content-Type`	string	Yes	Must be set to `application/json`

Request Body

mobileNumber

string

required

The user’s 10-digit mobile phone number to check against Account Aggregator databases.Format: 10 digits, numeric only, without country code prefixExample: 9876543210Validation: Must be exactly 10 numeric digits

A unique consent identifier to be passed to AA calls. This is used by some AAs to track the profile check request.Format: 1-100 charactersExample: consent-uuid-12345

aaId

string[]

Optional array of AA identifiers to filter the check to specific Account Aggregators. If not provided, all enabled AAs are checked.Format: Array of alphanumeric strings (2-50 characters each)Example: ["onemoney", "finvu"]Note: AA identifiers should be provided without the @ symbol

Response

Success Response

ver

string

API version number.Example: "1.0.0"

timestamp

string

ISO 8601 timestamp of when the response was generated.Example: "2025-11-25T10:30:00.000Z"

txnid

string

Unique transaction identifier for this request.Example: "550e8400-e29b-41d4-a716-446655440000"

data

array

Array of profile check results, one entry per AA that was queried.

data[].aaId

string

Account Aggregator identifier (without the @ symbol).Example: "onemoney"

data[].registrationStatus

boolean | null

Indicates whether the user is registered with this AA.Values:

true: User has a Virtual User Account (VUA) with this AA
false: User is not registered with this AA
null: Unable to determine (check failed or timed out)

data[].hasLinkedAccounts

boolean | null

Indicates whether the user has linked financial accounts with this AA.Values:

true: User has linked one or more financial accounts
false: User has not linked any accounts (or is not registered)
null: Unable to determine (check failed or timed out)

data[].status

string

The outcome of the profile check for this AA.Values:

success: AA responded successfully with profile information
timeout: AA did not respond within the configured timeout period
failed: An error occurred during the check (see errorMessage)

data[].errorMessage

string

Error details when status is failed. Not present for successful or timed out requests.

Example Requests

Check All AAs

Query all enabled Account Aggregators for the user’s profile status:

{
  "mobileNumber": "9876543210",
  "userConsentId": "consent-uuid-12345"
}

Check Specific AAs

Query only specific Account Aggregators:

{
  "mobileNumber": "9876543210",
  "userConsentId": "consent-uuid-12345",
  "aaId": ["onemoney", "finvu"]
}

Example Responses

Successful Multi-AA Response

{
  "ver": "1.0.0",
  "timestamp": "2025-11-25T10:30:00.000Z",
  "txnid": "550e8400-e29b-41d4-a716-446655440000",
  "data": [
    {
      "aaId": "onemoney",
      "registrationStatus": true,
      "hasLinkedAccounts": true,
      "status": "success"
    },
    {
      "aaId": "finvu",
      "registrationStatus": false,
      "hasLinkedAccounts": false,
      "status": "success"
    },
    {
      "aaId": "anumati",
      "registrationStatus": null,
      "hasLinkedAccounts": null,
      "status": "timeout"
    }
  ]
}

Response Interpretation

AA	registrationStatus	hasLinkedAccounts	Interpretation
onemoney	`true`	`true`	User is registered and has linked accounts - can proceed directly to consent
finvu	`false`	`false`	User not registered - needs to complete AA registration first
anumati	`null`	`null`	Unable to determine - AA did not respond in time

Error Response

When the API request fails at the FinPro level (before reaching AAs):

{
  "ver": "1.0.0",
  "status": "error",
  "error": {
    "code": "PROFILE_CHECK_FAILED",
    "message": "Failed to check profile existence",
    "details": "No active AAs found with profile API enabled"
  }
}

Common Error Scenarios

Error	Cause	Resolution
Missing mobileNumber	`mobileNumber` field not provided	Include required field in request body
Invalid mobile format	Mobile number is not 10 numeric digits	Validate format before API call
Missing userConsentId	`userConsentId` field not provided	Include required field in request body
Authentication failed	Invalid or missing auth headers	Verify credentials in admin portal
No active AAs found	No AAs have profile API enabled	Contact support to enable AAs

Use Cases

Smart AA Selection

Use the profile check results to intelligently guide users:

const profileResults = response.data;

// Find AAs where user is registered with linked accounts
const readyAAs = profileResults.filter(
  aa => aa.status === 'success' &&
       aa.registrationStatus === true &&
       aa.hasLinkedAccounts === true
);

// Find AAs where user is registered but needs to link accounts
const needsLinkingAAs = profileResults.filter(
  aa => aa.status === 'success' &&
       aa.registrationStatus === true &&
       aa.hasLinkedAccounts === false
);

// Find AAs where user needs to register
const needsRegistrationAAs = profileResults.filter(
  aa => aa.status === 'success' &&
       aa.registrationStatus === false
);

if (readyAAs.length > 0) {
  // Recommend these AAs for fastest onboarding
  showRecommendedAAs(readyAAs);
} else if (needsLinkingAAs.length > 0) {
  // User can use these AAs but needs to link accounts
  showLinkingFlow(needsLinkingAAs);
} else {
  // User needs to register with an AA
  showRegistrationFlow(needsRegistrationAAs);
}

Before initiating a consent request, verify the user is ready:

async function validateUserReadiness(mobileNumber, preferredAA) {
  const response = await checkProfile({
    mobileNumber,
    userConsentId: generateUUID(),
    aaId: [preferredAA]
  });

  const aaResult = response.data[0];

  if (aaResult.status !== 'success') {
    throw new Error(`Unable to verify profile: ${aaResult.status}`);
  }

  if (!aaResult.registrationStatus) {
    return { ready: false, reason: 'NOT_REGISTERED' };
  }

  if (!aaResult.hasLinkedAccounts) {
    return { ready: false, reason: 'NO_LINKED_ACCOUNTS' };
  }

  return { ready: true };
}

Usage Notes

Performance Considerations

Parallel Execution: All AA requests are executed in parallel using Promise.allSettled(), so the total response time is approximately equal to the slowest AA response (up to the timeout limit)
Timeouts: Each AA has a configurable timeout (typically 4-6 seconds). AAs that don’t respond within their timeout will return status: "timeout"
Caching: Consider caching results for a short duration (e.g., 5-15 minutes) as registration status doesn’t change frequently

Best Practices

Always Handle All Status Values: Your application should gracefully handle success, timeout, and failed statuses
Don’t Block on Timeouts: If some AAs timeout, you can still use the successful results to guide the user
Provide Fallback Options: If all AAs fail or timeout, provide a default flow that allows users to proceed
Mobile Number Validation: Validate the mobile number format client-side before calling the API
Selective Querying: If you already know which AA the user prefers, use the aaId filter to reduce unnecessary requests

Privacy Considerations

This API only returns registration status information
No personal data or financial information is exposed
Mobile numbers are used only for lookup purposes

Rate Limiting

This API is subject to rate limiting:

Metric	Value
Limit	1000 requests per time window
Remaining	Returned in `X-RateLimit-Remaining` header
Reset	Returned in `X-RateLimit-Reset` header

Monitor these headers to stay within allowed limits.

AA List - Get the list of integrated Account Aggregators
FIP Health - Check FIP health metrics across AAs
Consent Request V4 - Create consent requests after profile validation
Web Redirection Encryption - Generate AA redirect URLs for registration/consent flows

Consent Management

Data Management

Web Redirection

User Management

Miscellaneous

Overview

Key Features

Use Cases

Authentication

Request Body

Response

Success Response

Example Requests

Check All AAs

Check Specific AAs

Example Responses

Successful Multi-AA Response

Response Interpretation

Error Response

Common Error Scenarios

Use Cases

Smart AA Selection

Usage Notes

Performance Considerations

Best Practices

Privacy Considerations

Rate Limiting

Consent Management

Data Management

Web Redirection

User Management

Miscellaneous

​Overview

​Key Features

​Use Cases

​Authentication

​Request Body

​Response

​Success Response

​Example Requests

​Check All AAs

​Check Specific AAs

​Example Responses

​Successful Multi-AA Response

​Response Interpretation

​Error Response

​Common Error Scenarios

​Use Cases

​Smart AA Selection

​Pre-consent Validation

​Usage Notes

​Performance Considerations

​Best Practices

​Privacy Considerations

​Rate Limiting

​Related APIs

Overview

Key Features

Use Cases

Authentication

Request Body

Response

Success Response

Example Requests

Check All AAs

Check Specific AAs

Example Responses

Successful Multi-AA Response

Response Interpretation

Error Response

Common Error Scenarios

Use Cases

Smart AA Selection

Pre-consent Validation

Usage Notes

Performance Considerations

Best Practices

Privacy Considerations

Rate Limiting

Related APIs