# Creates a bank account.

`POST /banking/bank-accounts`

Group: Banking › Bank Accounts · Operation ID: `createBankAccount`

The response contains only the new account's id. Read the record with GET banking/bank-accounts/:id.

externalAccountId, accountId, reconciliationStartDate and paymentAllowed are required. A duplicate externalAccountId fails with DUPLICATE_EXTERNAL_ACCOUNT_ID, which names the existing account. accountId and financialInstitutionId each fail with REFERENCE_NOT_FOUND when they name no record.

When referenceType is 'QRR', reference must be a Swiss QR-IBAN, whose fifth to ninth digits fall between 30000 and 31999. Anything else fails with INVALID_QR_IBAN.

[Open in the interactive reference](https://docs.api.lensing.ai/?op=createBankAccount)

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Api-Version` | header | `"v1"` | yes | The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version `v1`. |
| `Idempotency-Key` | header | string | no | An opaque caller-chosen string (1-255 characters) that makes this request safe to retry. Repeating the same key with an identical request body replays the original response instead of re-executing - but only once that original request succeeded; a failed attempt re-executes on retry. Repeating the key with a different body is answered with 422. A key still in flight is answered with 409 - as is a key whose original request was interrupted before it finished, for a few minutes afterwards, until that attempt is presumed dead. A completed response stays replayable for 24 hours. The key is scoped to the caller, not to the action: reusing it for a different action is answered with 409 or 422 rather than treated independently. On read actions this header is ignored. On write actions that cannot offer the guarantee it is answered with `400 IDEMPOTENCY_NOT_SUPPORTED` rather than silently ignored. |

## Request body

Required, `application/json`: createBankAccountInput.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `externalAccountId` | string | yes | The account's identifier in the system that owns it, for example its IBAN or ACH account number. Must be unique within the tenant. |
| `accountId` | string | yes | The general-ledger account this bank account posts to. See id on GET accounting/accounts/:id. |
| `reconciliationStartDate` | string (date) | yes | The date from which transactions on this account are reconciled. Use format YYYY-MM-DD. |
| `paymentAllowed` | boolean | yes | Whether outbound payments may be made from this account. |
| `financialInstitutionId` | string | no | The financial institution holding the account. Omit when the account is not linked to one. There is no endpoint for it. |
| `currency` | string | no | The account currency. Format ISO 4217, for example 'USD'. |
| `type` | string | no | The kind of account, as free-form text. For example 'checking' or 'saving'. |
| `reference` | string | no | The IBAN or ACH account number. When referenceType is 'QRR' this must be a Swiss QR-IBAN. |
| `referenceType` | string | no | How payment references on this account are structured. Accepted values: 'QRR', 'SCOR', 'NON'. |
| `referenceNumber` | string | no | A structured creditor reference number for this account. |
| `receivableAccount` | boolean | no | Whether the account may receive incoming payments. Defaults to false. |

Example:

```json
{
  "externalAccountId": "CH9300762011623852957",
  "accountId": "d5397c8b-6d2b-47e9-83a3-712d9180711e",
  "reconciliationStartDate": "2026-01-01",
  "paymentAllowed": true,
  "financialInstitutionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "currency": "CHF",
  "type": "checking",
  "reference": "CH4431999123000889012",
  "referenceType": "QRR",
  "referenceNumber": "<referenceNumber>",
  "receivableAccount": false
}
```

## Response

`200` Success

Under `data` (createBankAccountOutput):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The unique identifier for the created bank account. |

## Response headers

- `Idempotency-Replayed` — Present and `true` only when this response replays a previously stored one for the same Idempotency-Key, rather than reflecting a live execution. Absent on a live response - never sent as `false`.

## Errors

| Code | Status |
| --- | --- |
| `REFERENCE_NOT_FOUND` | 400 |
| `INVALID_FIELD_VALUE` | 400 |
| `INVALID_QR_IBAN` | 400 |
| `DUPLICATE_EXTERNAL_ACCOUNT_ID` | 400 |
| `IDEMPOTENCY_KEY_CONFLICT` | 409 |
| `IDEMPOTENCY_PAYLOAD_MISMATCH` | 422 |

## Statuses

- `400` — Invalid request or business failure. Codes: REFERENCE_NOT_FOUND, INVALID_FIELD_VALUE, INVALID_QR_IBAN, DUPLICATE_EXTERNAL_ACCOUNT_ID
- `401` — Missing or invalid access token
- `403` — Not authorized
- `404` — Not found
- `409` — The Idempotency-Key is still being processed by another request.
- `422` — The Idempotency-Key was already used with a different request payload.
- `429` — Too many requests
- `500` — Internal server error