Bank statements

Base URL: $BUSINESS_API

List bank statements

Logs

GET /bank-statements

Returns the tenant's imported bank statements, newest first, with cursor pagination (limit defaults to 20, at most 100). Each statement carries its bank account reference, statement reference and date, currency and line count. Requires payments:read.

Parameters

limitinteger · query · optional

Maximum resources to return (default 20, maximum 100).

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Success

Errors 400 · 403 · 404 · 409

Permissions payments:read · Roles: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

curl -X GET "$BUSINESS_API/bank-statements" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Success

Import a bank statement

Logs

POST /bank-statements

Import a bank statement (lines or csv) and match credits to payments

Stores a statement with its lines, given either as a lines array or as CSV text (columns value_date as YYYY-MM-DD, amount, then optional reference and description; a value_date header row is skipped). bank_account_ref, statement_reference, statement_date and at least one line are required, and amounts are read in the tenant's currency. Each credit line is then matched to a posted payment of the same amount, first by reference or receipt number, then by amount alone when exactly one bank transfer falls within three days; matched payments become reconciled and everything else waits in the unmatched queue. Records a bank_statement.imported event and returns 201 with the statement and its lines.

Body application/json

bank_account_refstring · optional
statement_referencestring · optional
statement_datestring · optional
csvstring · optional

Returns

200 Success

Errors 400 · 403 · 404 · 409

Permissions payments:write · Roles: admin, billing_clerk, finance, owner

curl -X POST "$BUSINESS_API/bank-statements" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "bank_account_ref": "bank account ref",
  "statement_reference": "STA-2026-000142",
  "statement_date": "2026-11-19",
  "csv": "csv"
}'
Response 200

Success

Unmatched bank lines review queue

Logs

GET /bank-statements/unmatched-lines

Returns the lines of every statement of the tenant that are still unmatched, across all imports, with cursor pagination (limit defaults to 20, at most 100). This is the review queue for credits that could not be matched automatically and for debits, which are never auto-matched. Requires payments:read.

Parameters

limitinteger · query · optional

Maximum resources to return (default 20, maximum 100).

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Success

Errors 400 · 403 · 404 · 409

Permissions payments:read · Roles: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

curl -X GET "$BUSINESS_API/bank-statements/unmatched-lines" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Success

Get a bank statement

Logs

GET /bank-statements/{id}

Returns one imported statement with its bank account reference, statement reference and date, currency, line count and status. Lines are listed separately. Answers 404 when the statement is not in the caller's tenant.

Parameters

idstring · path · required

Identifier of the bank statement (prefix stm_).

Returns

200 Success

Errors 400 · 403 · 404 · 409

Permissions payments:read · Roles: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

curl -X GET "$BUSINESS_API/bank-statements/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Success

List a statement's lines, optionally by status

Logs

GET /bank-statements/{id}/lines

Returns the lines of one statement in import order with cursor pagination (limit defaults to 20, at most 100). Pass status (unmatched, matched or ignored) to see only lines in that review state. Each line shows its amount, value date, reference and, when matched, the payment and who matched it.

Parameters

idstring · path · required

Identifier of the bank statement whose lines to list (prefix stm_).

limitinteger · query · optional

Maximum resources to return (default 20, maximum 100).

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Success

Errors 400 · 403 · 404 · 409

Permissions payments:read · Roles: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

curl -X GET "$BUSINESS_API/bank-statements/{id}/lines" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Success

Manually match a line to a payment

Logs

POST /bank-statements/lines/{id}/match

Links an unmatched line to the payment named in the body, moves that payment from posted to reconciled and records who matched it, with an optional note. The line must be unmatched and the payment posted (409 otherwise), and the amounts must be equal (400 otherwise). Returns the updated line.

Parameters

idstring · path · required

Identifier of the unmatched statement line to match (prefix sln_).

Body application/json

payment_idstring · optional
notestring · optional

Returns

200 Success

Errors 400 · 403 · 404 · 409

Permissions payments:write · Roles: admin, billing_clerk, finance, owner

curl -X POST "$BUSINESS_API/bank-statements/lines/{id}/match" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "payment_id": "pay_2eUBfC8BJA6JLIoHrQwtN0GL1mW",
  "note": "Leitura confirmada no local."
}'
Response 200

Success

Return a matched line to review

Logs

POST /bank-statements/lines/{id}/unmatch

Returns a matched line to the unmatched queue and moves its payment from reconciled back to posted, clearing who matched it. An optional note query parameter is stored as the review note. A line that is not matched answers 409.

Parameters

idstring · path · required

Identifier of the matched statement line to unmatch (prefix sln_).

Returns

200 Success

Errors 400 · 403 · 404 · 409

Permissions payments:write · Roles: admin, billing_clerk, finance, owner

curl -X POST "$BUSINESS_API/bank-statements/lines/{id}/unmatch" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Success

Retire a line that needs no payment

Logs

POST /bank-statements/lines/{id}/ignore

Marks an unmatched line as ignored, for money that needs no payment such as a bank fee or an internal transfer, and stores the required note. Only an unmatched line can be ignored (409 otherwise), and an empty note answers 400. Returns the updated line.

Parameters

idstring · path · required

Identifier of the statement line to ignore (prefix sln_).

Body application/json

notestring · optional

Returns

200 Success

Errors 400 · 403 · 404 · 409

Permissions payments:write · Roles: admin, billing_clerk, finance, owner

curl -X POST "$BUSINESS_API/bank-statements/lines/{id}/ignore" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "note": "Leitura confirmada no local."
}'
Response 200

Success

Book a payment from an unmatched line and match it

Logs

POST /bank-statements/lines/{id}/create-payment

Records a bank transfer payment on the account in the body for the line's amount, dated at the line's value date and referenced with the line's reference (or BANK-<line id> when empty), allocates it to the account's open invoices, reconciles it and matches the line. Only an unmatched credit line qualifies; anything else answers 409. The payment uses an idempotency key derived from the line, so a repeated call does not book a second payment. Returns 201 with the updated line.

Parameters

idstring · path · required

Identifier of the unmatched credit statement line (prefix sln_).

Body application/json

account_idstring · optional
notestring · optional

Returns

200 Success

Errors 400 · 403 · 404 · 409

Permissions payments:write · Roles: admin, billing_clerk, finance, owner

curl -X POST "$BUSINESS_API/bank-statements/lines/{id}/create-payment" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "note": "Leitura confirmada no local."
}'
Response 200

Success