> ## 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.
# The Account Link object
> Send a new merchant from your app to Ionic to sign up and connect to your platform.
```json When you create a link theme={null}
{
"id": "id_01JEXAMPLE2K8V4N9C6M1Q7R",
"object": "account_link",
"url": "https://…",
"expires_at": "2026-01-01T00:00:00Z"
}
```
```json When you retrieve a link theme={null}
{
"id": "id_01JEXAMPLE2K8V4N9C6M1Q7R",
"object": "account_link",
"outcome": "in_progress",
"connected_account_id": "mer_01JEXAMPLE2K8V4N9C6M1Q7R",
"onboarding_status": "…",
"payments_enabled": true,
"connection_status": "…",
"livemode": false
}
```
An Account Link (`alink_…`) is a single-use URL that takes one merchant through
Ionic's hosted signup, connection, and onboarding for one of your Connect
configurations. Your server creates the link, saves its ID, and redirects the
merchant's browser to the returned `url`. When the merchant finishes or leaves,
Ionic sends the browser to your `return_url` with `account_link` added to the
query. Your server then reads the link to find the merchant's ID. For the full
flow, see [Connect a new merchant](/guides/hosted-account-links).
For a new-merchant configuration, Ionic creates the merchant's account from
`prefill`. Your platform can act for that account only after its owner verifies
their email and agrees to connect, which creates the Connection. The merchant's
ID becomes the [connected account](/api-reference/connected-accounts) you select
with `Ionic-Account`. Both requests use your platform secret key, and the key's
mode decides whether the link is test or live.
## Attributes
### When you create a link
Account Link ID. Save it with your customer before redirecting; the return carries it back.
Single-use URL for the merchant's browser. Redirect to it right away; don't email or message it.
When `url` stops working, 30 minutes after creation.
### When you retrieve a link
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.
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`.
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.
Whether the Account can take payments in this link's mode right now.
Current status of `connection_id`: `active`, `suspended`, or `disconnected`. Present after consent.
See every field in the response of [Retrieve hosted onboarding progress](/api-reference/account-links/retrieve-hosted-onboarding-progress).
## Endpoints
| Endpoint | Use it for |
| - | - |
| [Create a hosted onboarding link](/api-reference/account-links/create-a-hosted-onboarding-link) | Create the link and get the `url` to redirect the merchant to. |
| [Retrieve hosted onboarding progress](/api-reference/account-links/retrieve-hosted-onboarding-progress) | Read how the visit ended, the merchant's ID and Connection, and whether payments are enabled. |
## Statuses
A link result reports three separate things. Check each one.
`outcome` describes how the merchant's visit went. It does not describe payment readiness.
| Outcome | Meaning |
| - | - |
| `in_progress` | The merchant has not 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. |
`onboarding_status` reports 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.
| Onboarding status | Meaning |
| - | - |
| `awaiting_consent` | Ionic created the account; the owner has not 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 cannot continue. |
`payments_enabled` is `true` when the account can take payments in the link's
mode right now. `connection_status` is `active`, `suspended`, or
`disconnected`, and is present after consent.
## Rules
* The `url` works once and expires 30 minutes after creation. Redirect to it
right away. Do not email or message it, because link previews can open it first.
* Send an `Idempotency-Key` on create. Retrying with the same key and body
returns the same link. The same key with a different body returns `409`. See
[Idempotency](/api-reference/idempotency).
* The return tells you which link to look at, not what happened. Look up the
`account_link` value in your own records, then save `connected_account_id`
and `connection_id` from the API response, never from the browser.
* To continue an expired or abandoned visit, create a new link with
`resume_from` set to the earlier link ID.
* Subscribe to `account.updated` for later changes to `payments_enabled`. See
[Webhooks for platforms](/guides/connect-webhooks).
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.