Skip to navigation
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 429 with code: feature_limit_exceeded and 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.

Headers

Idempotency-KeystringOptional<=255 characters

Client-supplied unique key (recommended: UUID v4) for safe retries. Within 24 hours, repeating the same key with the same request (method, path, query, body) replays the original response instead of re-executing the action — once the action has run, a 5xx included; a request stopped before it ran is not stored. Reusing a key with a different request returns 422 idempotency_key_conflict (IETF draft §2.7).

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
defaultboolean or nullOptional

Optional; omitted or null behaves like false. true makes this the workspace’s default bank account and demotes the current one. When the workspace has no default bank account yet, the new account becomes the default whatever this value is.

Response

Created
idlong
public_idstringRead-onlyformat: "^[a-z]+_[0-7][0-9a-hjkmnp-tv-z]{25}$"

Stable public identifier of this record. Never changes once assigned. Its prefix names the entity: doc_ document (invoice, proforma, credit note, quote, sales order), exp_ expense, cnt_ contact, prj_ project, ba_ bank account or cash register, txn_ transaction, lon_ loan, bst_ bank statement. Accepted in place of the numeric id in this resource’s path parameters and in request fields that reference it (customer_id, bank_account_id, …).

account_typeenum

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

Allowed values:
currency_editableboolean

Whether currency may be changed. false for an account synced from the bank that reported its currency — the bank’s value applies and a different one is refused with 422. true for a manual account, and for a synced account the bank sent no currency for, so you can set it.

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).

archivedbooleanOptional

An archived account is one the workspace put away: it stays readable by id and keeps its history, but the list omits it unless archived=true is passed, and it must not be offered as the account a new payment leaves from or arrives to.

Errors

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