Books: bank and inbox

34 operations in the Tolvi API, version 1. Paths are relative to https://api.tolvi.co.uk. Every amount is integer pence.

Can a bank be connected?

GET/api/v1/books/bank/providers

Scopes: books:read

Whether open-banking connections are available to this business (and if not, why), and the banks to pick from when the provider doesn’t show its own picker. Statement files always work. Part of the books product: the firm must have it and you must have access to it.

Responses

200 OK, `application/json`

Body: object (BooksBankProviderInfo).

200 OK response for GET /api/v1/books/bank/providers
Field	Type	Description
`available`required	`boolean`	Whether this business can connect a bank. Statement files always work.
`reason`required	`string (BooksBankUnavailableReason)`nullable	Why available is false: not_configured (the provider’s keys aren’t set), or sandbox_restricted (the provider is in its sandbox and this business isn’t one of the few allowed to try it). Null when available. One of: `not_configured`, `sandbox_restricted`
`message`required	`string`nullable	Why, in plain English, when available is false.
`provider`required	`string (BooksBankProvider)`nullable	One of: `truelayer`, `yapily`, `fake`
`environment`required	`string (BooksBankEnvironment)`	One of: `sandbox`, `live`
`banks`required	`array of BooksBankOption`	Banks to pick from; empty when the provider shows its own picker.
`banks[].id`required	`string`
`banks[].name`required	`string`
`chooseBank`required	`boolean`	The person chooses their bank in Tolvi before connecting (send its id as bankId): Yapily has no picker of its own.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).

List bank accounts

GET/api/v1/books/bank/accounts

Scopes: books:read

Each account with its connection (and where it stands against the 90-day reconfirmation), its balance in the books, the bank’s balance, pending lines and how many lines are still to explain. Part of the books product: the firm must have it and you must have access to it.

Responses

200 OK, `application/json`

Body: object (BooksBankAccountList).

200 OK response for GET /api/v1/books/bank/accounts
Field	Type	Description
`items`required	`array of BooksBankAccount`
`items[].id`required	`string (uuid)`
`items[].name`required	`string`
`items[].kind`required	`string (BooksBankAccountKind)`	One of: `current`, `savings`, `credit_card`, `other`
`items[].bankName`required	`string`nullable
`items[].sortCode`required	`string`nullable
`items[].accountNumberEnding`required	`string`nullable	The last four digits only.
`items[].currency`required	`string`
`items[].ledgerAccountId`required	`string (uuid)`
`items[].ledgerAccountCode`required	`string`
`items[].ledgerAccountName`required	`string`
`items[].connection`required	`object (BooksBankConnection)`nullable	Null for an account kept up to date with statement files.
`items[].connection.id`required	`string (uuid)`
`items[].connection.provider`required	`string (BooksBankProvider)`	One of: `truelayer`, `yapily`, `fake`
`items[].connection.status`required	`string (BooksBankConnectionStatus)`	One of: `pending`, `active`, `expired`, `revoked`, `error`
`items[].connection.bankName`required	`string`nullable
`items[].connection.consentState`required	`string (BooksBankConsentState)`nullable	Where the connection stands against the 90 days. reconfirm_soon: in the last 14 days. One of: `active`, `reconfirm_soon`, `reconfirm_required`, `revoked`
`items[].connection.consentExpiresAt`required	`string (date-time)`nullable
`items[].connection.daysLeft`required	`integer`nullable	Whole days until access stops; negative once it has.
`items[].connection.lastSyncedAt`required	`string (date-time)`nullable
`items[].connection.lastError`required	`string`nullable	Why the last sync didn’t work, in plain English.
`items[].connection.createdAt`required	`string (date-time)`
`items[].lastSyncedAt`required	`string (date-time)`nullable
`items[].bankBalancePence`required	`integer`nullable	Integer pence (GBP). The bank’s own balance at the last sync.
`items[].bankBalanceAt`required	`string (date-time)`nullable
`items[].statementBalancePence`required	`integer`nullable	Integer pence (GBP).
`items[].statementBalanceDate`required	`string (date)`nullable	example "2026-03-31"
`items[].ledgerBalancePence`required	`integer`	Integer pence (GBP). The balance in the books (money in the account positive).
`items[].toExplain`required	`integer`	Lines still to explain.
`items[].pending`required	`array of BooksBankPendingLine`
`items[].pending[].date`required	`string (date)`	example "2026-03-31"
`items[].pending[].description`required	`string`
`items[].pending[].amountPence`required	`integer`	Integer pence (GBP). Money in positive, money out negative.
`items[].createdAt`required	`string (date-time)`
`connections`required	`array of BooksBankConnection`	Every bank connection, including ones waiting for the person to pick accounts.
`connections[].id`required	`string (uuid)`
`connections[].provider`required	`string (BooksBankProvider)`	One of: `truelayer`, `yapily`, `fake`
`connections[].status`required	`string (BooksBankConnectionStatus)`	One of: `pending`, `active`, `expired`, `revoked`, `error`
`connections[].bankName`required	`string`nullable
`connections[].consentState`required	`string (BooksBankConsentState)`nullable	Where the connection stands against the 90 days. reconfirm_soon: in the last 14 days. One of: `active`, `reconfirm_soon`, `reconfirm_required`, `revoked`
`connections[].consentExpiresAt`required	`string (date-time)`nullable
`connections[].daysLeft`required	`integer`nullable	Whole days until access stops; negative once it has.
`connections[].lastSyncedAt`required	`string (date-time)`nullable
`connections[].lastError`required	`string`nullable	Why the last sync didn’t work, in plain English.
`connections[].createdAt`required	`string (date-time)`

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).

Add a bank account kept by statements

POST/api/v1/books/bank/accounts

Scopes: books:write
Retries: Send an Idempotency-Key to make retries safe.

For a bank without a feed: upload its statements. Tied to an account in the books (the one given, a free bank account, or a new one). The business’s owners and admins, or an accountant whose access can post. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/bank/accounts
Name	In	Type	Description
`Idempotency-Key`	header	`string`	A unique key (1-255 visible characters) to make retries safe. Replayed for 24 hours. 1 to 255 characters

Request body

Required. application/json: object (BooksBankCreateAccount).

Request body for POST /api/v1/books/bank/accounts
Field	Type	Description
`name`required	`string`	up to 120 characters
`kind`	`string (BooksBankAccountKind)`	One of: `current`, `savings`, `credit_card`, `other`
`bankName`	`string`
`sortCode`	`string`	example "12-34-56"
`accountNumber`	`string`
`ledgerAccountId`	`string (uuid)`	The ledger account; left out, Tolvi picks a free one or adds one.

Responses

201 Created, `application/json`

Body: object (BooksBankAccount).

A business bank, savings or card account, tied to one account in the books.

201 Created response for POST /api/v1/books/bank/accounts
Field	Type	Description
`id`required	`string (uuid)`
`name`required	`string`
`kind`required	`string (BooksBankAccountKind)`	One of: `current`, `savings`, `credit_card`, `other`
`bankName`required	`string`nullable
`sortCode`required	`string`nullable
`accountNumberEnding`required	`string`nullable	The last four digits only.
`currency`required	`string`
`ledgerAccountId`required	`string (uuid)`
`ledgerAccountCode`required	`string`
`ledgerAccountName`required	`string`
`connection`required	`object (BooksBankConnection)`nullable	Null for an account kept up to date with statement files.
`connection.id`required	`string (uuid)`
`connection.provider`required	`string (BooksBankProvider)`	One of: `truelayer`, `yapily`, `fake`
`connection.status`required	`string (BooksBankConnectionStatus)`	One of: `pending`, `active`, `expired`, `revoked`, `error`
`connection.bankName`required	`string`nullable
`connection.consentState`required	`string (BooksBankConsentState)`nullable	Where the connection stands against the 90 days. reconfirm_soon: in the last 14 days. One of: `active`, `reconfirm_soon`, `reconfirm_required`, `revoked`
`connection.consentExpiresAt`required	`string (date-time)`nullable
`connection.daysLeft`required	`integer`nullable	Whole days until access stops; negative once it has.
`connection.lastSyncedAt`required	`string (date-time)`nullable
`connection.lastError`required	`string`nullable	Why the last sync didn’t work, in plain English.
`connection.createdAt`required	`string (date-time)`
`lastSyncedAt`required	`string (date-time)`nullable
`bankBalancePence`required	`integer`nullable	Integer pence (GBP). The bank’s own balance at the last sync.
`bankBalanceAt`required	`string (date-time)`nullable
`statementBalancePence`required	`integer`nullable	Integer pence (GBP).
`statementBalanceDate`required	`string (date)`nullable	example "2026-03-31"
`ledgerBalancePence`required	`integer`	Integer pence (GBP). The balance in the books (money in the account positive).
`toExplain`required	`integer`	Lines still to explain.
`pending`required	`array of BooksBankPendingLine`
`pending[].date`required	`string (date)`	example "2026-03-31"
`pending[].description`required	`string`
`pending[].amountPence`required	`integer`	Integer pence (GBP). Money in positive, money out negative.
`createdAt`required	`string (date-time)`

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 409 Conflict, 422 Unprocessable content, 429 Too many requests, as problem details (application/problem+json).

Get a bank account

GET/api/v1/books/bank/accounts/{id}

Scopes: books:read

Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/books/bank/accounts/{id}
Name	In	Type	Description
`id`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (BooksBankAccount).

A business bank, savings or card account, tied to one account in the books.

The fields are as shown above.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

Rename a bank account or record its statement balance

PATCH/api/v1/books/bank/accounts/{id}

Scopes: books:write

The statement balance and its date are what reconciliation checks the books against. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for PATCH /api/v1/books/bank/accounts/{id}
Name	In	Type	Description
`id`required	path	`string (uuid)`

Request body

Required. application/json: object (BooksBankUpdateAccount).

Request body for PATCH /api/v1/books/bank/accounts/{id}
Field	Type	Description
`name`	`string`
`statementBalancePence`	`integer`nullable	Integer pence (GBP).
`statementBalanceDate`	`string (date)`nullable	example "2026-03-31"

Responses

200 OK, `application/json`

Body: object (BooksBankAccount).

A business bank, savings or card account, tied to one account in the books.

The fields are as shown above.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

Reconcile a bank account

GET/api/v1/books/bank/accounts/{id}/reconciliation

Scopes: books:read

The statement (or bank) balance against the balance in the books, and what makes up the difference: lines not yet explained, entries in the books no bank line explains, and anything still to find. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/books/bank/accounts/{id}/reconciliation
Name	In	Type	Description
`id`required	path	`string (uuid)`
`asAt`	query	`string (date)`	Default: the latest statement balance’s date, else today with the bank’s balance.

Responses

200 OK, `application/json`

Body: object (BooksBankReconciliation).

The statement (or bank) balance against the balance in the books, with the difference explained.

200 OK response for GET /api/v1/books/bank/accounts/{id}/reconciliation
Field	Type	Description
`bankAccountId`required	`string (uuid)`
`asAt`required	`string (date)`	example "2026-03-31"
`statementBalancePence`required	`integer`nullable	Integer pence (GBP).
`statementSource`required	`string (BooksBankBalanceSource)`nullable	One of: `statement`, `bank_feed`, `running_balance`
`ledgerBalancePence`required	`integer`	Integer pence (GBP).
`differencePence`required	`integer`nullable	Integer pence (GBP).
`items`required	`array of BooksBankReconciliationItem`
`items[].kind`required	`string (BooksBankReconciliationKind)`	One of: `to_explain`, `not_on_statement`, `unexplained`
`items[].label`required	`string`
`items[].count`required	`integer`
`items[].amountPence`required	`integer`	Integer pence (GBP).
`reconciled`required	`boolean`	The difference is fully explained.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

Preview a statement file

POST/api/v1/books/bank/accounts/{id}/imports/preview

Scopes: books:write

Reads the file without storing anything: its format, lines, what is new and the rows left out; or, for a CSV Tolvi doesn’t recognise, its headings to choose the columns from. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/bank/accounts/{id}/imports/preview
Name	In	Type	Description
`id`required	path	`string (uuid)`

Request body

Required. application/json: object (BooksBankStatementFile).

Request body for POST /api/v1/books/bank/accounts/{id}/imports/preview
Field	Type	Description
`fileName`required	`string`
`contentBase64`required	`string`	The file, base64 encoded (CSV, OFX, QFX, QIF or Santander’s text download; up to 8 MB).
`columns`	`object`	For an unrecognised CSV: { date, amount \| paidIn + paidOut, description: [..], headerRow?, amountSign? } (0-based columns).

Responses

200 OK, `application/json`

Body: object (BooksBankStatementPreview).

200 OK response for POST /api/v1/books/bank/accounts/{id}/imports/preview
Field	Type	Description
`needsColumns`required	`boolean`	True when Tolvi needs the columns chosen (see csv).
`csv`required	`object (BooksBankCsvColumns)`nullable	For a CSV Tolvi doesn’t recognise: the headings and first rows, for choosing the columns.
`csv.headers`required	`array of string`
`csv.sample`required	`array of array of string`	The first rows, each an array of cells.
`csv.suggested`required	`object`	Tolvi’s best guess at the columns (0-based indexes).
`csv.headerRow`required	`integer`nullable
`format`required	`string`nullable	example "csv"
`layout`required	`string`nullable	example "barclays"
`linesFound`required	`integer`
`linesNew`required	`integer`
`linesAlreadyIn`required	`integer`
`periodFrom`required	`string (date)`nullable	example "2026-03-31"
`periodTo`required	`string (date)`nullable	example "2026-03-31"
`closingBalancePence`required	`integer`nullable	Integer pence (GBP).
`issues`required	`array of BooksBankStatementIssue`	Rows left out.
`issues[].row`required	`integer`nullable	The 1-based row or record number.
`issues[].message`required	`string`
`sample`required	`array of BooksBankStatementLine`
`sample[].bookedAt`required	`string (date)`	example "2026-03-31"
`sample[].description`required	`string`
`sample[].amountPence`required	`integer`	Integer pence (GBP).
`sample[].alreadyIn`required	`boolean`	Already in the books from an earlier file or the bank feed.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

Import a statement file

POST/api/v1/books/bank/accounts/{id}/imports

Scopes: books:write
Retries: Send an Idempotency-Key to make retries safe.

CSV, OFX/QFX, QIF or Santander’s text download. Lines already in the books (same id, or same date, amount, description and balance) are skipped, so overlapping files are safe. Tolvi then suggests what each new line is. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/bank/accounts/{id}/imports
Name	In	Type	Description
`id`required	path	`string (uuid)`
`Idempotency-Key`	header	`string`	A unique key (1-255 visible characters) to make retries safe. Replayed for 24 hours. 1 to 255 characters

Request body

Required. application/json: object (BooksBankStatementFile).

Request body for POST /api/v1/books/bank/accounts/{id}/imports
Field	Type	Description
`fileName`required	`string`
`contentBase64`required	`string`	The file, base64 encoded (CSV, OFX, QFX, QIF or Santander’s text download; up to 8 MB).
`columns`	`object`	For an unrecognised CSV: { date, amount \| paidIn + paidOut, description: [..], headerRow?, amountSign? } (0-based columns).

Responses

201 Created, `application/json`

Body: object (BooksBankImport).

201 Created response for POST /api/v1/books/bank/accounts/{id}/imports
Field	Type	Description
`id`required	`string (uuid)`
`bankAccountId`required	`string (uuid)`
`fileName`required	`string`
`format`required	`string`
`linesFound`required	`integer`
`linesAdded`required	`integer`
`linesAlreadyIn`required	`integer`
`issues`required	`array of BooksBankStatementIssue`
`issues[].row`required	`integer`nullable	The 1-based row or record number.
`issues[].message`required	`string`
`periodFrom`required	`string (date)`nullable	example "2026-03-31"
`periodTo`required	`string (date)`nullable	example "2026-03-31"
`createdAt`required	`string (date-time)`

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 409 Conflict, 422 Unprocessable content, 429 Too many requests, as problem details (application/problem+json).

Connect a bank

POST/api/v1/books/bank/connections

Scopes: books:admin
Access: A signed-in Tolvi session only, never an API token.

Returns the provider’s link: the person signs in at their bank there and is sent back to Tolvi Books (see callback). When providers.chooseBank is true (Yapily) bankId is required (422 without it). Read-only access, renewed every 90 days. Owners and admins, signed in. 503 when bank connections aren’t switched on. Part of the books product: the firm must have it and you must have access to it.

Request body

Required. application/json: object (BooksBankStartConnection).

Request body for POST /api/v1/books/bank/connections
Field	Type	Description
`bankId`	`string`	The provider’s id for the bank the person chose (from providers.banks). Required when providers.chooseBank is true; otherwise it skips the provider’s own picker.

Responses

201 Created, `application/json`

Body: object (BooksBankConnectStart).

201 Created response for POST /api/v1/books/bank/connections
Field	Type	Description
`connectionId`required	`string (uuid)`
`url`required	`string`	Send the person’s browser here. The provider handles the bank’s sign-in, then returns to Tolvi with a code.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).

Finish connecting a bank

POST/api/v1/books/bank/connections/callback

Scopes: books:admin
Access: A signed-in Tolvi session only, never an API token.

Send what the provider put on the redirect (state, and code or error). Returns the accounts the bank shared, to choose which to add. Part of the books product: the firm must have it and you must have access to it.

Request body

Required. application/json: object (BooksBankConnectionCallback).

What the provider sent back on the redirect.

Request body for POST /api/v1/books/bank/connections/callback
Field	Type	Description
`state`required	`string`
`code`	`string`
`error`	`string`
`errorDescription`	`string`
`params`	`object`	Every query parameter the provider sent back, as is. The provider reads its own (Yapily sends a one-time token, not a code). Up to 30.

Responses

200 OK, `application/json`

Body: object (BooksBankConnectionAccounts).

200 OK response for POST /api/v1/books/bank/connections/callback
Field	Type	Description
`connection`required	`object (BooksBankConnection)`	One consent at one bank, through the open-banking provider. Access lasts 90 days at a time; the person reconfirms it in Tolvi (FCA SCA-RTS Article 10A).
`connection.id`required	`string (uuid)`
`connection.provider`required	`string (BooksBankProvider)`	One of: `truelayer`, `yapily`, `fake`
`connection.status`required	`string (BooksBankConnectionStatus)`	One of: `pending`, `active`, `expired`, `revoked`, `error`
`connection.bankName`required	`string`nullable
`connection.consentState`required	`string (BooksBankConsentState)`nullable	Where the connection stands against the 90 days. reconfirm_soon: in the last 14 days. One of: `active`, `reconfirm_soon`, `reconfirm_required`, `revoked`
`connection.consentExpiresAt`required	`string (date-time)`nullable
`connection.daysLeft`required	`integer`nullable	Whole days until access stops; negative once it has.
`connection.lastSyncedAt`required	`string (date-time)`nullable
`connection.lastError`required	`string`nullable	Why the last sync didn’t work, in plain English.
`connection.createdAt`required	`string (date-time)`
`accounts`required	`array of BooksBankProviderAccount`
`accounts[].providerAccountId`required	`string`
`accounts[].name`required	`string`
`accounts[].kind`required	`string (BooksBankAccountKind)`	One of: `current`, `savings`, `credit_card`, `other`
`accounts[].sortCode`required	`string`nullable
`accounts[].accountNumberEnding`required	`string`nullable	The last four digits only.
`accounts[].currency`required	`string`
`accounts[].bankAccountId`required	`string (uuid)`nullable	Already in Tolvi as this bank account.
`accounts[].suggestedLedgerAccountId`required	`string (uuid)`nullable	The ledger account Tolvi suggests; null means Tolvi adds one.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).

The accounts a bank shared

GET/api/v1/books/bank/connections/{id}/accounts

Scopes: books:admin
Access: A signed-in Tolvi session only, never an API token.

Each with whether it is already added and the account in the books Tolvi would use. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/books/bank/connections/{id}/accounts
Name	In	Type	Description
`id`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (BooksBankConnectionAccounts).

The fields are as shown above.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

Add accounts from a connected bank

POST/api/v1/books/bank/connections/{id}/accounts

Scopes: books:admin
Access: A signed-in Tolvi session only, never an API token.

Each is tied to an account in the books (the one given, a free bank account, or a new one) and read straight away. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/bank/connections/{id}/accounts
Name	In	Type	Description
`id`required	path	`string (uuid)`

Request body

Required. application/json: object (BooksBankAddAccounts).

Request body for POST /api/v1/books/bank/connections/{id}/accounts
Field	Type	Description
`accounts`required	`array of BooksBankAddAccount`
`accounts[].providerAccountId`required	`string`
`accounts[].ledgerAccountId`	`string (uuid)`
`accounts[].name`	`string`

Responses

200 OK, `application/json`

Body: object (BooksBankAccountList).

The fields are as shown above.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

Keep sharing for another 90 days

POST/api/v1/books/bank/connections/{id}/reconfirm

Scopes: books:admin
Access: A signed-in Tolvi session only, never an API token.

The person’s explicit reconfirmation (FCA SCA-RTS Article 10A). When the bank wants them to sign in again, url says where to send them. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/bank/connections/{id}/reconfirm
Name	In	Type	Description
`id`required	path	`string (uuid)`

Request body

Required. application/json: object (BooksBankReconfirm).

Request body for POST /api/v1/books/bank/connections/{id}/reconfirm
Field	Type	Description
`keepSharing`required	`boolean`	Must be true: the person ticked “Keep sharing”.

Responses

200 OK, `application/json`

Body: object (BooksBankReconfirmResult).

200 OK response for POST /api/v1/books/bank/connections/{id}/reconfirm
Field	Type	Description
`connection`required	`object (BooksBankConnection)`	One consent at one bank, through the open-banking provider. Access lasts 90 days at a time; the person reconfirms it in Tolvi (FCA SCA-RTS Article 10A).
`connection.id`required	`string (uuid)`
`connection.provider`required	`string (BooksBankProvider)`	One of: `truelayer`, `yapily`, `fake`
`connection.status`required	`string (BooksBankConnectionStatus)`	One of: `pending`, `active`, `expired`, `revoked`, `error`
`connection.bankName`required	`string`nullable
`connection.consentState`required	`string (BooksBankConsentState)`nullable	Where the connection stands against the 90 days. reconfirm_soon: in the last 14 days. One of: `active`, `reconfirm_soon`, `reconfirm_required`, `revoked`
`connection.consentExpiresAt`required	`string (date-time)`nullable
`connection.daysLeft`required	`integer`nullable	Whole days until access stops; negative once it has.
`connection.lastSyncedAt`required	`string (date-time)`nullable
`connection.lastError`required	`string`nullable	Why the last sync didn’t work, in plain English.
`connection.createdAt`required	`string (date-time)`
`url`required	`string`nullable	When the bank wants the person to sign in again: send them here.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

Disconnect a bank

POST/api/v1/books/bank/connections/{id}/disconnect

Scopes: books:admin
Access: A signed-in Tolvi session only, never an API token.

Ends Tolvi’s access at the provider and forgets the tokens. The accounts and their lines stay; statements can still be uploaded. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/bank/connections/{id}/disconnect
Name	In	Type	Description
`id`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (BooksBankConnection).

One consent at one bank, through the open-banking provider. Access lasts 90 days at a time; the person reconfirms it in Tolvi (FCA SCA-RTS Article 10A).

200 OK response for POST /api/v1/books/bank/connections/{id}/disconnect
Field	Type	Description
`id`required	`string (uuid)`
`provider`required	`string (BooksBankProvider)`	One of: `truelayer`, `yapily`, `fake`
`status`required	`string (BooksBankConnectionStatus)`	One of: `pending`, `active`, `expired`, `revoked`, `error`
`bankName`required	`string`nullable
`consentState`required	`string (BooksBankConsentState)`nullable	Where the connection stands against the 90 days. reconfirm_soon: in the last 14 days. One of: `active`, `reconfirm_soon`, `reconfirm_required`, `revoked`
`consentExpiresAt`required	`string (date-time)`nullable
`daysLeft`required	`integer`nullable	Whole days until access stops; negative once it has.
`lastSyncedAt`required	`string (date-time)`nullable
`lastError`required	`string`nullable	Why the last sync didn’t work, in plain English.
`createdAt`required	`string (date-time)`

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

Read the bank now

POST/api/v1/books/bank/connections/{id}/sync

Scopes: books:write

Tolvi also reads each bank a few times a day. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/bank/connections/{id}/sync
Name	In	Type	Description
`id`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (BooksBankConnection).

One consent at one bank, through the open-banking provider. Access lasts 90 days at a time; the person reconfirms it in Tolvi (FCA SCA-RTS Article 10A).

The fields are as shown above.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

List bank lines

GET/api/v1/books/bank/lines

Scopes: books:read

Newest first, with Tolvi’s suggestion and its “Why?” for each line still to explain. Money in positive, money out negative. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/books/bank/lines
Name	In	Type	Description
`q`	query	`string`	Search: words in the description, payee or reference, or an amount (12.50). up to 100 characters
`offset`	query	`integer`	at least 0; default 0
`limit`	query	`integer`	1 to 500; default 200
`to`	query	`string (date)`
`from`	query	`string (date)`
`status`	query	`string`	One of: `to_explain`, `explained`, `excluded`, `all`
`bankAccountId`	query	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (BooksBankLineList).

200 OK response for GET /api/v1/books/bank/lines
Field	Type	Description
`items`required	`array of BooksBankLine`
`items[].id`required	`string (uuid)`
`items[].bankAccountId`required	`string (uuid)`
`items[].source`required	`string (BooksBankLineSource)`	One of: `feed`, `csv`, `ofx`, `qif`, `manual`
`items[].bookedAt`required	`string (date)`	example "2026-03-31"
`items[].description`required	`string`
`items[].counterparty`required	`string`nullable
`items[].reference`required	`string`nullable
`items[].payee`required	`string`nullable	Who it was paid to or received from, cleaned up.
`items[].amountPence`required	`integer`	Integer pence (GBP).
`items[].currency`required	`string`
`items[].runningBalancePence`required	`integer`nullable	Integer pence (GBP).
`items[].status`required	`string (BooksBankLineStatus)`	to_explain, explained (in the books), or excluded (set aside). One of: `to_explain`, `explained`, `excluded`
`items[].suggestion`required	`object (BooksBankSuggestion)`nullable	What Tolvi suggests for a line and why. Only an owner’s rule set to post automatically ever posts without a tap.
`items[].suggestion.level`required	`string (BooksBankSuggestionLevel)`	One of: `sorted`, `suggested`, `question`
`items[].suggestion.stage`required	`string (BooksBankSuggestionStage)`	Which step decided: a possible copy, a match, your rule, what you did before, Tolvi AI, or nothing yet (for_ai). One of: `duplicate`, `matched`, `ruled`, `remembered`, `ai`, `for_ai`
`items[].suggestion.summary`required	`string`
`items[].suggestion.reasons`required	`array of string`	The “Why?”.
`items[].suggestion.kind`required	`string (BooksBankSuggestionKind)`	One of: `category`, `transfer`, `match`, `duplicate`, `none`
`items[].suggestion.categorisation`required	`object (BooksBankCategorisation)`nullable	A category (account code) and VAT code; a split gives each part’s share in basis points.
`items[].suggestion.categorisation.accountCode`required	`string`
`items[].suggestion.categorisation.accountName`required	`string`nullable
`items[].suggestion.categorisation.vatCode`required	`string`nullable	Null or NONE: no VAT.
`items[].suggestion.categorisation.split`required	`array of BooksBankSplitPart`	Empty when not split.
`items[].suggestion.categorisation.split[].accountCode`required	`string`
`items[].suggestion.categorisation.split[].vatCode`required	`string`nullable
`items[].suggestion.categorisation.split[].shareBps`required	`integer`	1 to 9999
`items[].suggestion.transferBankAccountId`required	`string (uuid)`nullable
`items[].suggestion.otherLineId`required	`string (uuid)`nullable
`items[].suggestion.documentKind`required	`string (BooksBankDocumentKind)`nullable	One of: `receipt`, `sales_invoice`, `sales_credit_note`, `bill`, `supplier_credit`, `vat_return`, `loan_repayment`
`items[].suggestion.documentIds`required	`array of string`
`items[].suggestion.duplicateOfId`required	`string (uuid)`nullable
`items[].suggestion.ruleId`required	`string (uuid)`nullable
`items[].suggestion.ruleName`required	`string`nullable
`items[].suggestion.candidates`required	`array of BooksBankCandidate`	Other possible matches, best first.
`items[].suggestion.candidates[].summary`required	`string`
`items[].suggestion.candidates[].score`required	`integer`	0 to 100
`items[].suggestion.candidates[].band`required	`string (BooksBankMatchBand)`	One of: `high`, `medium`, `low`
`items[].suggestion.candidates[].kind`required	`string`	transfer, or the kind of document.
`items[].suggestion.candidates[].documentIds`required	`array of string`
`items[].suggestion.candidates[].bankAccountId`required	`string (uuid)`nullable
`items[].suggestion.candidates[].otherLineId`required	`string (uuid)`nullable
`items[].explanation`required	`object (BooksBankExplanation)`nullable	How the line is in the books.
`items[].explanation.kind`required	`string (BooksBankExplanationKind)`	One of: `category`, `transfer`, `match`
`items[].explanation.entryId`required	`string (uuid)`
`items[].explanation.categorisation`required	`object (BooksBankCategorisation)`nullable	A category (account code) and VAT code; a split gives each part’s share in basis points.
`items[].explanation.categorisation.accountCode`required	`string`
`items[].explanation.categorisation.accountName`required	`string`nullable
`items[].explanation.categorisation.vatCode`required	`string`nullable	Null or NONE: no VAT.
`items[].explanation.categorisation.split`required	`array of BooksBankSplitPart`	Empty when not split.
`items[].explanation.categorisation.split[].accountCode`required	`string`
`items[].explanation.categorisation.split[].vatCode`required	`string`nullable
`items[].explanation.categorisation.split[].shareBps`required	`integer`	1 to 9999
`items[].explanation.transferLineId`required	`string (uuid)`nullable
`items[].explanation.receiptId`required	`string (uuid)`nullable
`items[].explanation.ruleId`required	`string (uuid)`nullable	The rule that posted it without a tap.
`items[].explanation.ruleVersion`required	`integer`nullable
`items[].explanation.explainedBy`required	`string (uuid)`nullable
`items[].explanation.explainedAt`required	`string (date-time)`
`items[].bankChange`required	`object`nullable	The bank changed or withdrew this line after Tolvi read it: { kind: corrected \| missing, changed, amountPence, description, bookedAt }.
`items[].createdAt`required	`string (date-time)`
`counts`required	`object (BooksBankLineCounts)`
`counts.toExplain`required	`integer`
`counts.explained`required	`integer`
`counts.excluded`required	`integer`
`total`required	`integer`	Lines matching the filter (for paging with offset).

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).

Confirm a group of lines

POST/api/v1/books/bank/lines/confirm

Scopes: books:write

Each line as suggested, or every line as one category. Each line posts on its own, so one that can’t be posted (a locked period, say) doesn’t stop the rest. Part of the books product: the firm must have it and you must have access to it.

Request body

Required. application/json: object (BooksBankConfirmLines).

Request body for POST /api/v1/books/bank/lines/confirm
Field	Type	Description
`lineIds`required	`array of string`
`categorisation`	`object (BooksBankCategorisationInput)`	The same category for every line; left out, each is confirmed as suggested.
`categorisation.accountCode`required	`string`
`categorisation.vatCode`	`string`nullable
`categorisation.split`	`array of BooksBankSplitPartInput`
`categorisation.split[].accountCode`required	`string`
`categorisation.split[].vatCode`	`string`nullable
`categorisation.split[].shareBps`required	`integer`	1 to 9999

Responses

200 OK, `application/json`

Body: object (BooksBankConfirmResults).

200 OK response for POST /api/v1/books/bank/lines/confirm
Field	Type	Description
`results`required	`array of BooksBankConfirmResult`
`results[].lineId`required	`string (uuid)`
`results[].ok`required	`boolean`
`results[].problem`required	`string`nullable	Why this line wasn’t confirmed.
`confirmed`required	`integer`

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).

Get a bank line

GET/api/v1/books/bank/lines/{id}

Scopes: books:read

Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/books/bank/lines/{id}
Name	In	Type	Description
`id`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (BooksBankLine).

A line from the bank or a statement: what happened, what Tolvi suggests and how it is in the books. Money in positive, money out negative.

200 OK response for GET /api/v1/books/bank/lines/{id}
Field	Type	Description
`id`required	`string (uuid)`
`bankAccountId`required	`string (uuid)`
`source`required	`string (BooksBankLineSource)`	One of: `feed`, `csv`, `ofx`, `qif`, `manual`
`bookedAt`required	`string (date)`	example "2026-03-31"
`description`required	`string`
`counterparty`required	`string`nullable
`reference`required	`string`nullable
`payee`required	`string`nullable	Who it was paid to or received from, cleaned up.
`amountPence`required	`integer`	Integer pence (GBP).
`currency`required	`string`
`runningBalancePence`required	`integer`nullable	Integer pence (GBP).
`status`required	`string (BooksBankLineStatus)`	to_explain, explained (in the books), or excluded (set aside). One of: `to_explain`, `explained`, `excluded`
`suggestion`required	`object (BooksBankSuggestion)`nullable	What Tolvi suggests for a line and why. Only an owner’s rule set to post automatically ever posts without a tap.
`suggestion.level`required	`string (BooksBankSuggestionLevel)`	One of: `sorted`, `suggested`, `question`
`suggestion.stage`required	`string (BooksBankSuggestionStage)`	Which step decided: a possible copy, a match, your rule, what you did before, Tolvi AI, or nothing yet (for_ai). One of: `duplicate`, `matched`, `ruled`, `remembered`, `ai`, `for_ai`
`suggestion.summary`required	`string`
`suggestion.reasons`required	`array of string`	The “Why?”.
`suggestion.kind`required	`string (BooksBankSuggestionKind)`	One of: `category`, `transfer`, `match`, `duplicate`, `none`
`suggestion.categorisation`required	`object (BooksBankCategorisation)`nullable	A category (account code) and VAT code; a split gives each part’s share in basis points.
`suggestion.categorisation.accountCode`required	`string`
`suggestion.categorisation.accountName`required	`string`nullable
`suggestion.categorisation.vatCode`required	`string`nullable	Null or NONE: no VAT.
`suggestion.categorisation.split`required	`array of BooksBankSplitPart`	Empty when not split.
`suggestion.categorisation.split[].accountCode`required	`string`
`suggestion.categorisation.split[].vatCode`required	`string`nullable
`suggestion.categorisation.split[].shareBps`required	`integer`	1 to 9999
`suggestion.transferBankAccountId`required	`string (uuid)`nullable
`suggestion.otherLineId`required	`string (uuid)`nullable
`suggestion.documentKind`required	`string (BooksBankDocumentKind)`nullable	One of: `receipt`, `sales_invoice`, `sales_credit_note`, `bill`, `supplier_credit`, `vat_return`, `loan_repayment`
`suggestion.documentIds`required	`array of string`
`suggestion.duplicateOfId`required	`string (uuid)`nullable
`suggestion.ruleId`required	`string (uuid)`nullable
`suggestion.ruleName`required	`string`nullable
`suggestion.candidates`required	`array of BooksBankCandidate`	Other possible matches, best first.
`suggestion.candidates[].summary`required	`string`
`suggestion.candidates[].score`required	`integer`	0 to 100
`suggestion.candidates[].band`required	`string (BooksBankMatchBand)`	One of: `high`, `medium`, `low`
`suggestion.candidates[].kind`required	`string`	transfer, or the kind of document.
`suggestion.candidates[].documentIds`required	`array of string`
`suggestion.candidates[].bankAccountId`required	`string (uuid)`nullable
`suggestion.candidates[].otherLineId`required	`string (uuid)`nullable
`explanation`required	`object (BooksBankExplanation)`nullable	How the line is in the books.
`explanation.kind`required	`string (BooksBankExplanationKind)`	One of: `category`, `transfer`, `match`
`explanation.entryId`required	`string (uuid)`
`explanation.categorisation`required	`object (BooksBankCategorisation)`nullable	A category (account code) and VAT code; a split gives each part’s share in basis points.
`explanation.categorisation.accountCode`required	`string`
`explanation.categorisation.accountName`required	`string`nullable
`explanation.categorisation.vatCode`required	`string`nullable	Null or NONE: no VAT.
`explanation.categorisation.split`required	`array of BooksBankSplitPart`	Empty when not split.
`explanation.categorisation.split[].accountCode`required	`string`
`explanation.categorisation.split[].vatCode`required	`string`nullable
`explanation.categorisation.split[].shareBps`required	`integer`	1 to 9999
`explanation.transferLineId`required	`string (uuid)`nullable
`explanation.receiptId`required	`string (uuid)`nullable
`explanation.ruleId`required	`string (uuid)`nullable	The rule that posted it without a tap.
`explanation.ruleVersion`required	`integer`nullable
`explanation.explainedBy`required	`string (uuid)`nullable
`explanation.explainedAt`required	`string (date-time)`
`bankChange`required	`object`nullable	The bank changed or withdrew this line after Tolvi read it: { kind: corrected \| missing, changed, amountPence, description, bookedAt }.
`createdAt`required	`string (date-time)`

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

Explain a bank line

POST/api/v1/books/bank/lines/{id}/explain

Scopes: books:write

As suggested; as a category (with VAT, or split); as a transfer to or from another of the business’s accounts; or as the payment for a confirmed receipt. Posts one entry in the books. 422 when it can’t be posted (a locked period, an unknown category), 409 when the line is already explained. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/bank/lines/{id}/explain
Name	In	Type	Description
`id`required	path	`string (uuid)`

Request body

Required. application/json: object (BooksBankExplainLine).

kind: suggested (confirm the suggestion), category ({ accountCode, vatCode?, split? }), transfer ({ toBankAccountId, otherLineId? }), match ({ receiptId, accountCode? }), bill ({ billId }: money out paying a bill, in full or in part) or vat_return ({ submissionId }: a payment to or from HMRC for a filed return).

Request body for POST /api/v1/books/bank/lines/{id}/explain
Field	Type	Description
`kind`required	`string (BooksBankExplainKind)`	One of: `suggested`, `category`, `transfer`, `match`, `bill`, `vat_return`
`billId`	`string (uuid)`
`accountCode`	`string`
`vatCode`	`string`nullable
`split`	`array of BooksBankSplitPartInput`
`split[].accountCode`required	`string`
`split[].vatCode`	`string`nullable
`split[].shareBps`required	`integer`	1 to 9999
`toBankAccountId`	`string (uuid)`
`otherLineId`	`string (uuid)`nullable
`receiptId`	`string (uuid)`
`submissionId`	`string (uuid)`	The filed VAT return this payment settles.

Responses

200 OK, `application/json`

Body: object (BooksBankLine).

A line from the bank or a statement: what happened, what Tolvi suggests and how it is in the books. Money in positive, money out negative.

The fields are as shown above.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

Undo a line’s explanation

POST/api/v1/books/bank/lines/{id}/undo

Scopes: books:write

Posts the reversal of its entry (dated in the first open period if the books are locked) and puts the line back to explain. A matched receipt goes back to waiting for its payment. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/bank/lines/{id}/undo
Name	In	Type	Description
`id`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (BooksBankLine).

A line from the bank or a statement: what happened, what Tolvi suggests and how it is in the books. Money in positive, money out negative.

The fields are as shown above.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

Set a line aside

POST/api/v1/books/bank/lines/{id}/exclude

Scopes: books:write

A copy of another line, or nothing to do with the business: it stays in the list but never in the books. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/bank/lines/{id}/exclude
Name	In	Type	Description
`id`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (BooksBankLine).

A line from the bank or a statement: what happened, what Tolvi suggests and how it is in the books. Money in positive, money out negative.

The fields are as shown above.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

Bring back a line set aside

POST/api/v1/books/bank/lines/{id}/include

Scopes: books:write

Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/bank/lines/{id}/include
Name	In	Type	Description
`id`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (BooksBankLine).

A line from the bank or a statement: what happened, what Tolvi suggests and how it is in the books. Money in positive, money out negative.

The fields are as shown above.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

List rules

GET/api/v1/books/bank/rules

Scopes: books:read

Each rule’s current version, as a sentence, with how many lines it has explained. Part of the books product: the firm must have it and you must have access to it.

Responses

200 OK, `application/json`

Body: array of BooksBankRule.

An owner’s (or accountant’s) rule, current version. It suggests, or posts without a tap only when the owner chose that.

200 OK response for GET /api/v1/books/bank/rules
Field	Type	Description
`[].id`required	`string (uuid)`
`[].version`required	`integer`
`[].name`required	`string`nullable
`[].description`required	`string`	The rule as a sentence.
`[].enabled`required	`boolean`
`[].priority`required	`integer`
`[].match`required	`string (BooksBankRuleMatch)`	One of: `all`, `any`
`[].conditions`required	`array of BooksBankRuleCondition`
`[].conditions[].field`required	`string (BooksBankRuleField)`	One of: `description`, `merchant`, `counterparty`, `reference`, `amount`, `direction`, `payment_type`, `bank_account`
`[].conditions[].op`required	`string`	example "contains"
`[].conditions[].value`	`string`
`[].conditions[].pence`	`integer`	at least 0
`[].conditions[].toPence`	`integer`	Integer pence (GBP). at least 0
`[].categorise`required	`object (BooksBankCategorisation)`	A category (account code) and VAT code; a split gives each part’s share in basis points.
`[].categorise.accountCode`required	`string`
`[].categorise.accountName`required	`string`nullable
`[].categorise.vatCode`required	`string`nullable	Null or NONE: no VAT.
`[].categorise.split`required	`array of BooksBankSplitPart`	Empty when not split.
`[].categorise.split[].accountCode`required	`string`
`[].categorise.split[].vatCode`required	`string`nullable
`[].categorise.split[].shareBps`required	`integer`	1 to 9999
`[].postWithoutAsking`required	`boolean`
`[].autoPostLimitPence`required	`integer`nullable	Integer pence (GBP).
`[].createdBy`required	`string (BooksBankRuleAuthor)`	One of: `owner`, `accountant`
`[].applied`required	`integer`	Lines this rule explained (all versions).
`[].updatedAt`required	`string (date-time)`

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).

Add a rule

POST/api/v1/books/bank/rules

Scopes: books:write
Retries: Send an Idempotency-Key to make retries safe.

A rule needs a condition on the description, payee, reference or amount. postWithoutAsking: only the business’s owners and admins, signed in; even then a possible copy, a locked period, an unusual amount or a VAT-sensitive code is left for a person. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/bank/rules
Name	In	Type	Description
`Idempotency-Key`	header	`string`	A unique key (1-255 visible characters) to make retries safe. Replayed for 24 hours. 1 to 255 characters

Request body

Required. application/json: object (BooksBankRuleInput).

Request body for POST /api/v1/books/bank/rules
Field	Type	Description
`name`	`string`
`priority`	`integer`
`enabled`	`boolean`
`match`	`string (BooksBankRuleMatch)`	One of: `all`, `any`
`conditions`required	`array of BooksBankRuleCondition`
`conditions[].field`required	`string (BooksBankRuleField)`	One of: `description`, `merchant`, `counterparty`, `reference`, `amount`, `direction`, `payment_type`, `bank_account`
`conditions[].op`required	`string`	example "contains"
`conditions[].value`	`string`
`conditions[].pence`	`integer`	at least 0
`conditions[].toPence`	`integer`	Integer pence (GBP). at least 0
`categorise`required	`object (BooksBankCategorisationInput)`	An account code and VAT code (null: no VAT), or a split.
`categorise.accountCode`required	`string`
`categorise.vatCode`	`string`nullable
`categorise.split`	`array of BooksBankSplitPartInput`
`categorise.split[].accountCode`required	`string`
`categorise.split[].vatCode`	`string`nullable
`categorise.split[].shareBps`required	`integer`	1 to 9999
`postWithoutAsking`	`boolean`	Post matching lines without a tap. The business’s owners and admins only, signed in.
`autoPostLimitPence`	`integer`nullable	Integer pence (GBP).

Responses

201 Created, `application/json`

Body: object (BooksBankRule).

An owner’s (or accountant’s) rule, current version. It suggests, or posts without a tap only when the owner chose that.

201 Created response for POST /api/v1/books/bank/rules
Field	Type	Description
`id`required	`string (uuid)`
`version`required	`integer`
`name`required	`string`nullable
`description`required	`string`	The rule as a sentence.
`enabled`required	`boolean`
`priority`required	`integer`
`match`required	`string (BooksBankRuleMatch)`	One of: `all`, `any`
`conditions`required	`array of BooksBankRuleCondition`
`conditions[].field`required	`string (BooksBankRuleField)`	One of: `description`, `merchant`, `counterparty`, `reference`, `amount`, `direction`, `payment_type`, `bank_account`
`conditions[].op`required	`string`	example "contains"
`conditions[].value`	`string`
`conditions[].pence`	`integer`	at least 0
`conditions[].toPence`	`integer`	Integer pence (GBP). at least 0
`categorise`required	`object (BooksBankCategorisation)`	A category (account code) and VAT code; a split gives each part’s share in basis points.
`categorise.accountCode`required	`string`
`categorise.accountName`required	`string`nullable
`categorise.vatCode`required	`string`nullable	Null or NONE: no VAT.
`categorise.split`required	`array of BooksBankSplitPart`	Empty when not split.
`categorise.split[].accountCode`required	`string`
`categorise.split[].vatCode`required	`string`nullable
`categorise.split[].shareBps`required	`integer`	1 to 9999
`postWithoutAsking`required	`boolean`
`autoPostLimitPence`required	`integer`nullable	Integer pence (GBP).
`createdBy`required	`string (BooksBankRuleAuthor)`	One of: `owner`, `accountant`
`applied`required	`integer`	Lines this rule explained (all versions).
`updatedAt`required	`string (date-time)`

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 409 Conflict, 422 Unprocessable content, 429 Too many requests, as problem details (application/problem+json).

Preview a rule

POST/api/v1/books/bank/rules/preview

Scopes: books:read

What it would catch among the lines already in the books, before saving it: “This rule would apply to 14 past lines (£512.40).” Part of the books product: the firm must have it and you must have access to it.

Request body

Required. application/json: object (BooksBankRuleInput).

The fields are as shown above.

Responses

200 OK, `application/json`

Body: object (BooksBankRulePreview).

200 OK response for POST /api/v1/books/bank/rules/preview
Field	Type	Description
`count`required	`integer`
`totalPence`required	`integer`	Integer pence (GBP).
`wouldAutoPost`required	`integer`
`differentNow`required	`integer`
`sampleLineIds`required	`array of string`
`sampleLines`	`array of BooksBankRulePreviewLine`	The sample lines themselves (up to 10, newest first), so a preview can show them.
`sampleLines[].id`required	`string (uuid)`
`sampleLines[].bookedAt`required	`string (date)`	example "2026-03-31"
`sampleLines[].description`required	`string`
`sampleLines[].payee`required	`string`nullable
`sampleLines[].amountPence`required	`integer`	Integer pence (GBP). Money in positive, money out negative.
`sampleLines[].status`required	`string (BooksBankLineStatus)`	to_explain, explained (in the books), or excluded (set aside). One of: `to_explain`, `explained`, `excluded`
`summary`required	`string`	example "This rule would apply to 14 past lines (£512.40)."
`problems`required	`array of string`	Problems with the rule, if any.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).

Change a rule

PUT/api/v1/books/bank/rules/{id}

Scopes: books:write

Saves a new version; earlier versions are kept, so each entry still names the version that posted it. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for PUT /api/v1/books/bank/rules/{id}
Name	In	Type	Description
`id`required	path	`string (uuid)`

Request body

Required. application/json: object (BooksBankRuleInput).

The fields are as shown above.

Responses

200 OK, `application/json`

Body: object (BooksBankRule).

An owner’s (or accountant’s) rule, current version. It suggests, or posts without a tap only when the owner chose that.

The fields are as shown above.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

Remove a rule

POST/api/v1/books/bank/rules/{id}/remove

Scopes: books:write

It stops applying; lines it explained stay as they are (undo them one by one if needed). Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/bank/rules/{id}/remove
Name	In	Type	Description
`id`required	path	`string (uuid)`

Responses

204 No content

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

Get the inbox

GET/api/v1/books/inbox

Scopes: books:read

Bank lines still to explain, laid out as questions (Tolvi isn’t sure: two or three answers), suggested groups (one payee, one category: one tap confirms them all) and matches; “Do this every time?” rule offers; receipts to check, reminders to approve and invoices to chase; VAT returns due; and bank or HMRC connections running out. Says whether Tolvi AI is waiting for next month’s allowance (nothing is charged) and whether the viewer can act. Part of the books product: the firm must have it and you must have access to it.

Responses

200 OK, `application/json`

Body: object (BooksInbox).

Everything that needs the owner, most of it already sorted, each with a “Why?”. Nothing in it posts until a person confirms (or the owner’s own rule does).

200 OK response for GET /api/v1/books/inbox
Field	Type	Description
`viewer`required	`object (BooksInboxViewer)`	Who is looking, and whether they can act on the inbox.
`viewer.canAct`required	`boolean`	False for an accountant whose link only lets them see the books.
`viewer.accountant`required	`boolean`	An accountant working through the practice link.
`viewer.canAutoPost`required	`boolean`	May let a rule post without asking (the business’s owners and admins, signed in).
`viewer.readOnlyReason`required	`string`nullable	Why the viewer can’t act, in plain English.
`counts`required	`object (BooksInboxCounts)`
`counts.total`required	`integer`
`counts.questions`required	`integer`
`counts.suggested`required	`integer`
`counts.matched`required	`integer`
`counts.tasks`required	`integer`
`counts.ruleOffers`required	`integer`
`ai`required	`object (BooksInboxAi)`	Tolvi AI in the inbox this month (fair use, D-83): past the allowance it waits, and nothing is charged.
`ai.state`required	`string (BooksInboxAiState)`	One of: `on`, `waiting`
`ai.allowance`required	`integer`	AI suggestions included this month.
`ai.used`required	`integer`
`ai.resetsOn`required	`string (date)`	When the allowance starts again. example "2026-03-31"
`ai.waiting`required	`integer`	Lines waiting for Tolvi AI.
`ai.message`required	`string`nullable
`questions`required	`array of BooksInboxLine`	Tolvi isn’t sure: answer in a tap.
`questions[].line`required	`object (BooksBankLine)`	A line from the bank or a statement: what happened, what Tolvi suggests and how it is in the books. Money in positive, money out negative.
`questions[].line.id`required	`string (uuid)`
`questions[].line.bankAccountId`required	`string (uuid)`
`questions[].line.source`required	`string (BooksBankLineSource)`	One of: `feed`, `csv`, `ofx`, `qif`, `manual`
`questions[].line.bookedAt`required	`string (date)`	example "2026-03-31"
`questions[].line.description`required	`string`
`questions[].line.counterparty`required	`string`nullable
`questions[].line.reference`required	`string`nullable
`questions[].line.payee`required	`string`nullable	Who it was paid to or received from, cleaned up.
`questions[].line.amountPence`required	`integer`	Integer pence (GBP).
`questions[].line.currency`required	`string`
`questions[].line.runningBalancePence`required	`integer`nullable	Integer pence (GBP).
`questions[].line.status`required	`string (BooksBankLineStatus)`	to_explain, explained (in the books), or excluded (set aside). One of: `to_explain`, `explained`, `excluded`
`questions[].line.suggestion`required	`object (BooksBankSuggestion)`nullable	What Tolvi suggests for a line and why. Only an owner’s rule set to post automatically ever posts without a tap.
`questions[].line.suggestion.level`required	`string (BooksBankSuggestionLevel)`	One of: `sorted`, `suggested`, `question`
`questions[].line.suggestion.stage`required	`string (BooksBankSuggestionStage)`	Which step decided: a possible copy, a match, your rule, what you did before, Tolvi AI, or nothing yet (for_ai). One of: `duplicate`, `matched`, `ruled`, `remembered`, `ai`, `for_ai`
`questions[].line.suggestion.summary`required	`string`
`questions[].line.suggestion.reasons`required	`array of string`	The “Why?”.
`questions[].line.suggestion.kind`required	`string (BooksBankSuggestionKind)`	One of: `category`, `transfer`, `match`, `duplicate`, `none`
`questions[].line.suggestion.categorisation`required	`object (BooksBankCategorisation)`nullable	A category (account code) and VAT code; a split gives each part’s share in basis points.
`questions[].line.suggestion.categorisation.accountCode`required	`string`
`questions[].line.suggestion.categorisation.accountName`required	`string`nullable
`questions[].line.suggestion.categorisation.vatCode`required	`string`nullable	Null or NONE: no VAT.
`questions[].line.suggestion.categorisation.split`required	`array of BooksBankSplitPart`	Empty when not split.
`questions[].line.suggestion.categorisation.split[].accountCode`required	`string`
`questions[].line.suggestion.categorisation.split[].vatCode`required	`string`nullable
`questions[].line.suggestion.categorisation.split[].shareBps`required	`integer`	1 to 9999
`questions[].line.suggestion.transferBankAccountId`required	`string (uuid)`nullable
`questions[].line.suggestion.otherLineId`required	`string (uuid)`nullable
`questions[].line.suggestion.documentKind`required	`string (BooksBankDocumentKind)`nullable	One of: `receipt`, `sales_invoice`, `sales_credit_note`, `bill`, `supplier_credit`, `vat_return`, `loan_repayment`
`questions[].line.suggestion.documentIds`required	`array of string`
`questions[].line.suggestion.duplicateOfId`required	`string (uuid)`nullable
`questions[].line.suggestion.ruleId`required	`string (uuid)`nullable
`questions[].line.suggestion.ruleName`required	`string`nullable
`questions[].line.suggestion.candidates`required	`array of BooksBankCandidate`	Other possible matches, best first.
`questions[].line.suggestion.candidates[].summary`required	`string`
`questions[].line.suggestion.candidates[].score`required	`integer`	0 to 100
`questions[].line.suggestion.candidates[].band`required	`string (BooksBankMatchBand)`	One of: `high`, `medium`, `low`
`questions[].line.suggestion.candidates[].kind`required	`string`	transfer, or the kind of document.
`questions[].line.suggestion.candidates[].documentIds`required	`array of string`
`questions[].line.suggestion.candidates[].bankAccountId`required	`string (uuid)`nullable
`questions[].line.suggestion.candidates[].otherLineId`required	`string (uuid)`nullable
`questions[].line.explanation`required	`object (BooksBankExplanation)`nullable	How the line is in the books.
`questions[].line.explanation.kind`required	`string (BooksBankExplanationKind)`	One of: `category`, `transfer`, `match`
`questions[].line.explanation.entryId`required	`string (uuid)`
`questions[].line.explanation.categorisation`required	`object (BooksBankCategorisation)`nullable	A category (account code) and VAT code; a split gives each part’s share in basis points.
`questions[].line.explanation.categorisation.accountCode`required	`string`
`questions[].line.explanation.categorisation.accountName`required	`string`nullable
`questions[].line.explanation.categorisation.vatCode`required	`string`nullable	Null or NONE: no VAT.
`questions[].line.explanation.categorisation.split`required	`array of BooksBankSplitPart`	Empty when not split.
`questions[].line.explanation.categorisation.split[].accountCode`required	`string`
`questions[].line.explanation.categorisation.split[].vatCode`required	`string`nullable
`questions[].line.explanation.categorisation.split[].shareBps`required	`integer`	1 to 9999
`questions[].line.explanation.transferLineId`required	`string (uuid)`nullable
`questions[].line.explanation.receiptId`required	`string (uuid)`nullable
`questions[].line.explanation.ruleId`required	`string (uuid)`nullable	The rule that posted it without a tap.
`questions[].line.explanation.ruleVersion`required	`integer`nullable
`questions[].line.explanation.explainedBy`required	`string (uuid)`nullable
`questions[].line.explanation.explainedAt`required	`string (date-time)`
`questions[].line.bankChange`required	`object`nullable	The bank changed or withdrew this line after Tolvi read it: { kind: corrected \| missing, changed, amountPence, description, bookedAt }.
`questions[].line.createdAt`required	`string (date-time)`
`questions[].bankAccountName`required	`string`nullable
`questions[].sourceLabel`required	`string`	“From your rule”, “You usually choose this”, “Tolvi AI suggests”, “Matched”…
`questions[].question`required	`string`nullable	For a question: what Tolvi asks, in plain English.
`questions[].choices`required	`array of BooksInboxChoice`	For a question: two or three likely answers.
`questions[].choices[].label`required	`string`
`questions[].choices[].asSuggested`required	`boolean`	Confirm as Tolvi suggested (a copy set aside, a match).
`questions[].choices[].categorisation`required	`object (BooksBankCategorisation)`nullable	A category (account code) and VAT code; a split gives each part’s share in basis points.
`questions[].choices[].categorisation.accountCode`required	`string`
`questions[].choices[].categorisation.accountName`required	`string`nullable
`questions[].choices[].categorisation.vatCode`required	`string`nullable	Null or NONE: no VAT.
`questions[].choices[].categorisation.split`required	`array of BooksBankSplitPart`	Empty when not split.
`questions[].choices[].categorisation.split[].accountCode`required	`string`
`questions[].choices[].categorisation.split[].vatCode`required	`string`nullable
`questions[].choices[].categorisation.split[].shareBps`required	`integer`	1 to 9999
`groups`required	`array of BooksInboxGroup`
`groups[].key`required	`string`
`groups[].label`required	`string`
`groups[].payee`required	`string`
`groups[].direction`required	`string (BooksInboxDirection)`	One of: `in`, `out`
`groups[].categorisation`required	`object (BooksBankCategorisation)`	A category (account code) and VAT code; a split gives each part’s share in basis points.
`groups[].categorisation.accountCode`required	`string`
`groups[].categorisation.accountName`required	`string`nullable
`groups[].categorisation.vatCode`required	`string`nullable	Null or NONE: no VAT.
`groups[].categorisation.split`required	`array of BooksBankSplitPart`	Empty when not split.
`groups[].categorisation.split[].accountCode`required	`string`
`groups[].categorisation.split[].vatCode`required	`string`nullable
`groups[].categorisation.split[].shareBps`required	`integer`	1 to 9999
`groups[].sourceLabel`required	`string`
`groups[].reasons`required	`array of string`	The “Why?” of the newest line.
`groups[].totalPence`required	`integer`	Integer pence (GBP).
`groups[].lineIds`required	`array of string`
`groups[].lines`required	`array of BooksInboxLine`
`groups[].lines[].line`required	`object (BooksBankLine)`	A line from the bank or a statement: what happened, what Tolvi suggests and how it is in the books. Money in positive, money out negative.
`groups[].lines[].line.id`required	`string (uuid)`
`groups[].lines[].line.bankAccountId`required	`string (uuid)`
`groups[].lines[].line.source`required	`string (BooksBankLineSource)`	One of: `feed`, `csv`, `ofx`, `qif`, `manual`
`groups[].lines[].line.bookedAt`required	`string (date)`	example "2026-03-31"
`groups[].lines[].line.description`required	`string`
`groups[].lines[].line.counterparty`required	`string`nullable
`groups[].lines[].line.reference`required	`string`nullable
`groups[].lines[].line.payee`required	`string`nullable	Who it was paid to or received from, cleaned up.
`groups[].lines[].line.amountPence`required	`integer`	Integer pence (GBP).
`groups[].lines[].line.currency`required	`string`
`groups[].lines[].line.runningBalancePence`required	`integer`nullable	Integer pence (GBP).
`groups[].lines[].line.status`required	`string (BooksBankLineStatus)`	to_explain, explained (in the books), or excluded (set aside). One of: `to_explain`, `explained`, `excluded`
`groups[].lines[].line.suggestion`required	`object (BooksBankSuggestion)`nullable	What Tolvi suggests for a line and why. Only an owner’s rule set to post automatically ever posts without a tap.
`groups[].lines[].line.suggestion.level`required	`string (BooksBankSuggestionLevel)`	One of: `sorted`, `suggested`, `question`
`groups[].lines[].line.suggestion.stage`required	`string (BooksBankSuggestionStage)`	Which step decided: a possible copy, a match, your rule, what you did before, Tolvi AI, or nothing yet (for_ai). One of: `duplicate`, `matched`, `ruled`, `remembered`, `ai`, `for_ai`
`groups[].lines[].line.suggestion.summary`required	`string`
`groups[].lines[].line.suggestion.reasons`required	`array of string`	The “Why?”.
`groups[].lines[].line.suggestion.kind`required	`string (BooksBankSuggestionKind)`	One of: `category`, `transfer`, `match`, `duplicate`, `none`
`groups[].lines[].line.suggestion.categorisation`required	`object (BooksBankCategorisation)`nullable	A category (account code) and VAT code; a split gives each part’s share in basis points.
`groups[].lines[].line.suggestion.categorisation.accountCode`required	`string`
`groups[].lines[].line.suggestion.categorisation.accountName`required	`string`nullable
`groups[].lines[].line.suggestion.categorisation.vatCode`required	`string`nullable	Null or NONE: no VAT.
`groups[].lines[].line.suggestion.categorisation.split`required	`array of BooksBankSplitPart`	Empty when not split.
`groups[].lines[].line.suggestion.categorisation.split[].accountCode`required	`string`
`groups[].lines[].line.suggestion.categorisation.split[].vatCode`required	`string`nullable
`groups[].lines[].line.suggestion.categorisation.split[].shareBps`required	`integer`	1 to 9999
`groups[].lines[].line.suggestion.transferBankAccountId`required	`string (uuid)`nullable
`groups[].lines[].line.suggestion.otherLineId`required	`string (uuid)`nullable
`groups[].lines[].line.suggestion.documentKind`required	`string (BooksBankDocumentKind)`nullable	One of: `receipt`, `sales_invoice`, `sales_credit_note`, `bill`, `supplier_credit`, `vat_return`, `loan_repayment`
`groups[].lines[].line.suggestion.documentIds`required	`array of string`
`groups[].lines[].line.suggestion.duplicateOfId`required	`string (uuid)`nullable
`groups[].lines[].line.suggestion.ruleId`required	`string (uuid)`nullable
`groups[].lines[].line.suggestion.ruleName`required	`string`nullable
`groups[].lines[].line.suggestion.candidates`required	`array of BooksBankCandidate`	Other possible matches, best first.
`groups[].lines[].line.suggestion.candidates[].summary`required	`string`
`groups[].lines[].line.suggestion.candidates[].score`required	`integer`	0 to 100
`groups[].lines[].line.suggestion.candidates[].band`required	`string (BooksBankMatchBand)`	One of: `high`, `medium`, `low`
`groups[].lines[].line.suggestion.candidates[].kind`required	`string`	transfer, or the kind of document.
`groups[].lines[].line.suggestion.candidates[].documentIds`required	`array of string`
`groups[].lines[].line.suggestion.candidates[].bankAccountId`required	`string (uuid)`nullable
`groups[].lines[].line.suggestion.candidates[].otherLineId`required	`string (uuid)`nullable
`groups[].lines[].line.explanation`required	`object (BooksBankExplanation)`nullable	How the line is in the books.
`groups[].lines[].line.explanation.kind`required	`string (BooksBankExplanationKind)`	One of: `category`, `transfer`, `match`
`groups[].lines[].line.explanation.entryId`required	`string (uuid)`
`groups[].lines[].line.explanation.categorisation`required	`object (BooksBankCategorisation)`nullable	A category (account code) and VAT code; a split gives each part’s share in basis points.
`groups[].lines[].line.explanation.categorisation.accountCode`required	`string`
`groups[].lines[].line.explanation.categorisation.accountName`required	`string`nullable
`groups[].lines[].line.explanation.categorisation.vatCode`required	`string`nullable	Null or NONE: no VAT.
`groups[].lines[].line.explanation.categorisation.split`required	`array of BooksBankSplitPart`	Empty when not split.
`groups[].lines[].line.explanation.categorisation.split[].accountCode`required	`string`
`groups[].lines[].line.explanation.categorisation.split[].vatCode`required	`string`nullable
`groups[].lines[].line.explanation.categorisation.split[].shareBps`required	`integer`	1 to 9999
`groups[].lines[].line.explanation.transferLineId`required	`string (uuid)`nullable
`groups[].lines[].line.explanation.receiptId`required	`string (uuid)`nullable
`groups[].lines[].line.explanation.ruleId`required	`string (uuid)`nullable	The rule that posted it without a tap.
`groups[].lines[].line.explanation.ruleVersion`required	`integer`nullable
`groups[].lines[].line.explanation.explainedBy`required	`string (uuid)`nullable
`groups[].lines[].line.explanation.explainedAt`required	`string (date-time)`
`groups[].lines[].line.bankChange`required	`object`nullable	The bank changed or withdrew this line after Tolvi read it: { kind: corrected \| missing, changed, amountPence, description, bookedAt }.
`groups[].lines[].line.createdAt`required	`string (date-time)`
`groups[].lines[].bankAccountName`required	`string`nullable
`groups[].lines[].sourceLabel`required	`string`	“From your rule”, “You usually choose this”, “Tolvi AI suggests”, “Matched”…
`groups[].lines[].question`required	`string`nullable	For a question: what Tolvi asks, in plain English.
`groups[].lines[].choices`required	`array of BooksInboxChoice`	For a question: two or three likely answers.
`groups[].lines[].choices[].label`required	`string`
`groups[].lines[].choices[].asSuggested`required	`boolean`	Confirm as Tolvi suggested (a copy set aside, a match).
`groups[].lines[].choices[].categorisation`required	`object (BooksBankCategorisation)`nullable	A category (account code) and VAT code; a split gives each part’s share in basis points.
`groups[].lines[].choices[].categorisation.accountCode`required	`string`
`groups[].lines[].choices[].categorisation.accountName`required	`string`nullable
`groups[].lines[].choices[].categorisation.vatCode`required	`string`nullable	Null or NONE: no VAT.
`groups[].lines[].choices[].categorisation.split`required	`array of BooksBankSplitPart`	Empty when not split.
`groups[].lines[].choices[].categorisation.split[].accountCode`required	`string`
`groups[].lines[].choices[].categorisation.split[].vatCode`required	`string`nullable
`groups[].lines[].choices[].categorisation.split[].shareBps`required	`integer`	1 to 9999
`suggested`required	`array of BooksInboxLine`	Suggested lines not in a group.
`suggested[].line`required	`object (BooksBankLine)`	A line from the bank or a statement: what happened, what Tolvi suggests and how it is in the books. Money in positive, money out negative.
`suggested[].line.id`required	`string (uuid)`
`suggested[].line.bankAccountId`required	`string (uuid)`
`suggested[].line.source`required	`string (BooksBankLineSource)`	One of: `feed`, `csv`, `ofx`, `qif`, `manual`
`suggested[].line.bookedAt`required	`string (date)`	example "2026-03-31"
`suggested[].line.description`required	`string`
`suggested[].line.counterparty`required	`string`nullable
`suggested[].line.reference`required	`string`nullable
`suggested[].line.payee`required	`string`nullable	Who it was paid to or received from, cleaned up.
`suggested[].line.amountPence`required	`integer`	Integer pence (GBP).
`suggested[].line.currency`required	`string`
`suggested[].line.runningBalancePence`required	`integer`nullable	Integer pence (GBP).
`suggested[].line.status`required	`string (BooksBankLineStatus)`	to_explain, explained (in the books), or excluded (set aside). One of: `to_explain`, `explained`, `excluded`
`suggested[].line.suggestion`required	`object (BooksBankSuggestion)`nullable	What Tolvi suggests for a line and why. Only an owner’s rule set to post automatically ever posts without a tap.
`suggested[].line.suggestion.level`required	`string (BooksBankSuggestionLevel)`	One of: `sorted`, `suggested`, `question`
`suggested[].line.suggestion.stage`required	`string (BooksBankSuggestionStage)`	Which step decided: a possible copy, a match, your rule, what you did before, Tolvi AI, or nothing yet (for_ai). One of: `duplicate`, `matched`, `ruled`, `remembered`, `ai`, `for_ai`
`suggested[].line.suggestion.summary`required	`string`
`suggested[].line.suggestion.reasons`required	`array of string`	The “Why?”.
`suggested[].line.suggestion.kind`required	`string (BooksBankSuggestionKind)`	One of: `category`, `transfer`, `match`, `duplicate`, `none`
`suggested[].line.suggestion.categorisation`required	`object (BooksBankCategorisation)`nullable	A category (account code) and VAT code; a split gives each part’s share in basis points.
`suggested[].line.suggestion.categorisation.accountCode`required	`string`
`suggested[].line.suggestion.categorisation.accountName`required	`string`nullable
`suggested[].line.suggestion.categorisation.vatCode`required	`string`nullable	Null or NONE: no VAT.
`suggested[].line.suggestion.categorisation.split`required	`array of BooksBankSplitPart`	Empty when not split.
`suggested[].line.suggestion.categorisation.split[].accountCode`required	`string`
`suggested[].line.suggestion.categorisation.split[].vatCode`required	`string`nullable
`suggested[].line.suggestion.categorisation.split[].shareBps`required	`integer`	1 to 9999
`suggested[].line.suggestion.transferBankAccountId`required	`string (uuid)`nullable
`suggested[].line.suggestion.otherLineId`required	`string (uuid)`nullable
`suggested[].line.suggestion.documentKind`required	`string (BooksBankDocumentKind)`nullable	One of: `receipt`, `sales_invoice`, `sales_credit_note`, `bill`, `supplier_credit`, `vat_return`, `loan_repayment`
`suggested[].line.suggestion.documentIds`required	`array of string`
`suggested[].line.suggestion.duplicateOfId`required	`string (uuid)`nullable
`suggested[].line.suggestion.ruleId`required	`string (uuid)`nullable
`suggested[].line.suggestion.ruleName`required	`string`nullable
`suggested[].line.suggestion.candidates`required	`array of BooksBankCandidate`	Other possible matches, best first.
`suggested[].line.suggestion.candidates[].summary`required	`string`
`suggested[].line.suggestion.candidates[].score`required	`integer`	0 to 100
`suggested[].line.suggestion.candidates[].band`required	`string (BooksBankMatchBand)`	One of: `high`, `medium`, `low`
`suggested[].line.suggestion.candidates[].kind`required	`string`	transfer, or the kind of document.
`suggested[].line.suggestion.candidates[].documentIds`required	`array of string`
`suggested[].line.suggestion.candidates[].bankAccountId`required	`string (uuid)`nullable
`suggested[].line.suggestion.candidates[].otherLineId`required	`string (uuid)`nullable
`suggested[].line.explanation`required	`object (BooksBankExplanation)`nullable	How the line is in the books.
`suggested[].line.explanation.kind`required	`string (BooksBankExplanationKind)`	One of: `category`, `transfer`, `match`
`suggested[].line.explanation.entryId`required	`string (uuid)`
`suggested[].line.explanation.categorisation`required	`object (BooksBankCategorisation)`nullable	A category (account code) and VAT code; a split gives each part’s share in basis points.
`suggested[].line.explanation.categorisation.accountCode`required	`string`
`suggested[].line.explanation.categorisation.accountName`required	`string`nullable
`suggested[].line.explanation.categorisation.vatCode`required	`string`nullable	Null or NONE: no VAT.
`suggested[].line.explanation.categorisation.split`required	`array of BooksBankSplitPart`	Empty when not split.
`suggested[].line.explanation.categorisation.split[].accountCode`required	`string`
`suggested[].line.explanation.categorisation.split[].vatCode`required	`string`nullable
`suggested[].line.explanation.categorisation.split[].shareBps`required	`integer`	1 to 9999
`suggested[].line.explanation.transferLineId`required	`string (uuid)`nullable
`suggested[].line.explanation.receiptId`required	`string (uuid)`nullable
`suggested[].line.explanation.ruleId`required	`string (uuid)`nullable	The rule that posted it without a tap.
`suggested[].line.explanation.ruleVersion`required	`integer`nullable
`suggested[].line.explanation.explainedBy`required	`string (uuid)`nullable
`suggested[].line.explanation.explainedAt`required	`string (date-time)`
`suggested[].line.bankChange`required	`object`nullable	The bank changed or withdrew this line after Tolvi read it: { kind: corrected \| missing, changed, amountPence, description, bookedAt }.
`suggested[].line.createdAt`required	`string (date-time)`
`suggested[].bankAccountName`required	`string`nullable
`suggested[].sourceLabel`required	`string`	“From your rule”, “You usually choose this”, “Tolvi AI suggests”, “Matched”…
`suggested[].question`required	`string`nullable	For a question: what Tolvi asks, in plain English.
`suggested[].choices`required	`array of BooksInboxChoice`	For a question: two or three likely answers.
`suggested[].choices[].label`required	`string`
`suggested[].choices[].asSuggested`required	`boolean`	Confirm as Tolvi suggested (a copy set aside, a match).
`suggested[].choices[].categorisation`required	`object (BooksBankCategorisation)`nullable	A category (account code) and VAT code; a split gives each part’s share in basis points.
`suggested[].choices[].categorisation.accountCode`required	`string`
`suggested[].choices[].categorisation.accountName`required	`string`nullable
`suggested[].choices[].categorisation.vatCode`required	`string`nullable	Null or NONE: no VAT.
`suggested[].choices[].categorisation.split`required	`array of BooksBankSplitPart`	Empty when not split.
`suggested[].choices[].categorisation.split[].accountCode`required	`string`
`suggested[].choices[].categorisation.split[].vatCode`required	`string`nullable
`suggested[].choices[].categorisation.split[].shareBps`required	`integer`	1 to 9999
`matched`required	`array of BooksInboxLine`	Paid invoices, receipts found and transfers between your accounts.
`matched[].line`required	`object (BooksBankLine)`	A line from the bank or a statement: what happened, what Tolvi suggests and how it is in the books. Money in positive, money out negative.
`matched[].line.id`required	`string (uuid)`
`matched[].line.bankAccountId`required	`string (uuid)`
`matched[].line.source`required	`string (BooksBankLineSource)`	One of: `feed`, `csv`, `ofx`, `qif`, `manual`
`matched[].line.bookedAt`required	`string (date)`	example "2026-03-31"
`matched[].line.description`required	`string`
`matched[].line.counterparty`required	`string`nullable
`matched[].line.reference`required	`string`nullable
`matched[].line.payee`required	`string`nullable	Who it was paid to or received from, cleaned up.
`matched[].line.amountPence`required	`integer`	Integer pence (GBP).
`matched[].line.currency`required	`string`
`matched[].line.runningBalancePence`required	`integer`nullable	Integer pence (GBP).
`matched[].line.status`required	`string (BooksBankLineStatus)`	to_explain, explained (in the books), or excluded (set aside). One of: `to_explain`, `explained`, `excluded`
`matched[].line.suggestion`required	`object (BooksBankSuggestion)`nullable	What Tolvi suggests for a line and why. Only an owner’s rule set to post automatically ever posts without a tap.
`matched[].line.suggestion.level`required	`string (BooksBankSuggestionLevel)`	One of: `sorted`, `suggested`, `question`
`matched[].line.suggestion.stage`required	`string (BooksBankSuggestionStage)`	Which step decided: a possible copy, a match, your rule, what you did before, Tolvi AI, or nothing yet (for_ai). One of: `duplicate`, `matched`, `ruled`, `remembered`, `ai`, `for_ai`
`matched[].line.suggestion.summary`required	`string`
`matched[].line.suggestion.reasons`required	`array of string`	The “Why?”.
`matched[].line.suggestion.kind`required	`string (BooksBankSuggestionKind)`	One of: `category`, `transfer`, `match`, `duplicate`, `none`
`matched[].line.suggestion.categorisation`required	`object (BooksBankCategorisation)`nullable	A category (account code) and VAT code; a split gives each part’s share in basis points.
`matched[].line.suggestion.categorisation.accountCode`required	`string`
`matched[].line.suggestion.categorisation.accountName`required	`string`nullable
`matched[].line.suggestion.categorisation.vatCode`required	`string`nullable	Null or NONE: no VAT.
`matched[].line.suggestion.categorisation.split`required	`array of BooksBankSplitPart`	Empty when not split.
`matched[].line.suggestion.categorisation.split[].accountCode`required	`string`
`matched[].line.suggestion.categorisation.split[].vatCode`required	`string`nullable
`matched[].line.suggestion.categorisation.split[].shareBps`required	`integer`	1 to 9999
`matched[].line.suggestion.transferBankAccountId`required	`string (uuid)`nullable
`matched[].line.suggestion.otherLineId`required	`string (uuid)`nullable
`matched[].line.suggestion.documentKind`required	`string (BooksBankDocumentKind)`nullable	One of: `receipt`, `sales_invoice`, `sales_credit_note`, `bill`, `supplier_credit`, `vat_return`, `loan_repayment`
`matched[].line.suggestion.documentIds`required	`array of string`
`matched[].line.suggestion.duplicateOfId`required	`string (uuid)`nullable
`matched[].line.suggestion.ruleId`required	`string (uuid)`nullable
`matched[].line.suggestion.ruleName`required	`string`nullable
`matched[].line.suggestion.candidates`required	`array of BooksBankCandidate`	Other possible matches, best first.
`matched[].line.suggestion.candidates[].summary`required	`string`
`matched[].line.suggestion.candidates[].score`required	`integer`	0 to 100
`matched[].line.suggestion.candidates[].band`required	`string (BooksBankMatchBand)`	One of: `high`, `medium`, `low`
`matched[].line.suggestion.candidates[].kind`required	`string`	transfer, or the kind of document.
`matched[].line.suggestion.candidates[].documentIds`required	`array of string`
`matched[].line.suggestion.candidates[].bankAccountId`required	`string (uuid)`nullable
`matched[].line.suggestion.candidates[].otherLineId`required	`string (uuid)`nullable
`matched[].line.explanation`required	`object (BooksBankExplanation)`nullable	How the line is in the books.
`matched[].line.explanation.kind`required	`string (BooksBankExplanationKind)`	One of: `category`, `transfer`, `match`
`matched[].line.explanation.entryId`required	`string (uuid)`
`matched[].line.explanation.categorisation`required	`object (BooksBankCategorisation)`nullable	A category (account code) and VAT code; a split gives each part’s share in basis points.
`matched[].line.explanation.categorisation.accountCode`required	`string`
`matched[].line.explanation.categorisation.accountName`required	`string`nullable
`matched[].line.explanation.categorisation.vatCode`required	`string`nullable	Null or NONE: no VAT.
`matched[].line.explanation.categorisation.split`required	`array of BooksBankSplitPart`	Empty when not split.
`matched[].line.explanation.categorisation.split[].accountCode`required	`string`
`matched[].line.explanation.categorisation.split[].vatCode`required	`string`nullable
`matched[].line.explanation.categorisation.split[].shareBps`required	`integer`	1 to 9999
`matched[].line.explanation.transferLineId`required	`string (uuid)`nullable
`matched[].line.explanation.receiptId`required	`string (uuid)`nullable
`matched[].line.explanation.ruleId`required	`string (uuid)`nullable	The rule that posted it without a tap.
`matched[].line.explanation.ruleVersion`required	`integer`nullable
`matched[].line.explanation.explainedBy`required	`string (uuid)`nullable
`matched[].line.explanation.explainedAt`required	`string (date-time)`
`matched[].line.bankChange`required	`object`nullable	The bank changed or withdrew this line after Tolvi read it: { kind: corrected \| missing, changed, amountPence, description, bookedAt }.
`matched[].line.createdAt`required	`string (date-time)`
`matched[].bankAccountName`required	`string`nullable
`matched[].sourceLabel`required	`string`	“From your rule”, “You usually choose this”, “Tolvi AI suggests”, “Matched”…
`matched[].question`required	`string`nullable	For a question: what Tolvi asks, in plain English.
`matched[].choices`required	`array of BooksInboxChoice`	For a question: two or three likely answers.
`matched[].choices[].label`required	`string`
`matched[].choices[].asSuggested`required	`boolean`	Confirm as Tolvi suggested (a copy set aside, a match).
`matched[].choices[].categorisation`required	`object (BooksBankCategorisation)`nullable	A category (account code) and VAT code; a split gives each part’s share in basis points.
`matched[].choices[].categorisation.accountCode`required	`string`
`matched[].choices[].categorisation.accountName`required	`string`nullable
`matched[].choices[].categorisation.vatCode`required	`string`nullable	Null or NONE: no VAT.
`matched[].choices[].categorisation.split`required	`array of BooksBankSplitPart`	Empty when not split.
`matched[].choices[].categorisation.split[].accountCode`required	`string`
`matched[].choices[].categorisation.split[].vatCode`required	`string`nullable
`matched[].choices[].categorisation.split[].shareBps`required	`integer`	1 to 9999
`ruleOffers`required	`array of BooksInboxRuleOffer`
`ruleOffers[].merchantKey`required	`string`
`ruleOffers[].merchant`required	`string`
`ruleOffers[].direction`required	`string (BooksInboxDirection)`	One of: `in`, `out`
`ruleOffers[].question`required	`string`
`ruleOffers[].reason`required	`string`
`ruleOffers[].ruleText`required	`string`	The rule in plain words.
`ruleOffers[].categorisation`required	`object (BooksBankCategorisation)`	A category (account code) and VAT code; a split gives each part’s share in basis points.
`ruleOffers[].categorisation.accountCode`required	`string`
`ruleOffers[].categorisation.accountName`required	`string`nullable
`ruleOffers[].categorisation.vatCode`required	`string`nullable	Null or NONE: no VAT.
`ruleOffers[].categorisation.split`required	`array of BooksBankSplitPart`	Empty when not split.
`ruleOffers[].categorisation.split[].accountCode`required	`string`
`ruleOffers[].categorisation.split[].vatCode`required	`string`nullable
`ruleOffers[].categorisation.split[].shareBps`required	`integer`	1 to 9999
`ruleOffers[].by`required	`string (BooksInboxDecider)`	One of: `owner`, `accountant`
`tasks`required	`array of BooksInboxTask`
`tasks[].kind`required	`string (BooksInboxTaskKind)`	One of: `receipt`, `reminder`, `invoice`, `vat`, `bank_consent`, `hmrc_consent`
`tasks[].id`required	`string`
`tasks[].title`required	`string`
`tasks[].detail`required	`string`nullable
`tasks[].amountPence`required	`integer`nullable	Integer pence (GBP).
`tasks[].date`required	`string (date)`nullable	example "2026-03-31"
`tasks[].path`required	`array of string`	Where to go, relative to the Books area (e.g. ["sales", "invoices", "<id>"]).
`tasks[].query`required	`object`nullable	Query parameters for the link.
`tasks[].ownerOnly`required	`boolean`	Only the business’s own people can do this (an accountant sees it but can’t).
`tasks[].tone`required	`string (BooksInboxTaskTone)`	One of: `info`, `warning`, `danger`
`sortedByRules`required	`object (BooksInboxSorted)`	Lines your rules posted without a tap in the last 7 days (in the activity, each with Undo).
`sortedByRules.count`required	`integer`
`sortedByRules.since`required	`string (date)`	example "2026-03-31"

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).

Confirm lines from the inbox

POST/api/v1/books/inbox/confirm

Scopes: books:write

One line, a group or a selection: each as suggested, or all as one category (an answer to a question). Each line posts on its own, so one that can’t be posted doesn’t stop the rest. The business’s own people, or an accountant whose practice link lets them change the books (year_end or full_bookkeeping), as in Bank. A read-only link sees the inbox but gets 403 here. Part of the books product: the firm must have it and you must have access to it.

Request body

Required. application/json: object (BooksBankConfirmLines).

The fields are as shown above.

Responses

200 OK, `application/json`

Body: object (BooksBankConfirmResults).

200 OK response for POST /api/v1/books/inbox/confirm
Field	Type	Description
`results`required	`array of BooksBankConfirmResult`
`results[].lineId`required	`string (uuid)`
`results[].ok`required	`boolean`
`results[].problem`required	`string`nullable	Why this line wasn’t confirmed.
`confirmed`required	`integer`

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).

Undo lines confirmed from the inbox

POST/api/v1/books/inbox/undo

Scopes: books:write

Posts the reversal of each line’s entry and puts it back in the inbox. The business’s own people, or an accountant whose practice link lets them change the books (year_end or full_bookkeeping), as in Bank. A read-only link sees the inbox but gets 403 here. Part of the books product: the firm must have it and you must have access to it.

Request body

Required. application/json: object (BooksInboxUndoLines).

Request body for POST /api/v1/books/inbox/undo
Field	Type	Description
`lineIds`required	`array of string`

Responses

200 OK, `application/json`

Body: object (BooksBankConfirmResults).

200 OK response for POST /api/v1/books/inbox/undo
Field	Type	Description
`results`required	`array of BooksBankConfirmResult`
`results[].lineId`required	`string (uuid)`
`results[].ok`required	`boolean`
`results[].problem`required	`string`nullable	Why this line wasn’t confirmed.
`confirmed`required	`integer`

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).

Why Tolvi suggested this

GET/api/v1/books/inbox/lines/{id}/why

Scopes: books:read

Where the suggestion came from (your rule, your past choices, a match or Tolvi AI, with the model and prompt version), what this business chose before for the payee, and every decision on the line with who made it. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/books/inbox/lines/{id}/why
Name	In	Type	Description
`id`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (BooksInboxWhy).

The “Why?” sheet: where a suggestion came from, what it rests on, and who has decided what on this line.

200 OK response for GET /api/v1/books/inbox/lines/{id}/why
Field	Type	Description
`item`required	`object (BooksInboxLine)`	A bank line in the inbox, with where its suggestion came from.
`item.line`required	`object (BooksBankLine)`	A line from the bank or a statement: what happened, what Tolvi suggests and how it is in the books. Money in positive, money out negative.
`item.line.id`required	`string (uuid)`
`item.line.bankAccountId`required	`string (uuid)`
`item.line.source`required	`string (BooksBankLineSource)`	One of: `feed`, `csv`, `ofx`, `qif`, `manual`
`item.line.bookedAt`required	`string (date)`	example "2026-03-31"
`item.line.description`required	`string`
`item.line.counterparty`required	`string`nullable
`item.line.reference`required	`string`nullable
`item.line.payee`required	`string`nullable	Who it was paid to or received from, cleaned up.
`item.line.amountPence`required	`integer`	Integer pence (GBP).
`item.line.currency`required	`string`
`item.line.runningBalancePence`required	`integer`nullable	Integer pence (GBP).
`item.line.status`required	`string (BooksBankLineStatus)`	to_explain, explained (in the books), or excluded (set aside). One of: `to_explain`, `explained`, `excluded`
`item.line.suggestion`required	`object (BooksBankSuggestion)`nullable	What Tolvi suggests for a line and why. Only an owner’s rule set to post automatically ever posts without a tap.
`item.line.suggestion.level`required	`string (BooksBankSuggestionLevel)`	One of: `sorted`, `suggested`, `question`
`item.line.suggestion.stage`required	`string (BooksBankSuggestionStage)`	Which step decided: a possible copy, a match, your rule, what you did before, Tolvi AI, or nothing yet (for_ai). One of: `duplicate`, `matched`, `ruled`, `remembered`, `ai`, `for_ai`
`item.line.suggestion.summary`required	`string`
`item.line.suggestion.reasons`required	`array of string`	The “Why?”.
`item.line.suggestion.kind`required	`string (BooksBankSuggestionKind)`	One of: `category`, `transfer`, `match`, `duplicate`, `none`
`item.line.suggestion.categorisation`required	`object (BooksBankCategorisation)`nullable	A category (account code) and VAT code; a split gives each part’s share in basis points.
`item.line.suggestion.categorisation.accountCode`required	`string`
`item.line.suggestion.categorisation.accountName`required	`string`nullable
`item.line.suggestion.categorisation.vatCode`required	`string`nullable	Null or NONE: no VAT.
`item.line.suggestion.categorisation.split`required	`array of BooksBankSplitPart`	Empty when not split.
`item.line.suggestion.categorisation.split[].accountCode`required	`string`
`item.line.suggestion.categorisation.split[].vatCode`required	`string`nullable
`item.line.suggestion.categorisation.split[].shareBps`required	`integer`	1 to 9999
`item.line.suggestion.transferBankAccountId`required	`string (uuid)`nullable
`item.line.suggestion.otherLineId`required	`string (uuid)`nullable
`item.line.suggestion.documentKind`required	`string (BooksBankDocumentKind)`nullable	One of: `receipt`, `sales_invoice`, `sales_credit_note`, `bill`, `supplier_credit`, `vat_return`, `loan_repayment`
`item.line.suggestion.documentIds`required	`array of string`
`item.line.suggestion.duplicateOfId`required	`string (uuid)`nullable
`item.line.suggestion.ruleId`required	`string (uuid)`nullable
`item.line.suggestion.ruleName`required	`string`nullable
`item.line.suggestion.candidates`required	`array of BooksBankCandidate`	Other possible matches, best first.
`item.line.suggestion.candidates[].summary`required	`string`
`item.line.suggestion.candidates[].score`required	`integer`	0 to 100
`item.line.suggestion.candidates[].band`required	`string (BooksBankMatchBand)`	One of: `high`, `medium`, `low`
`item.line.suggestion.candidates[].kind`required	`string`	transfer, or the kind of document.
`item.line.suggestion.candidates[].documentIds`required	`array of string`
`item.line.suggestion.candidates[].bankAccountId`required	`string (uuid)`nullable
`item.line.suggestion.candidates[].otherLineId`required	`string (uuid)`nullable
`item.line.explanation`required	`object (BooksBankExplanation)`nullable	How the line is in the books.
`item.line.explanation.kind`required	`string (BooksBankExplanationKind)`	One of: `category`, `transfer`, `match`
`item.line.explanation.entryId`required	`string (uuid)`
`item.line.explanation.categorisation`required	`object (BooksBankCategorisation)`nullable	A category (account code) and VAT code; a split gives each part’s share in basis points.
`item.line.explanation.categorisation.accountCode`required	`string`
`item.line.explanation.categorisation.accountName`required	`string`nullable
`item.line.explanation.categorisation.vatCode`required	`string`nullable	Null or NONE: no VAT.
`item.line.explanation.categorisation.split`required	`array of BooksBankSplitPart`	Empty when not split.
`item.line.explanation.categorisation.split[].accountCode`required	`string`
`item.line.explanation.categorisation.split[].vatCode`required	`string`nullable
`item.line.explanation.categorisation.split[].shareBps`required	`integer`	1 to 9999
`item.line.explanation.transferLineId`required	`string (uuid)`nullable
`item.line.explanation.receiptId`required	`string (uuid)`nullable
`item.line.explanation.ruleId`required	`string (uuid)`nullable	The rule that posted it without a tap.
`item.line.explanation.ruleVersion`required	`integer`nullable
`item.line.explanation.explainedBy`required	`string (uuid)`nullable
`item.line.explanation.explainedAt`required	`string (date-time)`
`item.line.bankChange`required	`object`nullable	The bank changed or withdrew this line after Tolvi read it: { kind: corrected \| missing, changed, amountPence, description, bookedAt }.
`item.line.createdAt`required	`string (date-time)`
`item.bankAccountName`required	`string`nullable
`item.sourceLabel`required	`string`	“From your rule”, “You usually choose this”, “Tolvi AI suggests”, “Matched”…
`item.question`required	`string`nullable	For a question: what Tolvi asks, in plain English.
`item.choices`required	`array of BooksInboxChoice`	For a question: two or three likely answers.
`item.choices[].label`required	`string`
`item.choices[].asSuggested`required	`boolean`	Confirm as Tolvi suggested (a copy set aside, a match).
`item.choices[].categorisation`required	`object (BooksBankCategorisation)`nullable	A category (account code) and VAT code; a split gives each part’s share in basis points.
`item.choices[].categorisation.accountCode`required	`string`
`item.choices[].categorisation.accountName`required	`string`nullable
`item.choices[].categorisation.vatCode`required	`string`nullable	Null or NONE: no VAT.
`item.choices[].categorisation.split`required	`array of BooksBankSplitPart`	Empty when not split.
`item.choices[].categorisation.split[].accountCode`required	`string`
`item.choices[].categorisation.split[].vatCode`required	`string`nullable
`item.choices[].categorisation.split[].shareBps`required	`integer`	1 to 9999
`ai`required	`object (BooksInboxAiDetail)`nullable	Tolvi AI’s part in a suggestion.
`ai.suggestionId`required	`string (uuid)`
`ai.model`required	`string`
`ai.promptVersion`required	`string`
`ai.confidence`required	`string (BooksInboxConfidence)`	One of: `high`, `medium`, `low`
`ai.status`required	`string (BooksInboxAiStatus)`	One of: `proposed`, `accepted`, `discarded`
`ai.at`required	`string (date-time)`
`memory`required	`array of BooksInboxMemory`	Most chosen first.
`memory[].label`required	`string`
`memory[].times`required	`integer`
`history`required	`array of BooksInboxActivityItem`	Every decision on this line, newest first.
`history[].id`required	`string (uuid)`
`history[].lineId`required	`string (uuid)`
`history[].at`required	`string (date-time)`
`history[].action`required	`string (BooksInboxActivityAction)`	One of: `confirmed`, `changed`, `answered`, `set_aside`, `posted_by_rule`, `undone`
`history[].by`required	`object (BooksInboxPerson)`	Who decided: a person at the business, an accountant (with their firm) or a rule.
`history[].by.kind`required	`string (BooksInboxDeciderKind)`	One of: `owner`, `accountant`, `rule`
`history[].by.name`required	`string`
`history[].by.firmName`required	`string`nullable
`history[].payee`required	`string`nullable
`history[].amountPence`required	`integer`	Integer pence (GBP).
`history[].what`required	`string`nullable	What it went in as.
`history[].undoable`required	`boolean`	Still stands and can be undone.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

Who confirmed what

GET/api/v1/books/inbox/activity

Scopes: books:read

The latest decisions on bank lines, newest first: confirmed, changed, answered, set aside, posted by a rule or undone, by whom (an accountant with their firm), and whether each can still be undone. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/books/inbox/activity
Name	In	Type	Description
`limit`	query	`integer`	1 to 200; default 50

Responses

200 OK, `application/json`

Body: object (BooksInboxActivity).

200 OK response for GET /api/v1/books/inbox/activity
Field	Type	Description
`items`required	`array of BooksInboxActivityItem`
`items[].id`required	`string (uuid)`
`items[].lineId`required	`string (uuid)`
`items[].at`required	`string (date-time)`
`items[].action`required	`string (BooksInboxActivityAction)`	One of: `confirmed`, `changed`, `answered`, `set_aside`, `posted_by_rule`, `undone`
`items[].by`required	`object (BooksInboxPerson)`	Who decided: a person at the business, an accountant (with their firm) or a rule.
`items[].by.kind`required	`string (BooksInboxDeciderKind)`	One of: `owner`, `accountant`, `rule`
`items[].by.name`required	`string`
`items[].by.firmName`required	`string`nullable
`items[].payee`required	`string`nullable
`items[].amountPence`required	`integer`	Integer pence (GBP).
`items[].what`required	`string`nullable	What it went in as.
`items[].undoable`required	`boolean`	Still stands and can be undone.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).

Accept a rule offer (“Yes, always”)

POST/api/v1/books/inbox/rule-offers/accept

Scopes: books:write

Saves the offered rule for the payee, so its lines are suggested that way from now on. It only suggests unless postWithoutAsking is set, which the business’s owners and admins can do signed in (403 otherwise). 404 when the offer no longer applies. The business’s own people, or an accountant whose practice link lets them change the books (year_end or full_bookkeeping), as in Bank. A read-only link sees the inbox but gets 403 here. Part of the books product: the firm must have it and you must have access to it.

Request body

Required. application/json: object (BooksInboxAcceptRuleOffer).

Request body for POST /api/v1/books/inbox/rule-offers/accept
Field	Type	Description
`merchantKey`required	`string`
`direction`required	`string (BooksInboxDirection)`	One of: `in`, `out`
`postWithoutAsking`	`boolean`	Post matching lines without a tap. The business’s owners and admins only, signed in.

Responses

201 Created, `application/json`

Body: object (BooksInboxRuleCreated).

201 Created response for POST /api/v1/books/inbox/rule-offers/accept
Field	Type	Description
`ruleId`required	`string (uuid)`
`description`required	`string`
`postWithoutAsking`required	`boolean`

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).

Decline a rule offer

POST/api/v1/books/inbox/rule-offers/decline

Scopes: books:write

“Not now” asks again after the next correction; “Ask me each time” stops offering for that payee. The business’s own people, or an accountant whose practice link lets them change the books (year_end or full_bookkeeping), as in Bank. A read-only link sees the inbox but gets 403 here. Part of the books product: the firm must have it and you must have access to it.

Request body

Required. application/json: object (BooksInboxDeclineRuleOffer).

Request body for POST /api/v1/books/inbox/rule-offers/decline
Field	Type	Description
`merchantKey`required	`string`
`direction`required	`string (BooksInboxDirection)`	One of: `in`, `out`
`answer`required	`string (BooksInboxDeclineAnswer)`	One of: `not_now`, `ask_each_time`

Responses

204 No content

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).

Books: bank and inbox

Can a bank be connected?

Responses

200 OK, application/json

List bank accounts

Responses

200 OK, application/json

Add a bank account kept by statements

Parameters

Request body

Responses

201 Created, application/json

Get a bank account

Parameters

Responses

200 OK, application/json

Rename a bank account or record its statement balance

Parameters

Request body

Responses

200 OK, application/json

Reconcile a bank account

Parameters

Responses

200 OK, application/json

Preview a statement file

Parameters

Request body

Responses

200 OK, application/json

Import a statement file

Parameters

Request body

Responses

201 Created, application/json

Connect a bank

Request body

Responses

201 Created, application/json

Finish connecting a bank

Request body

Responses

200 OK, application/json

The accounts a bank shared

Parameters

Responses

200 OK, application/json

Add accounts from a connected bank

Parameters

Request body

Responses

200 OK, application/json

Keep sharing for another 90 days

Parameters

Request body

Responses

200 OK, application/json

Disconnect a bank

Parameters

Responses

200 OK, application/json

Read the bank now

Parameters

Responses

200 OK, application/json

List bank lines

Parameters

Responses

200 OK, application/json

Confirm a group of lines

Request body

Responses

200 OK, application/json

Get a bank line

Parameters

Responses

200 OK, application/json

Explain a bank line

Parameters

Request body

200 OK, `application/json`

200 OK, `application/json`

201 Created, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

201 Created, `application/json`

201 Created, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

201 Created, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

201 Created, `application/json`