Account Aggregator Flow | Credit Platform | Documentation

Some lenders need Account Aggregator consent before they can return a final or actionable offer. Hybrid Experience exposes that requirement through the offers polling API when it applies, so your product can show the borrower the right consent action without building the Account Aggregator journey yourself.

Gold Loan Hybrid does not include Account Aggregator right now. Gold Loan offers polling omits data.account_aggregator; use the Gold Loan offers and Hosted handoff responses instead.

Your product remains in control of the borrower UI until offer selection. Aarthik Labs creates the Account Aggregator handoff URL, tracks the consent session, receives the callback, reconciles lender state, and continues offer orchestration after the borrower returns.

Where AA Fits In Hybrid

Account Aggregator appears during offer discovery, before Hosted handoff, when the selected product/lender flow requires it.

Your app does not call a separate customer-facing Account Aggregator API. The offers endpoint tells you when AA is applicable and gives you the short-lived URL when it is ready.

When AA Appears

Your back-end discovers Account Aggregator readiness while polling:

GET /api/v1/hybrid/personal-loan/borrowers/{borrowerProviderID}/journey/offers
GET /api/v1/hybrid/loan-against-mutual-funds/borrowers/{borrowerProviderID}/journey/offers
GET /api/v1/hybrid/business-loan/borrowers/{borrowerProviderID}/journey/offers

This page applies when the offers response includes data.account_aggregator. The Gold Loan path uses the same polling cadence but does not return Account Aggregator.

If the response includes data.account_aggregator.url as a string, your app can show a borrower-facing action such as “Continue with bank statement consent” and open that URL.

If data.account_aggregator.url is null, Account Aggregator is applicable but the URL is not ready yet. Keep the borrower in a waiting state and poll again at data.polling.nextPoll.

If data.account_aggregator is not present, there is no actionable AA step for your product at that moment. Continue rendering offers, waiting states, or terminal states from the rest of the response.

AA URL Timing

The Account Aggregator URL is not returned immediately after offer fetch starts.

By default, Aarthik Labs waits until the second pre-window offer poll slot, 30 seconds after offer fetch starts, before returning the AA URL. This gives lenders time to share consent handles.

Read Offer Polling & Rate Limits for the full pre-AA and post-AA timing contract.

Response Shape

When AA is applicable, the offers response can include an account_aggregator object:

1 {
2   "data": {
3     "status": "OFFERED",
4     "polling": {
5       "shouldPoll": true,
6       "lastPoll": "2026-05-11T10:00:20.000Z",
7       "nextPoll": "2026-05-11T10:00:30.000Z"
8     },
9     "account_aggregator": {
10       "url": null,
11       "expires_at": null,
12       "lenders": ["AA Bank"]
13     },
14     "lenders": {
15       "AA Bank": {
16         "offers": [
17           {
18             "status": "OFFER_AWAITED",
19             "consentHandleAvailable": false,
20             "offerID": null
21           }
22         ]
23       }
24     }
25   },
26   "error": null
27 }

When the URL is ready:

1 {
2   "data": {
3     "account_aggregator": {
4       "url": "https://credit.aarthiklabs.com/lab/account-aggregator?token=...",
5       "expires_at": "2026-05-11T10:15:00.000Z",
6       "lenders": ["AA Bank"]
7     }
8   }
9 }

Important fields:

Field	Meaning
`data.account_aggregator.url`	Short-lived hosted AA URL. Open it only when it is a string.
`data.account_aggregator.expires_at`	Expiry time for the returned URL. `null` until the URL is generated.
`data.account_aggregator.lenders`	Borrower-visible lender names that currently need AA consent.
`data.polling.nextPoll`	Earliest time at which your back-end should poll offers again.

The account_aggregator object only contains url, expires_at, and lenders. It does not contain status, available, or poll_after_ms.

If the response also includes normal OFFER_RECEIVED offers, your UI can show those offers while also giving the borrower the option to complete AA for additional lender responses once the AA URL is ready.

Borrower Flow

What Your Product Should Build

Your product should build only the borrower-facing control points:

show a clear consent call-to-action when data.account_aggregator.url is present
open the latest returned url immediately
keep the borrower in a wait state when AA is applicable but url is null
poll again at data.polling.nextPoll
refresh offers after the borrower returns from consent
handle URL expiry by polling for a fresh URL
preserve already available offers while AA-backed lenders are still processing

Your product should not:

create or complete AA sessions directly
modify the AA URL
store the AA URL as a long-term resume link
expose the platform API key to the front-end
assume that every lender requires AA
assume that AA always produces an offer
poll faster than data.polling.nextPoll

How The Platform Handles AA

Behind the scenes, Aarthik Labs treats Account Aggregator as a sessionized flow:

the platform records lender consent requirements for the borrower journey
if multiple lenders need consent, the platform can consolidate eligible consent handles into one borrower AA run
the borrower completes consent through the hosted Account Aggregator surface
the callback completes the AA session
the platform dispatches approval or reconciliation back into lender orchestration
the offers endpoint reflects updated offer state once lenders respond

Your product does not need to model these internal sessions. It only needs to react to the polling response and open the returned AA URL when it is ready.

Offer Display With AA

The offers response can contain both immediate offers and lenders waiting for AA.

Your UI can:

show ready OFFER_RECEIVED offers immediately
show an Account Aggregator call-to-action when AA can unlock more lender responses
keep waiting for AA-backed lenders while preserving already available offers
refresh the offer list after the borrower returns from consent

Do not block the borrower from selecting an already available offer unless your own product policy requires waiting for all lender responses.

Return And Polling Behavior

After the borrower completes or exits the Account Aggregator surface, your app should return the borrower to your Hybrid UI and poll offers again.

Use this decision model:

Situation	Recommended behavior
Borrower completed consent	Poll offers again. Show a waiting state while lenders reconcile.
Borrower closed or exited consent	Poll offers again. If AA is still required, show the consent action again when a fresh URL is ready.
URL expired before opening	Poll offers again and use the latest URL.
AA URL is still `null`	Keep the borrower informed and continue polling at `data.polling.nextPoll`.
No offer is available after reconciliation	Show your no-offer state from the offers response.

The Account Aggregator callback and lender reconciliation are asynchronous. A successful borrower return does not always mean offers are immediately ready on the next poll.

Mobile App Handling

If your Hybrid journey runs inside a mobile app, open the AA URL in a browser or app-controlled surface that can preserve session state and return the borrower to your product.

Your mobile app should:

keep the Aarthik Labs API key server-side
open the AA URL without modifying it
allow the borrower to return to your Hybrid UI after consent
continue polling offers from your back-end after the borrower returns
support the same browser capabilities documented in the Hybrid mobile application guide

Read Mobile App Bridge and Mobile App Permissions for mobile-specific handling.

Some lender flows may also require monitoring consent after an offer path has progressed. The borrower-facing handling is similar: the platform prepares an Account Aggregator URL, the borrower completes consent in the hosted surface, and Aarthik Labs reconciles the callback before continuing lender progression.

For most Hybrid integrations, the most important AA behavior is pre-offer consent because it can unlock lender responses before the borrower selects an offer. Monitoring consent is handled later by the platform-managed journey surface when it applies.

Error And Retry Handling

Design your UI so AA failures do not trap the borrower.

Case	Recommended behavior
AA URL is null	Keep waiting and poll again at `data.polling.nextPoll`.
AA URL fails to open	Show a retry action and poll for a fresh URL.
Borrower abandons consent	Return to your Hybrid UI and let the offers response decide the next action.
Lender does not return an offer after AA	Show the lender state or no-offer state from the offers response.
Browser or webview blocks the AA surface	Move the borrower to a supported browser surface and retry with a fresh URL.
Offers poll returns `429`	Wait until the returned `polling.nextPoll` or `X-Aarthik-Next-Poll-At` time and retry.

Implementation Checklist

Your integration should:

show Account Aggregator only when the API returns an actionable AA URL
open the latest returned AA URL immediately
support browser or mobile webview behavior required for external consent screens
poll again after the borrower returns
keep the borrower in a clear waiting state while AA is processing
avoid storing AA URLs as long-term resume links
log journey ID, borrower provider ID, whether an AA URL was returned, and lender names for support
avoid logging full AA URLs unless your internal policy explicitly allows it
follow data.polling.nextPoll and handle 429 rate limits