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

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:

{
  "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

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