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

# POST /v1/bank-accounts — Link a Bank Account

> POST /v1/bank-accounts links a new bank account to your business. Provide account holder details, full account number, and routing number.

Link a new bank account to your business by submitting the account holder's legal name, a display name, full account number, routing number, and account type. Once created, Cleo Pay initiates the micro-deposit verification process automatically — two small deposits will arrive in the account within 1–3 business days.

## HTTP Request

```
POST https://api.cleo-pay.com/v1/bank-accounts
```

## Authentication

Include your bearer token on every request:

```
Authorization: Bearer <token>
```

***

## Request Body

<ParamField body="holderName" type="string" required>
  The legal name of the account holder exactly as it appears on the bank account. This is used for payment processing and account validation.
</ParamField>

<ParamField body="name" type="string" required>
  A human-readable display name for this account (e.g. `"Primary Operating Account"`). This is for your own reference and is returned in all subsequent responses.
</ParamField>

<ParamField body="accountNumber" type="string" required>
  The full bank account number. This value is **write-only** — it is never returned in any API response after creation.
</ParamField>

<ParamField body="routingNumber" type="string" required>
  The 9-digit ABA routing number for the account. This value is **write-only** — it is never returned in any API response after creation.
</ParamField>

<ParamField body="type" type="string" required>
  The type of bank account. Must be one of `checking` or `savings`.
</ParamField>

***

## Response Fields

A successful request returns HTTP `201 Created` with the new bank account object.

<ResponseField name="id" type="string" required>
  Unique identifier for the bank account.
</ResponseField>

<ResponseField name="status" type="string" required>
  The initial status of a newly created account is `pending_verification`, indicating that micro-deposits have been initiated.
</ResponseField>

<ResponseField name="type" type="string" required>
  The bank account type you submitted: `checking` or `savings`.
</ResponseField>

<ResponseField name="connectionType" type="string" required>
  Always `manual` for accounts created via the API.
</ResponseField>

<ResponseField name="name" type="string | null">
  The display name you provided.
</ResponseField>

<ResponseField name="institutionName" type="string | null">
  The name of the financial institution, if resolved from the routing number.
</ResponseField>

<ResponseField name="accountNumberLast4" type="string | null">
  The last four digits of the account number you submitted.
</ResponseField>

<ResponseField name="routingNumberLast4" type="string | null">
  The last four digits of the routing number you submitted.
</ResponseField>

<ResponseField name="isDefault" type="boolean" required>
  Whether this account has been set as the default for your business.
</ResponseField>

<ResponseField name="microDepositsInitiatedAt" type="datetime | null">
  The timestamp at which micro-deposits were initiated. Populated immediately on successful account creation.
</ResponseField>

<ResponseField name="microDepositsCompletedAt" type="datetime | null">
  The timestamp at which micro-deposits landed in the account. This will be `null` until the deposits arrive (typically 1–3 business days).
</ResponseField>

<ResponseField name="verificationAttempts" type="number" required>
  The number of failed verification attempts. Always `0` on a newly created account.
</ResponseField>

***

## Example Request

```bash theme={null}
curl --request POST \
  --url https://api.cleo-pay.com/v1/bank-accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "holderName": "Acme Corp",
    "name": "Primary Operating Account",
    "accountNumber": "123456789012",
    "routingNumber": "021000021",
    "type": "checking"
  }'
```

***

## Example Response

```json theme={null}
{
  "id": "ba_01j9kxm2p4fghe3t7q8wnvd5rc",
  "status": "pending_verification",
  "type": "checking",
  "connectionType": "manual",
  "name": "Primary Operating Account",
  "institutionName": "Chase",
  "accountNumberLast4": "9012",
  "routingNumberLast4": "0021",
  "isDefault": false,
  "microDepositsInitiatedAt": "2024-10-01T10:00:00Z",
  "microDepositsCompletedAt": null,
  "verificationAttempts": 0
}
```

<Warning>
  `accountNumber` and `routingNumber` are **write-only** fields. After creation, only the last four digits of each are accessible via `accountNumberLast4` and `routingNumberLast4`. Store sensitive account details securely before submitting them to the API if you need to retain them.
</Warning>

<Note>
  Micro-deposits are initiated automatically upon account creation. Check `microDepositsCompletedAt` on the account — once it is non-null, the deposits have landed and you can call the [verify micro-deposits](/api-reference/bank-accounts/verify-micro-deposits) endpoint to complete verification.
</Note>