AA BSA — Init Journey

Endpoint Overview

POST /api/v1/aa-bsa-journey/init

Description

The AA BSA Init Journey API kicks off the Account Aggregator (AA) powered Bank Statement Analysis (BSA) workflow. It creates a new journey session for a user and returns a client_id to track the session and a journey_url to redirect the user to — where they complete the RBI-regulated consent flow on the AA network.

This is always the first call in the AA BSA workflow. All subsequent steps — polling status, fetching statement data, and retrieving analysis insights — depend on the client_id returned here.

Key Benefits

Start a fully consent-driven bank data fetch in a single API call

Support both one-time loan underwriting and recurring loan monitoring consent types

Receive real-time journey updates via webhook without polling

Fully RBI-compliant — users retain control over their financial data at all times

Use Cases

Banking & Lending

Fintech & Payments

Enterprise & Compliance

Initiate bank statement collection as part of a digital personal or home loan application

Trigger loan monitoring consent for existing borrowers at disbursement

Replace manual PDF statement uploads with a frictionless AA-powered flow

Technical Implementation

Authentication

All API requests require authentication using your Finpass API credentials passed as request headers.

Obtain API Credentials: Register with Finpass to receive your X-API-KEY and X-API-SECRET.

Include in Requests: Add both keys to every request as HTTP headers.

Header	Value
`X-API-KEY`	Your assigned API Key
`X-API-SECRET`	Your assigned API Secret

Base URL: https://api.finpass.ai

Request Parameters

Request Headers

Header	Required	Description
`Content-Type`	Yes	Must be `application/json`
`X-API-KEY`	Yes	Your Finpass API Key
`X-API-SECRET`	Yes	Your Finpass API Secret

Request Body

Parameter	Type	Required	Description
`mobile_number`	string	Yes	The 10-digit mobile number of the user linked to their bank account(s) on the AA network
`consent_type`	string	No	Type of consent to request. Accepted values: `loan_underwriting` (default) or `loan_monitoring`
`redirect_url`	string	No	URL to redirect the user after completing the consent flow. Defaults to `https://finpass.ai/`
`webhook_url`	string	No	URL to receive a push callback when the journey status changes. Defaults to `https://finpass.ai/`

Example Request

{
  "mobile_number": "9876543210",
  "consent_type": "loan_underwriting",
  "redirect_url": "https://yourapp.com/callback",
  "webhook_url": "https://yourapp.com/webhook"
}

Process Response

Response Parameters

Parameter	Type	Description
`success`	boolean	Indicates whether the journey was initialised successfully
`message`	string	Human-readable status message
`data.client_id`	string	Unique session identifier for this journey — use this in all subsequent API calls
`data.journey_url`	string	URL to redirect the user to complete the AA consent flow
`data.status`	string	Current journey status — will be `initiated` at this stage
`data.consent_type`	string	The consent type for this session (`loan_underwriting` or `loan_monitoring`)
`data.expires_at`	string	Timestamp at which this session expires if the user does not complete consent (ISO 8601)

Example Successful Response

{
  "success": true,
  "message": "AA BSA journey initiated successfully",
  "data": {
    "client_id": "bsa_clnt_a1b2c3d4e5f6",
    "journey_url": "https://aa.finpass.ai/consent?token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.abc123xyz",
    "status": "initiated",
    "consent_type": "loan_underwriting",
    "expires_at": "2024-11-15T14:30:00Z"
  }
}

Possible Error Responses

Invalid Mobile Number

Invalid Consent Type

Unauthorized

{
  "success": false,
  "message": "Invalid mobile number. Please provide a valid 10-digit Indian mobile number.",
  "error_code": "INVALID_INPUT"
}

Returned when the provided mobile number is not a valid 10-digit Indian number.

Integration Best Practices

Security Recommendations

Store the client_id securely on your backend and never expose it in client-side code or publicly accessible URLs

Ensure your redirect_url and webhook_url are HTTPS endpoints and not publicly enumerable

Validate any webhook payload received at webhook_url before acting on status changes

Never pass the raw journey_url token to your frontend logs or analytics pipelines

User Experience Guidelines

Open journey_url in the same browser tab or a full-screen in-app WebView for the smoothest AA consent experience

Clearly communicate to the user what data will be accessed and for what purpose before redirecting

Set a sensible session timeout on your UI and prompt users to retry if the session expires before consent is granted

For mobile apps, use a deep link as the redirect_url to return users seamlessly after consent

Code Samples

cURL

Python

Node.js

Related APIs

AA BSA — Poll Status — Check the current state of an ongoing AA BSA journey session

AA BSA — Statement Result — Retrieve raw bank account and transaction data after journey completion

AA BSA — Analysis JSON — Fetch structured BSA insights including income, obligations, and risk flags

Compliance and Legal Considerations

This API operates within the RBI-regulated Account Aggregator (AA) ecosystem. You must be registered as a Financial Information User (FIU) with a licensed Account Aggregator before using this endpoint. Always present clear, accurate consent purpose language to the user before initiating the journey. Data fetched must only be used for the declared consent purpose (loan_underwriting or loan_monitoring) and must not be shared with unauthorised third parties. Comply with the RBI Master Direction on Account Aggregators and the Digital Personal Data Protection Act (DPDP), 2023. Access to this endpoint requires the AA_BSA_JOURNEY permission on your Finpass account.

Initialize

AA BSA — Init Journey#

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