API ReferenceBank Accounts

Create a bank account or cash register

View as Markdown
Creates either a bank account (with IBAN/account number) or a cash register. Two validation paths driven by the model's `account_type` enum (currently set via attribute, not via the API surface — defaults to `bank`): - **Bank**: requires `iban` OR `account_number` (one of them). `iban` is unique within the workspace if provided. - **Cash**: `name` is unique within the workspace's cash registers. Per-workspace caps: bank accounts hit the `bank_accounts` feature limit. Hitting the cap returns `402` with an `upgrade_url` pointing at the billing plans page.

Authentication

AuthorizationBearer

JWT issued via POST /api/v1/auth/sign_in. Used by mobile and SPA clients. Revoked tokens are rejected.

OR
AuthorizationBearer
Lucanto API key. Two prefixes: - `lct_pat_<random><checksum>` — personal access token (owner: User) - `lct_live_<random><checksum>` — workspace token, live data Issue keys at `/settings/api_keys` (personal) or `/:workspace_id/settings/api_keys` (workspace). Plaintext token is shown once and never again.

Path parameters

workspace_idlongRequired>=1
Workspace ID. The numeric ID shown in your URLs.

Request

This endpoint expects an object.
namestringRequired
Display name. Required.
currencystringOptional

ISO-4217 currency code. Optional — defaults to your workspace’s currency when omitted.

ibanstringOptional

IBAN. Provide this or account_number.

swift_codestringOptional

SWIFT/BIC. Optional — blank for domestic or cash accounts.

account_numberstringOptional

Local account number. Provide this or iban.

account_number_prefixstringOptional
bank_codestringOptional
defaultbooleanOptional

Mark as the workspace’s default account of this account_type.

Response

Created
idlong
account_typeenum

bank — traditional bank account with IBAN / account number, potentially PSD2-synced. cash — cash register for manual cash-movement tracking.

created_atdatetime
updated_atdatetime
namestring or nullOptional

Display name. Required for cash registers (where it must be unique within the workspace); optional for bank accounts where the IBAN/account_number identifies the record.

account_holder_namestring or nullOptional

Name on the account / register.

currencystring or nullOptional

ISO-4217 currency code. Defaults to workspace currency.

ibanstring or nullOptional

IBAN — required for bank-type accounts (or account_number must be set). Null for cash registers.

swift_codestring or nullOptional

SWIFT/BIC. Optional for bank accounts; null for cash.

account_numberstring or nullOptional

Local account number — required for bank-type accounts if iban is not set. SK/CZ banks accept legacy non-IBAN format. Null for cash registers.

account_number_prefixstring or nullOptional

CZ-style prefix on legacy account numbers (e.g. 19- in 19-2000945399/0800).

bank_codestring or nullOptional

Local bank code (SK: 4-digit, CZ: 4-digit). Null for cash registers.

balance_availablestring or nullOptionalformat: "decimal"

Available balance from the most recent PSD2 sync, if connected. Null for cash registers and non-synced bank accounts. Stringified BigDecimal.

balance_bookedstring or nullOptionalformat: "decimal"

Booked balance from the most recent PSD2 sync. Differs from balance_available for accounts with pending transactions. Same null/format semantics as balance_available.

last_balance_sync_atdatetime or nullOptional
Timestamp of the last successful balance sync. Null for cash registers and bank accounts that have never synced.
defaultboolean or nullOptional

Whether this account is the workspace’s default for new documents. Each account_type has independent defaults (one default bank + one default cash register per workspace).

Errors

401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
422
Unprocessable Entity Error
429
Too Many Requests Error