A valid request URL is required to generate request examples{
"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"
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}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.
A valid request URL is required to generate request examples{
"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"
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}Authorizations
A Platform Connect secret key (sk_…) sent as Authorization: Bearer <key>.
Headers
A unique key that makes a retry return the original result.
1 - 255Body
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.
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:<port>, http://127.0.0.1:<port>, and
http://[::1]:<port> 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.
Published revision to use. Omit it to use the configuration's current published revision. The response reports the revision used.
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.
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.
^alink_[0-9A-Za-z]{24}$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.
Show child attributes
Show child attributes
Response
The link. Save id, then redirect the browser to url.
Account Link ID. Save it with your customer before redirecting; the return carries it back.
^alink_[0-9A-Za-z]{24}$account_link When url stops working, 30 minutes after creation.
The configuration this link uses.
The configuration revision this link uses.
Single-use URL for the merchant's browser. Redirect to it right away; don't email or message it.
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.