Bank transactions
Bank transactions
A bank transaction is one line of a bank, card, cash or provider account
(bankTransaction.index, bankTransaction.show). This guide covers checking
a month against the bank statement, booking a line to an account
(categorize) or many lines at once (bulk categorize), short answers to
writes, changing a line that is already booked, money back from a supplier
or to a customer, and excluding, including or deleting lines in bulk.
Matching a line to a bill or invoice (reconciliationMatch.create) is in
Settling bills from bank lines. The same
operations power the Cybooks MCP server: each REST endpoint below names its
MCP tool.
Every write below needs an Idempotency-Key (MCP: idempotency_key), and the
ones that change one line need the line's ETag in Cybooks-If-Match (MCP:
if_match). See Authentication for both.
| Operation | REST | MCP tool | Scope |
|---|---|---|---|
bankTransaction.show | GET /v1/bank-transactions/{id} | cybooks_get_bank_transaction | bank-transactions:read |
bankTransaction.summary | GET /v1/bank-transactions/summary | cybooks_get_bank_transaction_summary | bank-transactions:read |
bankTransaction.categorize | POST /v1/bank-transactions/{id}/categorize | cybooks_categorize_bank_transaction | bank-transactions:action |
bankTransaction.bulkCategorize.preview, bankTransaction.bulkCategorize, bankTransaction.bulkCategorize.status | POST /v1/bank-transactions/bulk-categorize/preview, POST /v1/bank-transactions/bulk-categorize, GET /v1/bank-transactions/bulk-categorize/operations/{operationId} | cybooks_preview_bulk_categorize_bank_transactions, cybooks_bulk_categorize_bank_transactions, cybooks_get_bulk_categorize_status | bank-transactions:action |
bankTransaction.booking.index | GET /v1/bank-transactions/{id}/booked-transactions | cybooks_list_bank_transaction_bookings | bank-transactions:read |
bankTransaction.booking.undo | POST /v1/bank-transactions/{id}/booked-transactions/{bookingId}/undo | cybooks_undo_bank_transaction_booking | bank-transactions:action |
bankTransaction.bulkExclude.preview, bankTransaction.bulkExclude | POST /v1/bank-transactions/bulk-exclude/preview, POST /v1/bank-transactions/bulk-exclude | cybooks_preview_bulk_exclude_bank_transactions, cybooks_bulk_exclude_bank_transactions | bank-transactions:action |
bankTransaction.bulkInclude.preview, bankTransaction.bulkInclude | POST /v1/bank-transactions/bulk-include/preview, POST /v1/bank-transactions/bulk-include | cybooks_preview_bulk_include_bank_transactions, cybooks_bulk_include_bank_transactions | bank-transactions:action |
bankTransaction.bulkDelete.preview, bankTransaction.bulkDelete | POST /v1/bank-transactions/bulk-delete/preview, POST /v1/bank-transactions/bulk-delete | cybooks_preview_bulk_delete_bank_transactions, cybooks_bulk_delete_bank_transactions | bank-transactions:action |
The summary needs the view_bank_accounts permission. Categorize, bulk
categorize, undo, exclude and include need update_bank_accounts; bulk
delete needs delete_bank_accounts. The two other undos below need their
own scope: reconciliationMatch.unmatch the reconciliation:action scope (with
reconcile_transactions, update_bank_accounts, view_bank_accounts,
view_bills and view_vat_returns), transfer.unmatch the
transfers:action scope (with update_bank_accounts). The reads the steps
below look at need their own scope too: transfer.show the transfers:read
scope (with view_bank_accounts), vatReturn.index the reports:read scope
(with view_vat_returns), creditNote.index the credit-notes:read scope
(with view_credit_notes) and vendorCredit.index the vendor-credits:read
scope (with view_vendor_credits).
Checking a month against the statement
GET /v1/bank-transactions/summary (MCP: cybooks_get_bank_transaction_summary,
reached through cybooks_search_capabilities and run with
cybooks_read_capability) counts and sums the lines, so an agent can compare
the month with the statement without paging through every line.
| Filter | |
|---|---|
filter[date_from], filter[date_to] | Required, YYYY-MM-DD, inclusive, date_to at most 366 days after date_from. |
filter[payment_account_id], filter[direction], filter[currency], filter[reconciliation_state], filter[provider], filter[counterparty_id] | Optional, as on GET /v1/bank-transactions. |
Missing dates, a date_to before date_from or more than 366 days after it,
an empty filter value or any other filter (id, source_id,
updated_since, q) answer 422 validation_failed. The filters are read
from the URL query only, never from a request body.
The answer has one row per reconciliation state, direction and currency with
lines in the range:
{
"data": {
"date_from": "2026-03-01",
"date_to": "2026-03-31",
"rows": [
{ "reconciliation_state": "unreconciled", "direction": "incoming", "currency": "EUR", "count": 2, "amount": "120.10", "hidden_count": 0 },
{ "reconciliation_state": "unreconciled", "direction": "outgoing", "currency": "EUR", "count": 2, "amount": "-40.25", "hidden_count": 1 }
]
}
}countis the number of linesGET /v1/bank-transactionslists for the same
filters.amountis their sum, each line rounded to 2 decimals as the list shows
it, signed as the list signs a line: money out is negative.hidden_countis the number of salary lines the caller may not see
(noview_payroll). They are counted incountbut left out ofamount.- Lines of archived accounts are included, as in the list. Lines of
non-operational account types are not, as in the list.
Requires the bank-transactions:read scope and view_bank_accounts.
Categorize a line
bankTransaction.categorize books a line that no bill or invoice matches to
an account, and posts it to the ledger. The body names:
- the account, by
account_id(the chart-of-accountsid, needed when the
account has no code) oraccount_code; - the tax rule, by
tax_rule_idortax_code; counterparty_id: a customer on money in, a supplier on money out;memo;tags, optional: tag ids, at most 20, at most one tag from each tag group.
Send the line's ETag from bankTransaction.show (or from the last write on
the line) as Cybooks-If-Match. Posting changes the books, so confirm with
the user first.
Tags
tags puts the tags on the account line of the booking, as the Reconcile
screen does. Each id must be a tag that exists (a deleted tag is refused), and
two tags from one group are refused. Tags are part of the Cybooks plan: without
the tag feature, a non-empty tags is refused with 422 tags_need_plan;
"tags": [] is accepted on any plan. If a tag is deleted after the request was
checked but before the line was booked, nothing is booked and the answer is
422 tags_gone: read the tags again and send ones that still exist. Bulk
categorize takes tags per item the same way.
A categorized line shows its tags as tag_ids on the bank transaction: the
tags on its current categorize booking, without archived tags, sorted. A line
that is not categorized, and a line a salary mask hides, shows []. tag_ids
can be asked for with fields, and the change feed lists tag_ids among
the changed fields of a categorize that wrote tags (and of an undo that
changed them).
A line that is excluded from reconciliation is refused with
422 bank_line_excluded: include it again first (bulk include, below). A line
that is already booked is refused with 409 bank_line_already_booked, which
names its bookings (error.fields.booked_transaction_ids) and the operation
that undoes them (error.fields.undo_operation_id).
Change a line that is already booked
A booked line is not categorized again as it is. Change it only when the user
asked for that line to change, in three steps:
bankTransaction.booking.indexlists the line's bookings, each with its
id.- Undo it with the operation the 409 names in
error.fields.undo_operation_id,
on the id it lists inerror.fields.booked_transaction_ids:
bankTransaction.booking.undo(bookingId, the line's ETag) for a
categorization of the line or an invoice payment, as Cybooks' Undo does;
reconciliationMatch.unmatch(preview, then commit) for a bill payment or a
payment over several bills or invoices;transfer.unmatch(preview, then
commit, with the transfer's id and the ETag oftransfer.show, never*)
for a leg of a transfer. Check the line's date before you undo (see the
limits below). The line is open again; read it for its new ETag
(bankTransaction.booking.undoreturns it). bankTransaction.categorizebooks it again, with that new ETag and a new
Idempotency-Key.
Undo has limits. Do not work around a refusal: tell the user.
- A booking dated in a closed period or a filed VAT period: leave it and ask
the user first. Undoing a categorization dated on or before the period lock,
the tax lock date or the hard lock is refused:422 invalid_request, or
403 forbiddenwhen the month is closed and the connected person may not
close periods (manage_period_lock). Neither answer names the period: read
the line's date. The tax lock date moves when a VAT or OSS return is
completed in Cybooks; a return completed before the company had one is not
covered by it, so for a line dated in an earlier VAT period read
vatReturn.indexfirst and do not undo whenperiod_filedis true for the
line's date. Reopening a period is the user's decision, not a step to take
on your own. - A payment or a transfer dated in a closed period or a filed VAT period is
often not refused: for a person who may close periods (in a filed VAT
period, anyone who may undo), within the current financial year and unless
the company blocks such reversals, the undo posts its reversal on the
first open day and gives the line back unbooked, and step 3 is then
refused, because a new booking takes the lock on the line's own date. The
line stays unbooked until the user reopens the period. Otherwise it is refused:
403 forbiddenin a closed month for a person withoutmanage_period_lock,
422 invalid_requestwhen the payment is in an earlier financial year.
reconciliationMatch.unmatch.previewandtransfer.unmatch.previewshow it
(effects.modeisforward_reversal, witheffects.reversal_date);
bankTransaction.booking.undohas no preview. - A bill or invoice payment: undoing it reopens the bill or invoice.
- A payment over several bills or invoices is refused with
422 match_is_part_of_payment: reverse the whole payment with
reconciliationMatch.unmatchand the match id the refusal names. - A leg of a transfer between two accounts is undone only with
transfer.unmatch(preview, then commit) and the transfer id the 409 lists
inbooked_transaction_ids, never withbankTransaction.booking.undo, which
has no preview. The transfer's bank lines go back to To review, and a
counterpart line Cybooks created for it is deleted. - A booking only Cybooks can undo: the
409 bank_line_already_bookednames no
undo operation (undo_operation_idis empty), and the user undoes it in
Cybooks (Reconcile, Done tab).
booked_transaction_ids on a bank line
booked_transaction_ids on a bank lineEach bank line now carries booked_transaction_ids: every booking row on the
line, either side, newest payment first, as
GET /v1/bank-transactions/{id}/booked-transactions lists them. That includes
rows an undo does not take on their own, such as a fee line's booking or the
other side of a transfer: read the bookings before you undo one.
Short answers to writes: Prefer: return=minimal
Prefer: return=minimalAn agent that books many lines rarely needs the whole line back. These six
writes take the Prefer: return=minimal header (RFC 7240).
Over MCP, cybooks_categorize_bank_transaction is listed; the others are
reached through cybooks_search_capabilities and run with
cybooks_write_capability.
| Endpoint | MCP tool |
|---|---|
POST /v1/bank-transactions/{id}/categorize | cybooks_categorize_bank_transaction |
POST /v1/bank-transactions/{id}/book-incoming | cybooks_book_incoming_bank_transaction |
POST /v1/bank-transactions/{id}/book-outgoing | cybooks_book_outgoing_bank_transaction |
POST /v1/booked-transactions | cybooks_create_manual_booked_transaction |
POST /v1/bank-transactions/{id}/booked-transactions/{bookingId}/undo | cybooks_undo_bank_transaction_booking |
POST /v1/bank-transactions/{id}/booked-transactions/{bookingId}/unreconcile | cybooks_unreconcile_bank_transaction_booking |
With the header, data carries only id, version, etag,
reconciliation_state and booked_transaction_ids, meta is unchanged, and
the response carries Preference-Applied: return=minimal. Each of these
writes answers with Vary: Prefer, with or without the header. Over MCP, pass
the argument return: "minimal".
Send the line's ETag in Cybooks-If-Match, never the standard If-Match
(see Authentication).
POST /v1/bank-transactions/9c1d.../categorize
Idempotency-Key: 6f1e...
Cybooks-If-Match: "3f9c1a7d0b2e4c51-v4"
Prefer: return=minimal{
"data": {
"id": "9c1d...",
"version": 5,
"etag": "\"3f9c1a7d0b2e4c51-v5\"",
"reconciliation_state": "reconciled",
"booked_transaction_ids": ["b07a..."]
}
}- A booking write (
book-incoming,book-outgoing,POST /v1/booked-transactions)
answers with the booking: itsid,versionandetag, its
reconciliation.state, and its own id inbooked_transaction_ids. On
book-incomingandbook-outgoingthe bank line's new version stays in
meta.bank_transaction_version. To undo or
unreconcile next, send the line's ETag; read the line
(GET /v1/bank-transactions/{id}) if you no longer hold it. - A replay of the same
Idempotency-Keyis answered by thePreferheader the
replay sends: Cybooks stores the full answer, andPreferis not part of the
request fingerprint. The same key with and without the header is the same
request. - Every other endpoint ignores the header and answers in full without
Preference-Applied; the bulk exclude, include, delete and categorize
commits are among them. Over MCP, every other tool refuses thereturnargument.
Money back from a supplier
Money in from a supplier is a refund, and categorize refuses it with
422 supplier_refund_needs_vendor_credit. Refund a vendor credit against the
line.
Look first: vendorCredit.index with filter[contact_id] = the supplier. If
an approved vendor credit (status open or part-paid) has at least the
line's amount in unapplied_amount, go to step 3 with it. Only when there is
none:
vendorCredit.store: a vendor credit for the supplier, with the account
and VAT rule of the original charge.vendorCredit.approve.vendorCredit.refund.previewwithbank_transaction_id= the line. The
line's account, amount and date are used, sopayment_account_id,
amountandpayment_datemay be left out. It returns a
confirmation_token.vendorCredit.refund.createwith the same body, the token,
the sameIdempotency-Keyas the preview and the vendor credit's ETag. It books
this line; no second line is created.
The refusal codes are in Settling bills from bank lines.
Money back to a customer
Money out to a customer is a refund, and categorize refuses it with
422 customer_refund_needs_credit_note. A line that is already on the
account cannot be booked as a customer refund through the API yet, and
Cybooks does not offer that booking to every company yet: leave the line
unbooked and tell the user.
A refund to a customer belongs on a credit note. Record one only when the
user asks for it, and look first: creditNote.index with
filter[contact_id] = the customer and filter[status]=open; when an
approved credit note has the line's amount in unapplied_amount, create
nothing. Otherwise creditNote.store with the account and VAT rule of the
original sale, then creditNote.approve: approving posts to the ledger, and
the line stays to review until the user settles it in Cybooks.
Do not also record the refund with creditNote.refund.preview /
creditNote.refund.create. They take payment_account_id, amount and
payment_date and always record a new outgoing payment: they never take an
existing line and refuse a statement-backed account. Run next to a line
already on the account, they count the refund twice and close the credit
note, so the line can no longer be booked against it. Use them only for a
refund that is on no account yet, on an account that is not statement-backed,
with the preview's confirmation_token, the same Idempotency-Key and the
credit note's ETag. Booking an imported line to a credit note is not in the
API yet.
Exclude, include or delete lines in bulk
Each bulk action takes up to 100 line ids and is two calls with the same body
and the same Idempotency-Key:
- The preview (
….preview) writes nothing. It returns one result per id
(eligible, or the reason the line is left alone) and a
confirmation_token, valid for 5 minutes. - The commit, with the same
ids, the token and
the sameIdempotency-Keyas the preview: the token is bound to that
key, and a commit with another key is refused with422. It acts on the lines the
preview markedeligibleand returns every other id with its preview
status. A line that changed since the preview answers412: preview again
with a new key.
- Exclude (
bankTransaction.bulkExclude) takes lines out of
reconciliation. Only the flag changes: no booking or journal entry is made
or removed. A line already excluded isalready_excluded; a line Cybooks
protects, for example one that is reconciled, matched, booked, documented
or edited by a person, isprotectedwith its reasons. - Include (
bankTransaction.bulkInclude) puts excluded lines back, the
inverse of exclude. A line that is not excluded isnot_excluded. - Delete (
bankTransaction.bulkDelete) soft-deletes lines. A deleted
line leaves the account balance, and a deleted feed line is never imported
again. The account-type rule and the shared protections are listed in the
bankTransaction.bulkDelete.previewreference.
Exclude, include and delete only what the user asked for.
The account's unreconciled_transaction_count
unreconciled_transaction_countunreconciled_transaction_count on GET /v1/payment-accounts and
GET /v1/payment-accounts/{id} leaves out excluded lines. It now equals the
number of lines GET /v1/bank-transactions lists with
filter[payment_account_id] and filter[reconciliation_state]=unreconciled.
It used to count excluded lines that had no booking as well.
Bulk categorize
Bulk categorize books up to 50 bank lines in one preview and one commit, each
line with the body bankTransaction.categorize takes. A year of about 1,600
lines takes 32 preview and commit pairs instead of 1,600 calls. Each line is
still booked on its own, exactly as a single categorize books it: what one line
refuses never stops the others.
It takes three steps: a read-only preview, a commit that answers 202 at once,
and a status read you poll while a job books the lines.
| Endpoint | Operation | Answers |
|---|---|---|
POST /v1/bank-transactions/bulk-categorize/preview | bankTransaction.bulkCategorize.preview | 200: every item ready (with its journal) or refused; totals; confirmation_token |
POST /v1/bank-transactions/bulk-categorize | bankTransaction.bulkCategorize | 202: operation_id, status queued, total |
GET /v1/bank-transactions/bulk-categorize/operations/{operationId} | bankTransaction.bulkCategorize.status | 200: the operation's status and every line's outcome |
All three need the bank-transactions:action OAuth scope and the
update_bank_accounts permission. Over MCP they are capabilities with the same
operation IDs: find them with cybooks_search_capabilities "bulk categorize",
run the preview and the status read with cybooks_read_capability and the
commit with cybooks_write_capability.
1. Preview
POST /v1/bank-transactions/bulk-categorize/preview
Idempotency-Key: 0b6f3c2e-bulk-2026-10
{
"items": [
{
"bank_transaction_id": "9d1c…",
"counterparty_id": "4a77…",
"account_code": "6100",
"tax_code": "G",
"memo": "Bank charges October"
}
]
}items: 1 to 50 objects, each bank line once. Each item is the
bankTransaction.categorizebody (counterparty_id,account_idor
account_code,tax_rule_idortax_code,memo, optionaltags) plus
the line'sbank_transaction_id.- An empty
items, one that is not a list or more than 50 items refuses the
whole request with422keyeditems; a wrong item shape or a line named
twice, keyeditems.N.<field>. - The preview writes nothing and locks nothing. Every item answers on its own,
with itsindex:ready, with thejournalthe booking would post (per line the account,
debitandcreditin the company's currency, the line currency's
amounts and the tax rule; for a line in another currency the
exchange_rateused), orrefused, withhttp_status,code,messageandfieldsexactly as
bankTransaction.categorizerefuses that line:bank_line_already_booked,
bank_line_held_by_booking,bank_line_excluded,
supplier_refund_needs_vendor_credit,tags_need_plan, a closed period,
a salary line you may not see (403) and so on.
totalscounts the ready and refused items and sums the ready items'
debits and credits.- When any item is ready,
confirmation_tokenbinds the ready items for
5 minutes to you, your client, theIdempotency-Keyand the body. Refused
items are never booked: fix them and send them again in a later preview.
2. Commit
Send the same items with the same Idempotency-Key, plus the token:
POST /v1/bank-transactions/bulk-categorize
Idempotency-Key: 0b6f3c2e-bulk-2026-10
{
"items": [ … the same items … ],
"confirmation_token": "…"
}HTTP/1.1 202 Accepted
{ "data": { "operation_id": "5f0e…", "status": "queued", "total": 48 } }total is the number of ready lines the job will book. Nothing is booked
inside the request.
Idempotency-Keyis required. A replay with the same key and body answers
the stored202and starts no second operation.- A body that differs from the preview's answers
412; an expired or
tampered token422; a token already used409
confirmation_already_claimed. - At most 3 bulk categorize operations per person and client may be queued or
running at once. A fourth answers409bulk_categorize_busy: read one
until it ends, then commit again with the same key and token, or preview
again if the token expired (it lives 5 minutes). - An AI agent that holds a work lease on the lines (
work.claim) sends it as
the top-levellease_idargument over MCP, next tobody, as on every
write; the body takes nolease_id. The
commit keeps that lease for the job, which checks the leases again before
every line.
3. Status
GET /v1/bank-transactions/bulk-categorize/operations/5f0e…
{
"data": {
"operation_id": "5f0e…",
"status": "succeeded",
"total": 48, "booked": 46, "refused": 2, "failed": 0, "pending": 0,
"items": [
{ "bank_transaction_id": "9d1c…", "outcome": "booked", "booked_transaction_ids": ["c3a1…"], "code": null, "message": null },
{ "bank_transaction_id": "a802…", "outcome": "refused", "booked_transaction_ids": [], "code": "bank_line_already_booked", "message": "…" }
]
}
}status is queued, running or succeeded (every line has an outcome,
refused ones included). Poll every few seconds until it is succeeded; 50
lines take well under a minute. A long run may hand the operation back to
queued for a moment before it goes on. Only your own operations
through the same client are readable: any other id answers 404. The generic
GET /v1/operations/{id} shows the same counts and items under result,
never the line bodies you sent.
Each line's outcome:
outcome | Meaning |
|---|---|
booked | Booked as bankTransaction.categorize books it; booked_transaction_ids names the bookings. |
refused | Not booked; code and message say why (below). Nothing of the line was written. |
failed | Not booked because of an unexpected error (bulk_categorize_item_failed). It is reported to us; categorize the line on its own or preview it again. |
pending | The job has not reached the line yet. |
Refusals while the job books
The job checks every line again just before it books it, in its own
transaction, so a line that changed after the preview is refused, never booked
on stale facts:
code | Why |
|---|---|
any code of bankTransaction.categorize | The line refuses now what the single categorize would refuse: booked by someone else meanwhile (bank_line_already_booked), excluded, in a period locked since the preview, and so on. |
changed_since_preview | The line, its eligibility or the journal it would post changed since the preview, a moved exchange rate included. Preview it again. |
journal_mismatch | The posted journal differed from the preview's; nothing was booked. Preview it again. |
journal_unbalanced | The posted journal did not balance; nothing was booked. Preview it again. |
needs_permission | You lost update_bank_accounts while the job ran, or the channel you committed on can no longer be checked: every line left ends with this code. |
subscription_expired | The company's subscription expired while the job ran: every line left ends with this code. |
bulk_categorize_paused | Bulk categorize was switched off while the job ran: every line left ends with this code. |
agents_stopped, run_paused | For an AI agent: the company's STOP or the run's pause, checked before every line. Every line left ends with the code. |
leased_by_other_agent | For an AI agent: another agent holds a work lease on the line or its counterparty. |
Rate limits and the daily cap
A bulk preview and a bulk commit are one request each toward the api-v1
rate limit and the API key's daily cap, whatever the number of lines: the cap
counts calls, not lines. Each status read is one request.
Switched off
Operators can switch bulk categorize off. While it is off the preview and the
commit answer 503 with Retry-After: 30; categorize the lines one by one with
bankTransaction.categorize meanwhile. A job that is running stops before its
next line, which ends bulk_categorize_paused.
ETags and *
*Send the ETag of your last read of the line. * writes whatever the current
version is, without checking that nobody changed the line since: use the ETag
when you have read the line. Categorize and undo accept *; the operations
that refuse it are listed in Authentication.
Updated 5 days ago
