> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.credit.aarthiklabs.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.credit.aarthiklabs.com/_mcp/server. # Account Aggregator Flow > Understand how Account Aggregator consent unlocks lender offers inside Hybrid Experience. 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. Business Loan offer discovery can return an Account Aggregator action when required. Continue using the same `journeyID`; `productType` on offer rows identifies the resulting product as `BUSINESS_LOAN` or `PERSONAL_LOAN`. 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. ```mermaid flowchart LR A["Borrower starts in your UI"] --> B["Your back-end starts or resumes Hybrid journey"] B --> C["Your back-end polls offers"] C --> D{"AA needed?"} D --> E["No: show available offers"] D --> F["Yes: wait for AA URL"] F --> G["Open Account Aggregator URL"] G --> H["Borrower completes consent"] H --> I["Aarthik Labs receives callback and reconciles lenders"] I --> C E --> J["Borrower selects offer"] J --> K["Your back-end requests Hosted URL"] K --> L["Open Hosted Experience"] ``` 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: ```txt 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](/documentation/hybrid-experience/integrations-guide/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: ```json { "data": { "status": "OFFERED", "polling": { "shouldPoll": true, "lastPoll": "2026-05-11T10:00:20.000Z", "nextPoll": "2026-05-11T10:00:30.000Z" }, "account_aggregator": { "url": null, "expires_at": null, "lenders": ["AA Bank"], "productType": "BUSINESS_LOAN" }, "lenders": { "AA Bank": { "offers": [ { "status": "OFFER_AWAITED", "consentHandleAvailable": false, "offerID": null } ] } } }, "error": null } ``` When the URL is ready: ```json { "data": { "account_aggregator": { "url": "https://credit.aarthiklabs.com/lab/account-aggregator?token=...", "expires_at": "2026-05-11T10:15:00.000Z", "lenders": ["AA Bank"], "productType": "BUSINESS_LOAN" } } } ``` 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.account_aggregator.productType` | Business Loan journeys: the product for the current AA action. Continue using the same `journeyID`. | | `data.polling.nextPoll` | Earliest time at which your back-end should poll offers again. | The `account_aggregator` object contains `url`, `expires_at`, and `lenders`, plus `productType` on composite Business Hybrid responses. 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 ```mermaid sequenceDiagram participant Borrower participant UI as Your Product UI participant Backend as Your Backend participant Hybrid as Hybrid Experience API participant AA as Account Aggregator Surface participant Lender as Lender Systems UI->>Backend: Refresh offer state Backend->>Hybrid: Poll offers Hybrid-->>Backend: account_aggregator.url is ready Backend-->>UI: Return AA action Borrower->>UI: Continue with consent UI->>AA: Open account_aggregator.url Borrower->>AA: Complete consent AA->>Hybrid: Callback with consent result Hybrid->>Lender: Dispatch consent approval Lender-->>Hybrid: AA-backed offer response UI->>Backend: Poll offers again Backend->>Hybrid: Read updated offers Hybrid-->>Backend: Lender-grouped offers Backend-->>UI: Show offers ``` ## 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 browser capabilities documented in the Mobile Applications docs Read [Mobile App Bridge](/documentation/common/mobile-applications/bridge) and [Mobile App Permissions](/documentation/common/mobile-applications/permissions) for mobile-specific handling. ## Monitoring Consent 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