> ## Documentation Index
> Fetch the complete documentation index at: https://docs.centryos.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Linked Account Widget

> Generate a shareable link that lets end users link their bank, card, or international bank account.

## Overview

Create a **linked account widget**—a shareable URL that directs end users to link their payout method (bank, card, or international bank). Use this when you want users to add a linked account without initiating a withdrawal. The integration obtains an application token and URL, then redirects users to complete account linking.

## Prerequisites

* Valid access token

## Endpoint

* **POST** `{{LIQUIDITY_URL}}/v1/ext/application-token`
* Auth: Bearer `{{accessToken}}`

## Request

```bash theme={null}
curl -X POST "{{LIQUIDITY_URL}}/v1/ext/application-token" \
  -H "Authorization: Bearer {{accessToken}}" \
  -H "Content-Type: application/json" \
  -d '{
    "tokenType": "ACCOUNT_WIDGET",
    "currency": "USD",
    "useLinkAccountPath": true,
    "redirectTo": "https://your-merchant.com/thank-you",
    "extra": {
      "withdrawalSource": "MERCHANT_WALLET",
      "counterparty": {
        "firstName": "Jane",
        "lastName": "Doe",
        "email": "jane@example.com"
      }
    }
  }'
```

### Request Body Fields

| Field                          | Type    | Description                                                           | Required |
| ------------------------------ | ------- | --------------------------------------------------------------------- | -------- |
| `tokenType`                    | string  | Must be `ACCOUNT_WIDGET`                                              | Yes      |
| `currency`                     | string  | Currency code (e.g., `USD`)                                           | Yes      |
| `useLinkAccountPath`           | boolean | When `true`, the generated URL goes directly to the link-account flow | Yes      |
| `redirectTo`                   | string  | URL to redirect the user after they complete account linking          | No       |
| `extra`                        | object  | Additional options                                                    | No       |
| `extra.withdrawalSource`       | string  | Must be `MERCHANT_WALLET`                                             | No       |
| `extra.counterparty`           | object  | Counterparty info for the linked account                              | No       |
| `extra.counterparty.firstName` | string  | Counterparty first name                                               | No       |
| `extra.counterparty.lastName`  | string  | Counterparty last name                                                | No       |
| `extra.counterparty.email`     | string  | Counterparty email                                                    | No       |

## Response (200)

```json theme={null}
{
  "data": {
    "url": "https://sandbox.accounts.centryos.xyz/link-account/sATkWLobCODYbvJCC7asBYuCFVyvVI?t=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "application": {
      "id": "4c1c5cc2-2ada-4ecd-a49c-9db1d0094079",
      "token": "sATkWLobCODYbvJCC7asBYuCFVyvVI",
      "tokenType": "ACCOUNT_WIDGET",
      "expiredAt": "2027-02-07T13:07:54.520Z",
      "valid": true
    },
    "customerId": "MDMxNzMxZmQtOTAzMC00OTIxLTk3NmQtNjk3ZWU3Y2JjYzZi"
  },
  "success": true
}
```

### Response Fields

| Field                        | Type    | Description                                    |
| ---------------------------- | ------- | ---------------------------------------------- |
| `data.url`                   | string  | Shareable linked-account widget URL            |
| `data.application.id`        | string  | Application ID                                 |
| `data.application.token`     | string  | Application token                              |
| `data.application.tokenType` | string  | Token type: `ACCOUNT_WIDGET`                   |
| `data.application.expiredAt` | string  | Expiration datetime (ISO 8601)                 |
| `data.application.valid`     | boolean | Whether the token is currently valid           |
| `data.customerId`            | string  | Customer/entity ID associated with this widget |

## Important: Append `entityId` to the URL

Before redirecting your end user to the widget, you **must** add the `customerId` from the response to the URL as the `entityId` query parameter.

**Example:** If the response returns:

* `url`: `https://sandbox.accounts.centryos.xyz/link-account/sATkWLobCODYbvJCC7asBYuCFVyvVI?t=...`
* `customerId`: `MDMxNzMxZmQtOTAzMC00OTIxLTk3NmQtNjk3ZWU3Y2JjYzZi`

Then the final URL you redirect the user to should be:

```
https://sandbox.accounts.centryos.xyz/link-account/sATkWLobCODYbvJCC7asBYuCFVyvVI?t=...&entityId=MDMxNzMxZmQtOTAzMC00OTIxLTk3NmQtNjk3ZWU3Y2JjYzZi
```

Use `entityId={{customerId}}` — append `&entityId=` followed by the `customerId` value from the response. Without this, the widget cannot associate the linked account with the correct customer.

## Usage Flow

1. **Create linked account widget**: Call this endpoint with `useLinkAccountPath: true`.
2. **Append entityId**: Add `entityId={{customerId}}` to the returned `url`.
3. **Share or redirect**: Redirect your end user to the final URL so they can link their bank, card, or international bank account.
4. **Post-linking**: After linking, users can be redirected to your `redirectTo` URL, and you can use the linked account for payouts via [Withdraw to Linked Account](/guides/withdraw-to-linked-account).

## Notes

* `useLinkAccountPath: true` ensures the URL goes directly to the account-linking flow (no withdrawal step).
* Store `customerId` and use it to append `entityId` before redirecting users.
* The link expires at `data.application.expiredAt`; create new links as needed.
* Use `redirectTo` to send users to a thank-you or confirmation page after linking.