> ## 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. # Create a hosted onboarding link > Creates an Account Link: a single-use URL that takes one merchant through Ionic's hosted signup, connection, and onboarding for one of your Connect configurations. Save the returned `id` with your customer record, then redirect the merchant's browser to `url` right away. The URL works once and expires 30 minutes after creation. Don't email or message it, because link previews can open it first. When the merchant finishes or leaves, Ionic sends their browser to `return_url` with `account_link` added to the query. Look that ID up in your saved records and read the result with `GET /v1/account_links/{id}`. For a new-merchant configuration, Ionic creates the merchant's Account from `prefill` and returns its ID as `account`. Your Platform can act for that Account only after its owner verifies their email and clicks **Connect**, which creates the Connection. Retrying with the same `Idempotency-Key` and body returns the same link. To continue an expired or abandoned visit, create a new link with `resume_from`. ## OpenAPI ````yaml /openapi/connect.yaml post /account_links 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: post: tags: - Account Links summary: Create a hosted onboarding link description: > Creates an Account Link: a single-use URL that takes one merchant through Ionic's hosted signup, connection, and onboarding for one of your Connect configurations. Save the returned `id` with your customer record, then redirect the merchant's browser to `url` right away. The URL works once and expires 30 minutes after creation. Don't email or message it, because link previews can open it first. When the merchant finishes or leaves, Ionic sends their browser to `return_url` with `account_link` added to the query. Look that ID up in your saved records and read the result with `GET /v1/account_links/{id}`. For a new-merchant configuration, Ionic creates the merchant's Account from `prefill` and returns its ID as `account`. Your Platform can act for that Account only after its owner verifies their email and clicks **Connect**, which creates the Connection. Retrying with the same `Idempotency-Key` and body returns the same link. To continue an expired or abandoned visit, create a new link with `resume_from`. operationId: createAccountLink parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAccountLinkRequest' examples: newMerchant: summary: New merchant value: configuration_id: ccfg_4kT9mQ2xV7nB1cR8pL5wZ3yH external_reference: practice_4281 return_url: https://yourapp.com/settings/payments/done prefill: business_name: Bayview Dental contact_first_name: Ana contact_last_name: Lee contact_email: ana@bayviewdental.com contact_phone: '+14155550100' address_line1: 1 Harbor Way city: San Francisco state: CA postal_code: '94105' country: US existingAccount: summary: Existing Ionic merchant value: configuration_id: ccfg_8Hq3Lm0Wn5Tb2Xc7Rv4Kp9Dz external_reference: practice_4281 return_url: https://yourapp.com/settings/payments/done resume: summary: Continue an earlier visit value: configuration_id: ccfg_4kT9mQ2xV7nB1cR8pL5wZ3yH external_reference: practice_4281 return_url: https://yourapp.com/settings/payments/done resume_from: alink_8Fq2LmV0cX4nR7tYp1KsW3dA localTest: summary: Test mode on your machine value: configuration_id: ccfg_2Tn6Wq8Lr1Vx5Mb9Kc3Hp7Yd return_url: http://localhost:3000/settings/payments/done responses: '201': description: The link. Save `id`, then redirect the browser to `url`. content: application/json: schema: $ref: '#/components/schemas/AccountLinkLaunch' example: id: alink_8Fq2LmV0cX4nR7tYp1KsW3dA object: account_link expires_at: '2026-10-06T18:30:00Z' configuration_id: ccfg_4kT9mQ2xV7nB1cR8pL5wZ3yH configuration_revision: 3 account: mer_7Hk2Pq9Lm4Xw1R url: >- https://app.ionicfi.com/connect/l/alink_8Fq2LmV0cX4nR7tYp1KsW3dA#launch=iclaunch_9L7CdjG4hvWp1hCuec7q8zQG '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': description: > `HOSTED_CONNECT_STATE_CONFLICT`: the `Idempotency-Key` was already used with a different body, or the visit in `resume_from` changed. Use a new key. `HOSTED_PROGRAM_UNAVAILABLE`: your Platform Program doesn't allow this onboarding flow. `PLATFORM_ACCOUNT_LIMIT_REACHED`: your Program can't create another managed test Account. content: application/json: schema: $ref: '#/components/schemas/Error' '422': $ref: '#/components/responses/InvalidAccountLink' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' security: - secretKey: - platform:act components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: true description: A unique key that makes a retry return the original result. schema: type: string minLength: 1 maxLength: 255 schemas: CreateAccountLinkRequest: type: object additionalProperties: false required: - configuration_id - return_url properties: configuration_id: type: string description: > ID of a published Connect configuration (`ccfg_…`) in the same mode as your key. The configuration sets what the merchant does (connect only, or connect and apply for live processing at your pricing), which permissions you get, and whether new or existing Accounts can use it. Copy it from **Connect › Onboarding › Links** in the Dashboard. configuration_revision: type: integer format: int64 description: > Published revision to use. Omit it to use the configuration's current published revision. The response reports the revision used. external_reference: type: string description: | Your own ID for this customer, 1 to 256 characters. Ionic returns it when you retrieve the link and on `account_link.*` events. Ionic doesn't interpret it and doesn't require it to be unique. return_url: type: string format: uri description: > Where Ionic sends the merchant's browser when this visit ends, whether they finished or left. It can be any path and query on an origin you approved under **Connect › Domains › Redirect domains**, so each link can return to a different page. For example, `https://yourapp.com/settings/payments/done?practice=4281`. Ionic adds `account_link={id}` to the query and keeps your other query values; the query may be re-encoded, so don't rely on parameter order. `account_link` is reserved and overwrites any value you set. Live mode requires HTTPS and rejects loopback addresses. Test mode also accepts `http://localhost:`, `http://127.0.0.1:`, and `http://[::1]:` without registering them. Fragments and `user:password@` are rejected; write internationalized hostnames in punycode. Ionic checks the origin again when the merchant returns, so removing a redirect domain also stops returns to it. resume_from: type: string pattern: ^alink_[0-9A-Za-z]{24}$ description: > ID of an earlier link to continue, for example after it expired or the merchant left. The merchant resumes with the same Account, Connection, and application. Send the same `configuration_id` and `external_reference`, a new `Idempotency-Key`, and no `prefill`. `return_url` can differ from the earlier link's. prefill: type: object additionalProperties: type: string description: | Business and owner details as string values. For a configuration that creates new Accounts, these fields are required, and Ionic creates the merchant's Account from them: `business_name` (up to 200 characters), `contact_first_name`, `contact_last_name`, `contact_email` (the owner verifies this address), `contact_phone` (such as `+14155550100`), `address_line1`, `city`, `state`, `postal_code`, and `country` (`US`). `address_line2` is optional. A missing field returns `422` naming it. Other fields, and any prefill for existing-Account configurations, must be listed in the configuration's allowed prefill fields. The owner names are accepted only for new-Account configurations. Don't send `prefill` with `resume_from`. AccountLinkLaunch: type: object additionalProperties: false required: - id - object - expires_at - configuration_id - configuration_revision - url properties: id: type: string pattern: ^alink_[0-9A-Za-z]{24}$ description: >- Account Link ID. Save it with your customer before redirecting; the return carries it back. object: type: string enum: - account_link expires_at: type: string format: date-time description: When `url` stops working, 30 minutes after creation. configuration_id: type: string description: The configuration this link uses. configuration_revision: type: integer format: int64 description: The configuration revision this link uses. account: type: string description: > For a new-merchant configuration, the Account Ionic created from `prefill`. It isn't connected to your Platform until the owner verifies their email and clicks **Connect**. url: type: string format: uri description: >- Single-use URL for the merchant's browser. Redirect to it right away; don't email or message it. Error: type: object required: - error properties: error: type: object description: Details about the error. required: - code - message properties: code: type: string message: type: string responses: BadRequest: description: >- Invalid fields, PKCE data, callback data, permissions, or pagination cursor. content: application/json: schema: $ref: '#/components/schemas/Error' 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' InvalidAccountLink: description: >- `HOSTED_CONNECT_INVALID`: a field is invalid, such as an unpublished configuration, a `return_url` on an unapproved origin, or missing `prefill`. The message names the field and rule. 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.