> ## 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 International Bank Account

> Link an international bank account for cross-border payouts and wire transfers.

## Endpoint

* **Method**: `POST`
* **URL**: `{{LIQUIDITY_URL}}/v1/ext/application-token/:token/linked-accounts/:currency/link/international_bank/:step`
* **Auth**: Bearer `{{accessToken}}`

## Path Parameters

| Parameter  | Type   | Description                                  | Required |
| ---------- | ------ | -------------------------------------------- | -------- |
| `token`    | string | Application token from payout/account widget | Yes      |
| `currency` | string | Currency code (e.g., `USD`)                  | Yes      |
| `step`     | string | Usually `1`                                  | Yes      |

## Request Body

| Field                      | Type   | Description                                                                | Required    |
| -------------------------- | ------ | -------------------------------------------------------------------------- | ----------- |
| `label`                    | string | Display name for the linked account                                        | Yes         |
| `data.recipientType`       | string | `personal` or `business`                                                   | Yes         |
| `data.firstName`           | string | First name (required if `personal`)                                        | Conditional |
| `data.lastName`            | string | Last name (required if `personal`)                                         | Conditional |
| `data.name`                | string | Business name (required if `business`)                                     | Conditional |
| `data.email`               | string | Email of the recipient                                                     | Yes         |
| `data.accountNumber`       | string | International bank account number (IBAN or local)                          | Yes         |
| `data.swiftOrBic`          | string | SWIFT/BIC code                                                             | Yes         |
| `data.bankName`            | string | Name of the international bank                                             | Yes         |
| `data.recipientAddress`    | string | Street address of the recipient                                            | Yes         |
| `data.recipientCity`       | string | City of the recipient                                                      | Yes         |
| `data.recipientState`      | string | State/region of the recipient                                              | Yes         |
| `data.recipientCountry`    | string | ISO 3166-1 alpha-2 country code (e.g., `NG`, `GB`)                         | Yes         |
| `data.recipientPostalCode` | string | Postal code of the recipient                                               | Yes         |
| `data.nickName`            | string | Optional nickname for this account. If omitted, top-level `label` is used. | No          |

## Request

```bash theme={null}
curl -X POST "{{LIQUIDITY_URL}}/v1/ext/application-token/{{token}}/linked-accounts/USD/link/international_bank/1" \
  -H "Authorization: Bearer {{accessToken}}" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "International Wire",
    "data": {
      "firstName": "John",
      "lastName": "Doe",
      "name": "Quantum Works LLC",
      "accountNumber": "8991026399",
      "swiftOrBic": "031000053",
      "bankName": "ABC bank",
      "recipientAddress": "9401 San francisco",
      "recipientCity": "San francisco",
      "recipientState": "CA",
      "recipientPostalCode": "9401",
      "email": "timi@gradientfi.com",
      "recipientCountry": "NG",
      "recipientType": "personal",
      "nickName": "MayetopsC"
    }
  }'
```

## Response (200)

```json theme={null}
{
  "success": true,
  "message": "Account successfully linked!",
  "data": {
    "id": "6b7c509b-93f4-4b51-a8e4-61cabed5eea0"
  }
}
```

### Response Fields

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

## Notes

* Country codes should use ISO 3166-1 alpha-2 format (e.g., `GB`, `NG`, `US`)
* SWIFT/BIC codes should match the destination bank
* Store the `id` from the response for withdrawal requests

***