> ## Documentation Index > Fetch the complete documentation index at: https://docs.ionicfi.com/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve hosted onboarding progress > Returns the current state of an Account Link: how the merchant's visit ended, which Account and Connection it produced, and the merchant's onboarding and payment readiness. Call it when the merchant returns. Look up the `account_link` value from your return URL in your saved records first, and reject IDs you didn't create. Then save `connected_account_id` and `connection_id` from this response, never from the browser. This read never depends on the browser, so it also works after a lost return or a closed tab. A return doesn't mean payments are enabled: check `payments_enabled` and `onboarding_status`, and subscribe to `account.updated` for later changes. Use a key in the same mode that created the link. ## OpenAPI ````yaml /openapi/connect.yaml get /account_links/{id} openapi: 3.0.3 info: title: Ionic Connect API version: '2026-09-02' description: > Connect an existing Ionic Account, launch hosted onboarding for a new or existing merchant, and read Accounts that have granted Platform access. These endpoints require the Platform's Connect secret key. The key and its test or live mode identify the Platform; `Ionic-Account` is not accepted on this surface. Account Authorization uses a browser redirect with PKCE. Store the original `state` and PKCE verifier before sending the Account holder to the returned `authorization_url`, then validate `state` and exchange the one-time code after Ionic redirects back. Account Links use a separate, simple return: save each link ID against your customer, then retrieve current status with your Platform credential when Ionic returns that ID. servers: - url: '{baseUrl}/v1' variables: baseUrl: default: https://api.ionicfi.com description: API base URL for your environment. security: - secretKey: [] tags: - name: Account Links description: Launch hosted onboarding and retrieve current progress. - name: Account Authorizations description: Ask an existing Account to authorize a Platform. - name: Connected Accounts description: Accounts that currently authorize the Platform. paths: /account_links/{id}: get: tags: - Account Links summary: Retrieve hosted onboarding progress description: > Returns the current state of an Account Link: how the merchant's visit ended, which Account and Connection it produced, and the merchant's onboarding and payment readiness. Call it when the merchant returns. Look up the `account_link` value from your return URL in your saved records first, and reject IDs you didn't create. Then save `connected_account_id` and `connection_id` from this response, never from the browser. This read never depends on the browser, so it also works after a lost return or a closed tab. A return doesn't mean payments are enabled: check `payments_enabled` and `onboarding_status`, and subscribe to `account.updated` for later changes. Use a key in the same mode that created the link. operationId: retrieveAccountLink parameters: - $ref: '#/components/parameters/AccountLinkId' responses: '200': description: Current state of the link for your Platform and key mode. content: application/json: schema: $ref: '#/components/schemas/AccountLinkResult' example: id: alink_8Fq2LmV0cX4nR7tYp1KsW3dA object: account_link version: 4 version_scope: account_link external_reference: practice_4281 livemode: true expires_at: '2026-10-07T18:00:00Z' outcome: merchant_actions_completed requested_configuration: id: ccfg_4kT9mQ2xV7nB1cR8pL5wZ3yH revision: 3 configuration_id: ccfg_4kT9mQ2xV7nB1cR8pL5wZ3yH configuration_revision: 3 pricing_offer_id: poff_o1tg6XTDQ3v4KNDEiQrSjB5w connected_account_id: mer_7Hk2Pq9Lm4Xw1R connection_id: conn_3Rv8Kd1Nq6Lp0T application_id: app_CLAIMEDAPPLY000000000A connection_status: active onboarding_status: under_review payments_enabled: false existing_terms_retained: false '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: >- `ACCOUNT_LINK_NOT_FOUND`: no link with this ID belongs to your Platform in this key's mode. content: application/json: schema: $ref: '#/components/schemas/Error' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' security: - secretKey: - platform:act components: parameters: AccountLinkId: name: id in: path required: true description: Account Link ID saved against your customer before redirect. schema: type: string pattern: ^alink_[0-9A-Za-z]{24}$ schemas: AccountLinkResult: type: object additionalProperties: false required: - id - object - version - version_scope - external_reference - livemode - expires_at - outcome - requested_configuration - payments_enabled properties: id: type: string pattern: ^alink_[0-9A-Za-z]{24}$ description: Account Link ID. object: type: string enum: - account_link version: type: integer format: int64 description: >- Increases each time this result changes. Use it to ignore out-of-order webhook deliveries. version_scope: type: string description: 'The sequence `version` belongs to: `account_link`.' external_reference: type: string description: The `external_reference` you sent, or an empty string. livemode: type: boolean description: '`true` for a live-mode link.' expires_at: type: string format: date-time description: >- When the merchant's visit stops accepting actions. Before the merchant opens `url`, this is the link's expiry. outcome: type: string enum: - in_progress - merchant_actions_completed - cancelled - incomplete - expired - blocked description: > How the merchant's visit went. It describes the visit, not payment readiness. - `in_progress`: the merchant hasn't finished or left yet. - `merchant_actions_completed`: the merchant did everything this visit needed: connected, and signed the application if the configuration includes one. Payments may still be under review. - `cancelled`: the merchant left before connecting. - `incomplete`: the merchant connected, then left before finishing. - `expired`: the link or visit expired first. - `blocked`: the Account or Connection can no longer be used, or the application was closed. requested_configuration: $ref: '#/components/schemas/ConnectConfigurationReference' configuration_id: type: string description: >- The configuration whose terms apply to the merchant's application. Differs from `requested_configuration` when `existing_terms_retained` is `true`. configuration_revision: type: integer format: int64 description: Revision of `configuration_id`. pricing_offer_id: type: string description: Pricing on the merchant's application. connected_account_id: type: string description: > The merchant's Account ID. Send it as the `Ionic-Account` header on requests you make for the merchant. For a new-merchant configuration it's present from creation, before consent, and doesn't by itself let you act for the merchant; wait for `connection_id`. connection_id: type: string description: >- The Connection that grants your Platform access. Present after the owner consents. application_id: type: string description: The merchant's application, for configurations that include one. connection_status: type: string description: | Current status of `connection_id`: `active`, `suspended`, or `disconnected`. Present after consent. onboarding_status: type: string description: > Where the merchant is in onboarding. For connect-only configurations it is absent once the owner consents. Read the current value rather than inferring it from the return. - `awaiting_consent`: Ionic created the Account; the owner hasn't clicked **Connect** yet. - `collecting`: the merchant is filling in the application. - `awaiting_signature`: submitted, waiting for the merchant to sign. - `under_review`: signed; Ionic is reviewing it. - `approved`: the Account can take live payments, including a merchant who already could. - `closed`: the application was closed and can't continue. payments_enabled: type: boolean description: Whether the Account can take payments in this link's mode right now. existing_terms_retained: type: boolean description: >- `true` when the merchant keeps pricing they already have with Ionic instead of this configuration's terms, for example a merchant who already takes live payments. Error: type: object required: - error properties: error: type: object description: Details about the error. required: - code - message properties: code: type: string message: type: string ConnectConfigurationReference: type: object description: A published Connect configuration and the revision of it that applies. additionalProperties: false required: - id - revision properties: id: type: string description: Connect configuration ID. revision: type: integer format: int64 description: Published revision. responses: Unauthorized: description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: The credential cannot perform this Connect operation. content: application/json: schema: $ref: '#/components/schemas/Error' RateLimited: description: Too many requests. content: application/json: schema: $ref: '#/components/schemas/Error' InternalError: description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: secretKey: type: http scheme: bearer description: >- A Platform Connect secret key (`sk_…`) sent as `Authorization: Bearer `. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.