> ## 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.

# Link Bank Account

> Link a US bank account (ACH / RTP / wire) as a payout destination using an application token.

## Overview

Link a payout destination (US bank account) for an entity using an application token. The token is passed in the URL; **no Bearer auth is required** for this endpoint.

**Typical flow:**

1. Obtain an application token (e.g. account-widget token).
2. Call this endpoint with the token, currency, option `BANK`, step (e.g. `1`), and the required body.
3. On success, use the returned `data.id` for payouts (e.g. [Withdraw to Linked Account](/guides/withdraw-to-linked-account)).

**Supported (USD):** BANK – US bank account (ACH / RTP / wire).

## Endpoint

* **POST** `{{LIQUIDITY_URL}}/v1/ext/application-token/:token/linked-accounts/:currency/link/:option/:step`
* **Auth:** None (token is in the URL). Do not send `Authorization` header.
* **Headers:** `Content-Type: application/json` required.

### Path Parameters

| Parameter  | Type   | Required | Description                                    |
| ---------- | ------ | -------- | ---------------------------------------------- |
| `token`    | string | Yes      | Application token (e.g. account-widget token). |
| `currency` | string | Yes      | Currency. For this doc: `USD`.                 |
| `option`   | string | Yes      | Link type: `BANK`.                             |
| `step`     | string | Yes      | Step in the flow; typically `1`.               |

## Request Body

Every request must include:

| Field    | Type   | Required | Description                                            |
| -------- | ------ | -------- | ------------------------------------------------------ |
| `label`  | string | Yes      | Nickname for this linked account (e.g. "My checking"). |
| `option` | string | Yes      | Must match path: `BANK`.                               |
| `data`   | object | Yes      | Payload for BANK; see below.                           |

### BANK – data fields

| Field                 | Type   | Required        | Description                                                                                 |
| --------------------- | ------ | --------------- | ------------------------------------------------------------------------------------------- |
| `recipientType`       | string | Yes             | `"personal"` or `"business"`.                                                               |
| `name`                | string | Yes if business | Legal business name. Omit or leave empty for personal.                                      |
| `firstName`           | string | Yes if personal | Account holder first name.                                                                  |
| `lastName`            | string | Yes if personal | Account holder last name.                                                                   |
| `email`               | string | Yes             | Valid email.                                                                                |
| `accountNumber`       | string | Yes             | Bank account number.                                                                        |
| `routingNumber`       | string | Yes             | 9-digit US routing number (leading zero allowed).                                           |
| `type`                | string | Yes             | Account type: `CHECKING`, `SAVINGS`, or `BUSINESS`.                                         |
| `bankName`            | string | Yes             | Name of the bank.                                                                           |
| `recipientAddress`    | string | Yes             | Street address.                                                                             |
| `recipientCity`       | string | Yes             | City.                                                                                       |
| `recipientState`      | string | Yes             | 2-letter US state code (e.g. NY, CA).                                                       |
| `recipientPostalCode` | string | Yes             | US ZIP (e.g. 10001 or 10001-1234).                                                          |
| `routingType`         | string | Yes             | `ACH`, `RTP`, or `WIRE`.                                                                    |
| `nickName`            | string | No              | Nickname for this linked account (e.g. "MayetopsC"). If omitted, top-level `label` is used. |

## Request Examples

### Personal bank account (ACH)

```bash theme={null}
curl -X POST "{{LIQUIDITY_URL}}/v1/ext/application-token/{{token}}/linked-accounts/USD/link/BANK/1" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "My checking",
    "option": "BANK",
    "data": {
      "recipientType": "personal",
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "jane.doe@example.com",
      "accountNumber": "7400244922",
      "routingNumber": "021002220",
      "type": "CHECKING",
      "bankName": "Chase",
      "recipientAddress": "123 Main St",
      "recipientCity": "New York",
      "recipientState": "NY",
      "recipientPostalCode": "10001",
      "routingType": "ACH",
      "nickName": "MayetopsC"
    }
  }'
```

### Business bank account (RTP)

```json theme={null}
{
  "label": "Company operating account",
  "option": "BANK",
  "data": {
    "recipientType": "business",
    "name": "Acme Inc",
    "email": "payments@acme.com",
    "accountNumber": "9876543210",
    "routingNumber": "021002220",
    "type": "BUSINESS",
    "bankName": "Chase",
    "recipientAddress": "456 Business Ave",
    "recipientCity": "New York",
    "recipientState": "NY",
    "recipientPostalCode": "10002",
    "routingType": "RTP",
    "nickName": "MayetopsC"
  }
}
```

## Response

### Success (200)

```json theme={null}
{
  "success": true,
  "message": "Account successfully linked!",
  "data": {
    "id": "845a276a-3c5a-45ff-9aa9-6b266a77f92a"
  }
}
```

| Field     | Type   | Description                                          |
| --------- | ------ | ---------------------------------------------------- |
| `success` | bool   | `true` on success                                    |
| `message` | string | `"Account successfully linked!"`                     |
| `data.id` | string | Linked account ID — use this for withdrawal requests |

* Use `data.id` when calling the [withdrawal endpoint](/guides/withdraw-to-linked-account):\
  `POST /v1/ext/linked-accounts/{currency}/{linkedAccountId}/withdrawal`

### Error (4xx / 5xx)

```json theme={null}
{
  "success": false,
  "message": "<error detail or validation messages>",
  "fatal": true
}
```

### Typical Error Cases

| Situation             | HTTP | Notes                                                                 |
| --------------------- | ---- | --------------------------------------------------------------------- |
| Invalid/expired token | 400  | "Invalid or expired application token".                               |
| Wrong token type      | 400  | Token must be account-widget type.                                    |
| Validation error      | 400  | Missing/invalid fields (e.g. email, state, routingType).              |
| Personal account      | 400  | `firstName` and `lastName` required when `recipientType` is personal. |
| Business account      | 400  | `name` required when `recipientType` is business.                     |
| recipientState        | 400  | Must be 2-letter uppercase (e.g. NY).                                 |
| recipientPostalCode   | 400  | Must be US ZIP (5 or 5+4).                                            |
| routingType           | 400  | Must be ACH, RTP, or WIRE.                                            |
| Duplicate nickname    | 400  | "Nickname already exists, please choose a different nickname".        |
| No platform account   | 400  | No wallet found for entity/currency.                                  |
| Processing error      | 500  | Message may reflect processing or server error.                       |

## Validation Summary

* **label** – Required, any non-empty string.
* **option** – Required, `BANK` (must match path).
* **data** – Required; structure as above.
* **recipientType** – Required; `personal` or `business`; drives requirement for `name` vs `firstName`/`lastName`.
* **routingType** – Required; one of `ACH`, `RTP`, `WIRE`.

## Notes for Integrators

* Obtain a valid application token (account-widget type) before calling this endpoint.
* Use the returned `data.id` when calling the [external withdrawal API](/guides/withdraw-to-linked-account).
* For BANK, choose ACH, RTP, or WIRE via `routingType`.
* Same endpoint is used for non-external path with token in URL; external path is `POST /v1/ext/application-token/{token}/linked-accounts/{currency}/link/{option}/{step}`.