Account Aggregator - Init

Endpoint Overview

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

Description

The Account Aggregator 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 API Key and API Secret headers. Authentication follows these steps:

Obtain API Credentials: Register with Finpass to receive your x-api-key and x-api-secret.

Include in Requests: Add both credentials as headers in every API request.

Header	Description
`x-api-key`	Your unique API key provided by Finpass upon registration.
`x-api-secret`	Your API secret paired with the API key for authenticated access.

Production: https://api.finpass.ai

Request Parameters

Request Headers

Header	Required	Description
x-api-key	Yes	Your unique API key for authentication. Provided by Finpass during registration.
x-api-secret	Yes	Your API secret paired with the API key. Provided by Finpass during registration.
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
consent_type	string	Yes	Type of consent being requested (e.g., "loan_underwriting")
webhook_url	string	No	URL to receive webhook notifications for consent status updates
redirect_url	string	No	URL to redirect the user after the consent journey is completed

Example Request

{
    "mobile_number": "9999000000",
    "pan": "",
    "email": "",
    "consent_type": "loan_underwriting",
    "webhook_url": "",
    "redirect_url": ""
}

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": "aa_6989cbcf_a136a4017",
        "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"
}

Possible Error Responses

Authentication Error

Validation Error

Rate Limit Error

{
    "status_code": 401,
    "success": false,
    "message": "Unauthorized access. Invalid or missing API credentials.",
    "message_code": "unauthorized"
}

This error occurs when the x-api-key or x-api-secret headers are missing, invalid, or do not match. Verify your credentials and retry the request.

Integration Best Practices

Security Recommendations

Secure Credential Storage: Store your x-api-key and x-api-secret securely using environment variables or a secrets manager (e.g., AWS Secrets Manager, HashiCorp Vault). Never hardcode credentials in source code or expose them in client-side applications.

HTTPS Only: Always use HTTPS endpoints to ensure data transmission is encrypted

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

Credential Rotation: Periodically rotate your API key and secret. Coordinate with Finpass support to regenerate credentials and update them across your deployments.

Audit Logging: Maintain comprehensive logs of all API calls for compliance and security auditing purposes

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

Privacy Assurance: Inform users about data retention policies and how their financial information will be protected

Code Samples

cURL

Python

Node.js

Related APIs

Account Aggregator - Fetch JSON Report: Retrieve the aggregated financial data in JSON format after user consent is obtained.

Account Aggregator - Fetch PDF Report: Retrieve the aggregated financial data as a PDF report after user consent is obtained.

Account Aggregator - Refresh Data: Refresh the previously fetched aggregated financial data for an active consent session.

Compliance and Legal Considerations

Account Aggregator Framework Compliance: This API operates within India's Account Aggregator framework regulated by the Reserve Bank of India (RBI). Ensure your implementation complies with all RBI guidelines for data handling and customer consent.

Customer Consent: Always obtain explicit customer consent before accessing their financial data through the Account Aggregator network. Consent must be informed, specific, and revocable.

Data Retention: Follow data minimization principles and retain financial data only for the duration necessary to fulfill the stated purpose. Implement secure data deletion processes.

Privacy Regulations: Comply with applicable data protection regulations including the Digital Personal Data Protection Act (DPDPA) when handling customer financial information.

Purpose Limitation: Use the fetched financial data only for the specific purpose disclosed to and consented by the customer (e.g., loan underwriting or monitoring).

Initialize

Account Aggregator - Init#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses