AA Connect

This API is used when the same user needs more than one active consent, each for a different use-case. For example: Consent 1: Personal Finance Management (PFM) and Consent 2: F&O (for trading behavior insights). Both consents are created separately, but can be initiated in one single call using this API.

Request Body Parameters:

→ uniqueIdentifier (required): The primary identifier added at the time of subscription. It must be the exact same value used during the initial subscription.

→ aaCustId (optional): The user's Account Aggregator customer ID. Not needed when the customer ID is the user's mobile number followed by the AA handle; send it only when the AA customer ID must differ from the mobile number.

→ redirectUrl (required): URL where the customer is redirected after completing the consent journey. Send a full URL, for example "https://example.com/consent-done".

→ userSessionId (optional): Free-form session ID from your app, used to track the session that started the consent request.

→ consentTemplates (required): Array of strings. Names of the consent templates registered for you, for example ["YOUR_TEMPLATE_NAME"]. The field must be present with at least one template name.

Q. What is a consent template?

A consent template is a predefined configuration that specifies what financial data will be shared, why, and how often. It simplifies and standardizes the consent process for all users. This will be shared with FIU by the Wealthsync team.

Q. How is a consent template decided?

The consent template is created as per Sahamati guidelines and contains values as specified by ReBIT. Refer to the Sahamati templates here: https://sahamati.org.in/aa-fair-use-template-library/consent-template-id-ct008-personal-finance-management/

Q. What does the redirectUrl do?

The redirectUrl field will redirect the user to land on the URL provided in the value of this field after the consent journey has been completed.

Request Body Parameters:

         → <b>uniqueIdentifier</b> (required): The primary identifier added at the time of subscription. It must be the exact same value used during the initial subscription and MUST never change for this user.

         → <b>consentIds</b> (optional): Array of consent IDs (strings) to revoke. When omitted or empty, all existing consents of the user are included in the revoke request.

         → <b>redirectUrl</b> (optional): Full URL where the user is sent after the revoke is processed, for example "https://example.com/revoke-done".


        
         Q. What is consentId?
         
         The consentId uniquely identifies each consent given by the user to the Account Aggregator.
         A consent may hold multiple accounts, so all accounts within the consent will be considered for revocation.
         List of consent IDs to revoke. When consent IDs are not provided, all existing consents of the user will be included in revoke request to AA
         
         Q. Where do you get the consentId from?
         
         You receive consentId in the /webhook/consent notification and by calling 
         /pfm/api/v2/account-consents-latest API.
         A consent may hold multiple accounts, so all accounts within the consent will be considered for revocation.
         
         Q. What does the submit consent revoke request API do? 
         Will it stop sending the data associated with that account?
         
         The submit consent revoke request API returns a URL where the user has to go and confirm revocation.
         
         Once a consent is revoked:

         -> No new data will be fetched for accounts associated with that consent(s).

         -> Daily refresh for accounts associated with that consent(s) stops.

         -> Any new analytics or insights will not include this account.

         -> FIUs can expect to receive the /webhook/consent with status as "REVOKED" once the user confirms on AA.

         -> We support an optional configuration in Wealthsync to delete the data immediately after revoke.

            By default this is turned off, i.e., data is NOT deleted on revoke.

         -> Currently the revoke journey is supported only for consents created through some Account Aggregators.

This API initiates a single consent request with flexible parameters. Unlike submit-multi-consent-request, this is for creating one consent at a time with fine-grained control. After calling this API, the user is redirected to the AA (Account Aggregator) to approve the consent.

Request Body Parameters:

→ uniqueIdentifier (required): The primary identifier added at the time of subscription. It must be the exact same value used during the initial subscription and MUST never change for this user.

→ aaCustId (required): The user's Account Aggregator customer ID in the format: 10-digit mobile number + "@" + the AA handle.

Example: "9999999999@your-aa-handle"

→ templateName (required): The consent template name as configured in Wealthsync.

Example values: "BANK_STATEMENT_INSURANCE", "FNO_Activation", "BANK_STATEMENT_PERIODIC".

→ userSessionId (optional): A free-form session tracking ID from your app to track which user session

initiated the consent flow. Example: "sessionid123".

→ redirectUrl (required): The URL where the user will be redirected after completing the consent journey on AA.

→ pan (required): The user's 10-character PAN in the format AAAAA9999A.

→ consentDetails (required): Object with a required "fiTypes" array of strings — the list of financial information types

the user is consenting to share, for example {"fiTypes": ["DEPOSIT", "MUTUAL_FUNDS"]}. Supported fiTypes (upper case):

"DEPOSIT", "TERM_DEPOSIT", "RECURRING_DEPOSIT", "SIP", "EQUITIES", "MUTUAL_FUNDS", "ETF",

"IDR", "CIS", "AIF", "INVIT", "REIT", "LIFE_INSURANCE", "GENERAL_INSURANCE", "NPS",

"GSTR1_3B", "INSURANCE_POLICIES".

FAQ:

Q. What is a consent template?

A consent template is a predefined configuration that specifies what financial data will be shared, why, and how often. It simplifies and standardizes the consent process for all users. This will be shared with FIU by the Wealthsync team.

Q. How is a consent template decided?

The consent template is created as per Sahamati guidelines and contains values as specified by ReBIT. Refer to the Sahamati templates here: https://sahamati.org.in/aa-fair-use-template-library/consent-template-id-ct008-personal-finance-management/

Q. What does the redirectUrl do?

The redirectUrl field will redirect the user to land on the URL provided in the value of this field after the consent journey has been completed. Send a full URL, for example "https://example.com/consent-done".

Fetches data for all the accounts that a user has given across different consents.

Q. What is FI Request?

FI Request (Financial Information Request) is the request that your application sends to the Account Aggregator to retrieve financial data from the user’s linked Financial Information Providers (FIPs), such as banks, brokers, insurance companies, etc.

Q. Does an FIU do the FI request or is it handled by Wealthsync?

By default, Wealthsync performs a batch request every day for the FIUs. FIUs can opt out if they wish to handle the data refresh on their end.

Request Body Parameters:

→ uniqueIdentifier (required): The primary identifier added at the time of subscription. It must be the exact same value used during the initial subscription and MUST never change for this user.

This API triggers a Financial Information (FI) request for a specific individual account. Use this when you want to refresh data for just one account instead of all accounts.

Prerequisites: → First call any linked accounts API to get the fiDataId of the account. → Pass that fiDataId as the "accountId" parameter in this API.

Request Body Parameters:

→ uniqueIdentifier (required): The primary identifier added at the time of subscription. It must be the exact same value used during the initial subscription and MUST never change for this user.

→ accountId (required): The fiDataId of the specific account to fetch data for. To get the accountId (fiDataId) for different FI types, call the corresponding linked accounts API:

• Bank Savings/Current accounts: POST deposit/user-linked-accounts

• Fixed Deposits (FD): POST term-deposit/user-linked-accounts

• Recurring Deposits (RD): POST recurring-deposit/user-linked-accounts

• Mutual Funds: POST mutual-fund/user-linked-accounts

• ETFs: POST etf/user-linked-accounts

• Stocks: POST equities/user-linked-accounts

• Stocks + ETFs combined: POST equities-and-etfs/user-linked-accounts

• Life Insurance: POST life-insurance/user-linked-accounts

• General Insurance: POST general-insurance/user-linked-accounts

• NPS: POST nps/user-linked-accounts

This API returns the complete list of Financial Information Providers (FIPs) registered with the AA ecosystem. Each FIP includes fipId, fipName, supported fiTypes, enable status, entity logos/icons, and OTP length. Use this to show the user which banks, brokers, or insurers are available for linking.

Request Body Parameters:

→ uniqueIdentifier (required): The primary identifier added at the time of subscription. It must be the exact same value used during the initial subscription and MUST never change for this user.

This API returns the raw, unanalyzed financial data exactly as received from the Account Aggregator. Useful when you need the original data without any Wealthsync processing or analysis. The response includes Profile (holder info), Summary (account details), and Transactions.

Prerequisites: → First call any linked accounts API to get the fiDataId of the account. → Pass that fiDataId as the "accountId" parameter.

Request Body Parameters:

→ uniqueIdentifier (required): The primary identifier added at the time of subscription. It must be the exact same value used during the initial subscription and MUST never change for this user.

→ accountId (required): The fiDataId of the account whose raw data you want. To get the accountId (fiDataId) for different FI types, call the corresponding linked accounts API:

• Bank Savings/Current accounts: POST deposit/user-linked-accounts

• Fixed Deposits (FD): POST term-deposit/user-linked-accounts

• Recurring Deposits (RD): POST recurring-deposit/user-linked-accounts

• Mutual Funds: POST mutual-fund/user-linked-accounts

• ETFs: POST etf/user-linked-accounts

• Stocks: POST equities/user-linked-accounts

• Stocks + ETFs combined: POST equities-and-etfs/user-linked-accounts

• Life Insurance: POST life-insurance/user-linked-accounts

• General Insurance: POST general-insurance/user-linked-accounts

• NPS: POST nps/user-linked-accounts

→ fromDate (optional): Start date for the data range. Format: yyyy-MM-dd.

→ toDate (optional): End date for the data range. Format: yyyy-MM-dd.

This API returns the latest consent details for a specific account. The response includes consentId, consent start/expiry dates, consent mode, fetch type, fiTypes, data consumer/provider details, purpose, FI data range, data life, and frequency.

Use this to check the current consent status of an account or to get the consentId needed for the submit-consent-revoke-request API.

Request Body Parameters:

→ uniqueIdentifier (required): The primary identifier added at the time of subscription. It must be the exact same value used during the initial subscription and MUST never change for this user.

→ accountId (required): The fiDataId of the account whose consent details you want. To get the accountId (fiDataId) for different FI types, call the corresponding linked accounts API:

• Bank Savings/Current accounts: POST deposit/user-linked-accounts

• Fixed Deposits (FD): POST term-deposit/user-linked-accounts

• Recurring Deposits (RD): POST recurring-deposit/user-linked-accounts

• Mutual Funds: POST mutual-fund/user-linked-accounts

• ETFs: POST etf/user-linked-accounts

• Stocks: POST equities/user-linked-accounts

• Stocks + ETFs combined: POST equities-and-etfs/user-linked-accounts

• Life Insurance: POST life-insurance/user-linked-accounts

• General Insurance: POST general-insurance/user-linked-accounts

• NPS: POST nps/user-linked-accounts