Account Aggregator V2 - Init

Endpoint Overview

POST /api/v1/account-aggregator-v2/init

Description

The Account Aggregator V2 Init API initiates the account aggregation consent flow for financial data sharing. This endpoint creates a secure session for users to connect their financial accounts through the Account Aggregator (AA) ecosystem, enabling regulated and consent-based financial data sharing between Financial Information Providers (FIPs) and Financial Information Users (FIUs). The API generates a unique client session and returns a redirect URL for users to complete the consent journey through a secure interface.

Key Benefits

Consent-Based Data Access: Enable secure, user-consented access to financial data across multiple institutions

Regulatory Compliance: Fully compliant with RBI's Account Aggregator framework for financial data sharing

Streamlined Onboarding: Single API call to initiate the entire account aggregation consent flow

Multi-Institution Support: Access data from multiple banks and financial institutions through a single integration

Use Cases

Lending & Credit

Wealth Management

Personal Finance

Loan Underwriting: Access comprehensive financial history for accurate credit assessment and faster loan approvals

Credit Line Management: Monitor real-time cash flows to offer dynamic credit limits based on actual financial behavior

Risk Assessment: Analyze transaction patterns across multiple accounts for better risk profiling

Technical Implementation

Authentication

All API requests require authentication using a JWT Bearer token. Authentication follows these steps:

Obtain API Credentials: Register with Surepass to receive your API key.

Generate JWT Token: Use your API key to generate a JWT token.

Include in Requests: Add the token to the Authorization header as Bearer TOKEN.

Different authentication tokens are used for sandbox and production environments:

Sandbox: https://sandbox.surepass.app

Production: https://kyc-api.surepass.app

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token for API authentication. Format: `Bearer YOUR_JWT_TOKEN`
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
mobile_number	string	Yes	10-digit mobile number of the user initiating the account aggregation process
pan_number	string	No	PAN (Permanent Account Number) of the user for additional verification
email	string	No	Email address of the user for communication and notifications
input_redirect_url	string	No	Custom redirect URL where users will be sent after completing the consent flow
consent_type	string	Yes	Type of consent being requested

Example Request

{
  "mobile_number": "9999000000",
  "pan": "",
  "email": "",
  "input_redirect_url": "",
  "consent_type": "loan_underwriting"
}

Process Response

Response Parameters

Parameter	Type	Description
data	object	Contains the response data for the initiated session
data.client_id	string	Unique identifier for the account aggregator session
data.mobile_number	string	Echo of the mobile number used to initiate the session
data.pan_number	string/null	Echo of the PAN number if provided, null otherwise
data.email_id	string/null	Echo of the email address if provided, null otherwise
data.redirect_url	string	URL where the user should be redirected to complete the consent flow
status_code	integer	HTTP status code of the response
success	boolean	Indicates whether the request was successful
message	string	Human-readable message describing the result
message_code	string	Machine-readable code for the response status

Example Successful Response

{
  "data": {
    "client_id": "account_aggregator_v2_oOxRfypvwDqMjti",
    "mobile_number": "9999000000",
    "pan_number": null,
    "email_id": null,
    "redirect_url": "https://webvwlive.finvu.in/onboarding?fi=eGZ+eH1+H3N4Zg==&reqdatemQsNSzMbK58GdvaE9b1Ijzzo8dg=="
  },
  "status_code": 200,
  "success": true,
  "message": "Success",
  "message_code": "success"
}

Integration Best Practices

Security Recommendations

Token Management: Store JWT tokens securely and never expose them in client-side code or version control

HTTPS Only: Always use HTTPS for API calls to ensure data encryption in transit

Session Handling: Store the client_id securely for tracking the user's consent journey

Input Validation: Validate mobile numbers and email formats before sending API requests

User Experience Guidelines

Clear Communication: Inform users about the data sharing process and obtain explicit consent before initiating

Progress Indicators: Show loading states while the API call is being processed

Error Handling: Provide clear, actionable error messages if the initialization fails

Redirect Flow: Ensure smooth transition to the redirect URL and handle return callbacks appropriately

Code Samples

cURL

Python

Node.js

Related APIs

Account Aggregator V2 - Status: Check the current status of an account aggregation session and retrieve consent details

Account Aggregator V2 - Fetch Data: Retrieve the aggregated financial data after user consent is obtained

Account Aggregator V2 - Revoke Consent: Allow users to revoke previously granted data sharing consent

Compliance and Legal Considerations

This API operates under the RBI's Account Aggregator framework. Ensure compliance with applicable data protection regulations including the Information Technology Act, 2000, and upcoming Personal Data Protection Bill. Obtain explicit user consent before initiating data aggregation and maintain audit logs of all consent actions. Data retention and sharing must comply with RBI guidelines for Account Aggregators and Financial Information Users.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/account-aggregator-v2/init' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "mobile_number": "9999000000", "consent_type": "loan_underwriting" }'

{ "data": { "client_id": "account_aggregator_v2_oOxRfypvwDqMjti", "mobile_number": "9999000000", "pan_number": null, "email_id": null, "redirect_url": "https://webvwlive.finvu.in/onboarding?fi=eGZ+eH1+H3N4Zg==&reqdatemQsNSzMbK58GdvaE9b1Ijzzo8dg==" }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Initialize

Account Aggregator V2 - Init

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Integration Best Practices

Code Samples

Request

Responses

Initialize

Account Aggregator V2 - Init#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Integration Best Practices#

Code Samples#

Request

Responses

Account Aggregator V2 - Init

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Integration Best Practices

Code Samples