Books: purchases and receipts

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

List receipts

GET/api/v1/books/receipts

Scopes: books:read

Newest first. Filter by the person’s decision: to_review, confirmed, discarded or all. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/books/receipts
Name	In	Type	Description
`limit`	query	`integer`	1 to 200; default 100
`review`	query	`string`	One of: `to_review`, `confirmed`, `discarded`, `all`

Responses

200 OK, `application/json`

Body: object (ReceiptList).

200 OK response for GET /api/v1/books/receipts
Field	Type	Description
`items`required	`array of Receipt`
`items[].id`required	`string (uuid)`
`items[].source`required	`string (ReceiptSource)`	One of: `camera`, `upload`, `email`
`items[].fileName`required	`string`
`items[].contentType`required	`string`
`items[].sizeBytes`required	`integer`
`items[].status`required	`string (ReceiptFileStatus)`	pending_upload, pending_scan (being checked for viruses), available, or rejected (with the reason). One of: `pending_upload`, `pending_scan`, `available`, `rejected`
`items[].rejectedReason`required	`string`nullable
`items[].readingStatus`required	`string (ReceiptReadingStatus)`	waiting (until the virus check passes), queued, reading, done or failed. One of: `waiting`, `queued`, `reading`, `done`, `failed`
`items[].readingError`required	`string`nullable	Why reading failed, in plain English.
`items[].reading`required	`object (ReceiptReading)`nullable	What Tolvi AI read from the receipt: a suggestion for the person to confirm or correct. Money in integer pence.
`items[].reading.documentType`required	`string (ReceiptDocumentType)`	One of: `till_receipt`, `simplified_vat_invoice`, `vat_invoice`, `order_confirmation`, `statement`, `not_a_receipt`, `other`
`items[].reading.supplierName`required	`string`nullable
`items[].reading.supplierVatNumber`required	`string`nullable	As printed on the receipt.
`items[].reading.documentNumber`required	`string`nullable
`items[].reading.date`required	`string (date)`nullable	example "2026-03-31"
`items[].reading.currency`required	`string`nullable	example "GBP"
`items[].reading.totalPence`required	`integer`nullable	Integer pence (GBP).
`items[].reading.netPence`required	`integer`nullable	Integer pence (GBP).
`items[].reading.vatPence`required	`integer`nullable	Integer pence (GBP).
`items[].reading.vatBreakdown`required	`array of ReceiptVatRow`
`items[].reading.vatBreakdown[].rateBps`required	`integer`	VAT rate in basis points (2000 = 20%).
`items[].reading.vatBreakdown[].netPence`required	`integer`nullable	Integer pence (GBP).
`items[].reading.vatBreakdown[].vatPence`required	`integer`	Integer pence (GBP).
`items[].reading.lineItems`required	`array of ReceiptLineItem`
`items[].reading.lineItems[].description`required	`string`
`items[].reading.lineItems[].quantity`required	`string`nullable
`items[].reading.lineItems[].amountPence`required	`integer`	Integer pence (GBP).
`items[].reading.lineItems[].vatRateBps`required	`integer`nullable
`items[].reading.lineItems[].vatPence`	`integer`nullable	Integer pence (GBP). The VAT shown on this line. Absent on a reading from before lines were captured.
`items[].reading.lineItems[].accountCode`	`string`nullable	The category Tolvi AI suggests, from the chart of accounts.
`items[].reading.lineItems[].confidence`	`integer`	How sure Tolvi AI is of this line, from 0 to 100. 0 to 100
`items[].reading.lineItems[].reason`	`string`nullable	Why it is unsure, when it is; otherwise empty.
`items[].reading.moreLines`	`boolean`	The document has more lines than Tolvi AI kept.
`items[].reading.paymentMethod`required	`string (ReceiptPaymentMethod)`	One of: `card`, `cash`, `bank_transfer`, `direct_debit`, `other`, `unknown`
`items[].reading.cardLast4`required	`string`nullable	The last four digits of the card only.
`items[].reading.fields`required	`object (ReceiptFieldNotes)`
`items[].reading.fields.supplierName`required	`object (ReceiptFieldNote)`	How sure Tolvi AI is of one field, and why.
`items[].reading.fields.supplierName.confidence`required	`string (ReceiptConfidence)`	One of: `high`, `medium`, `low`
`items[].reading.fields.supplierName.reason`required	`string`
`items[].reading.fields.supplierName.alternative`required	`string`nullable	Another reading worth checking, e.g. "£36.20".
`items[].reading.fields.date`required	`object (ReceiptFieldNote)`	How sure Tolvi AI is of one field, and why.
`items[].reading.fields.date.confidence`required	`string (ReceiptConfidence)`	One of: `high`, `medium`, `low`
`items[].reading.fields.date.reason`required	`string`
`items[].reading.fields.date.alternative`required	`string`nullable	Another reading worth checking, e.g. "£36.20".
`items[].reading.fields.total`required	`object (ReceiptFieldNote)`	How sure Tolvi AI is of one field, and why.
`items[].reading.fields.total.confidence`required	`string (ReceiptConfidence)`	One of: `high`, `medium`, `low`
`items[].reading.fields.total.reason`required	`string`
`items[].reading.fields.total.alternative`required	`string`nullable	Another reading worth checking, e.g. "£36.20".
`items[].reading.fields.vat`required	`object (ReceiptFieldNote)`	How sure Tolvi AI is of one field, and why.
`items[].reading.fields.vat.confidence`required	`string (ReceiptConfidence)`	One of: `high`, `medium`, `low`
`items[].reading.fields.vat.reason`required	`string`
`items[].reading.fields.vat.alternative`required	`string`nullable	Another reading worth checking, e.g. "£36.20".
`items[].reading.fields.vatNumber`required	`object (ReceiptFieldNote)`	How sure Tolvi AI is of one field, and why.
`items[].reading.fields.vatNumber.confidence`required	`string (ReceiptConfidence)`	One of: `high`, `medium`, `low`
`items[].reading.fields.vatNumber.reason`required	`string`
`items[].reading.fields.vatNumber.alternative`required	`string`nullable	Another reading worth checking, e.g. "£36.20".
`items[].reading.notes`required	`string`
`items[].reading.model`required	`string`	The model that read it.
`items[].reading.promptVersion`required	`string`	example "extract_receipt@1"
`items[].reading.readAt`required	`string (date-time)`
`items[].suggestedLines`required	`array of ReceiptSuggestedLine`
`items[].suggestedLines[].description`required	`string`
`items[].suggestedLines[].accountCode`required	`string`nullable	The suggested category, from the chart of accounts.
`items[].suggestedLines[].grossPence`required	`integer`	Integer pence (GBP). What the line cost, including any VAT.
`items[].suggestedLines[].vatPence`required	`integer`	Integer pence (GBP). The VAT in that cost.
`items[].suggestedLines[].vatCode`required	`string (VatCode)`	One of: `S20`, `R5`, `Z0`, `EX`, `OS`, `RC_SERV`, `DRC_SALE`, `DRC_SALE_R5`, `DRC_PURCH`, `RC_GOODS_SALE`, `RC_GOODS_PURCH`, `PIVA`, `IMPORT_C79`, `BLOCKED`
`items[].suggestedLines[].checkThis`required	`boolean`	Tolvi AI was barely sure of this line: highlight it for the person to check. It never stops them.
`items[].suggestedLines[].checkReason`required	`string`nullable
`items[].checks`required	`object (ReceiptChecks)`nullable
`items[].checks.of`required	`string (ReceiptChecksOf)`	Whether these checks are on what Tolvi AI read or on what the person confirmed. One of: `reading`, `confirmed`
`items[].checks.problems`required	`array of ReceiptProblem`
`items[].checks.problems[].code`required	`string`	example "no_vat_number"
`items[].checks.problems[].severity`required	`string (ReceiptProblemSeverity)`	One of: `warning`, `info`
`items[].checks.problems[].field`required	`string`nullable	example "vatNumber"
`items[].checks.problems[].message`required	`string`
`items[].checks.problems[].source`required	`string`nullable	The rule behind it.
`items[].checks.vatClaimable`required	`boolean`	Whether the VAT on it can be reclaimed: the business is VAT registered and the receipt shows VAT and a valid UK VAT number.
`items[].checks.suggestedVatCode`required	`string (VatCode)`nullable	One of: `S20`, `R5`, `Z0`, `EX`, `OS`, `RC_SERV`, `DRC_SALE`, `DRC_SALE_R5`, `DRC_PURCH`, `RC_GOODS_SALE`, `RC_GOODS_PURCH`, `PIVA`, `IMPORT_C79`, `BLOCKED`
`items[].checks.vatNumber`required	`string`nullable	The VAT number without GB, when it passes the check digits.
`items[].duplicateOfId`required	`string (uuid)`nullable	An earlier receipt this looks like a copy of.
`items[].matches`required	`array of ReceiptMatch`
`items[].matches[].bankLineId`required	`string (uuid)`
`items[].matches[].bankAccountId`required	`string (uuid)`
`items[].matches[].bookedAt`required	`string (date)`	example "2026-03-31"
`items[].matches[].amountPence`required	`integer`	Integer pence (GBP). As on the bank line: money out is negative.
`items[].matches[].description`required	`string`
`items[].matches[].score`required	`integer`	0 to 100
`items[].matches[].band`required	`string (ReceiptMatchBand)`	One of: `high`, `medium`, `low`
`items[].matches[].summary`required	`string`
`items[].matches[].reasons`required	`array of string`
`items[].reviewStatus`required	`string (ReceiptReviewStatus)`	One of: `to_review`, `confirmed`, `discarded`
`items[].confirmed`required	`object (ReceiptConfirmed)`nullable	What the person confirmed. Money in integer pence.
`items[].confirmed.supplierName`required	`string`
`items[].confirmed.supplierVatNumber`required	`string`nullable
`items[].confirmed.date`required	`string (date)`	example "2026-03-31"
`items[].confirmed.currency`required	`string`	example "GBP"
`items[].confirmed.totalPence`required	`integer`	Integer pence (GBP).
`items[].confirmed.netPence`required	`integer`nullable	Integer pence (GBP).
`items[].confirmed.vatPence`required	`integer`nullable	Integer pence (GBP).
`items[].confirmed.vatCode`required	`string (VatCode)`nullable	One of: `S20`, `R5`, `Z0`, `EX`, `OS`, `RC_SERV`, `DRC_SALE`, `DRC_SALE_R5`, `DRC_PURCH`, `RC_GOODS_SALE`, `RC_GOODS_PURCH`, `PIVA`, `IMPORT_C79`, `BLOCKED`
`items[].confirmed.accountCode`required	`string`nullable
`items[].confirmed.paymentMethod`required	`string (ReceiptPaymentMethod)`nullable	One of: `card`, `cash`, `bank_transfer`, `direct_debit`, `other`, `unknown`
`items[].confirmed.cardLast4`required	`string`nullable
`items[].confirmed.paidPersonally`required	`boolean`
`items[].confirmed.bankLineId`required	`string (uuid)`nullable
`items[].confirmed.note`required	`string`nullable
`items[].confirmed.correctedFields`required	`array of string`	Fields the person changed from what Tolvi AI read; line1.category is the first line’s category.
`items[].confirmed.lines`required	`array of ReceiptConfirmedLine`	The lines it went into the books as. Empty when it was confirmed as one amount.
`items[].confirmed.lines[].description`required	`string`
`items[].confirmed.lines[].accountCode`required	`string`nullable
`items[].confirmed.lines[].grossPence`required	`integer`	Integer pence (GBP). What the line cost, including any VAT.
`items[].confirmed.lines[].vatPence`required	`integer`	Integer pence (GBP).
`items[].confirmed.confirmedBy`required	`string (uuid)`nullable
`items[].confirmed.confirmedAt`required	`string (date-time)`
`items[].postingStatus`required	`string (ReceiptPostingStatus)`	none, proposed (confirmed; waiting for the books), or posted. One of: `none`, `proposed`, `posted`
`items[].postingProposal`required	`object`nullable	What confirming proposes for the books (version 1, or version 2 with lines).
`items[].ledgerEntryId`required	`string (uuid)`nullable
`items[].emailFrom`required	`string`nullable	For an emailed receipt: who sent it.
`items[].emailSubject`required	`string`nullable
`items[].previewable`required	`boolean`	Whether a browser can show the image (a HEIC photo has a JPEG preview once read).
`items[].uploadedBy`required	`string (uuid)`nullable
`items[].capturedAt`required	`string (date-time)`nullable
`items[].createdAt`required	`string (date-time)`
`items[].updatedAt`required	`string (date-time)`
`toReview`required	`integer`	Receipts waiting for the person to check.

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

Add a receipt

POST/api/v1/books/receipts

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

Records a photo or file of a receipt (JPEG, PNG, WebP, HEIC or PDF, up to 20 MB) and returns a short-lived presigned URL to PUT it to storage with exactly the headers given; then call upload-complete. Send the app’s own clientReference for a capture so sending it again (an offline retry) returns the same receipt. Needs a person, not an API client. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/receipts
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 (CreateReceipt).

Request body for POST /api/v1/books/receipts
Field	Type	Description
`fileName`required	`string`	up to 200 characters; example "IMG_2041.HEIC"
`contentType`	`string`	The type the browser reports; the file name’s extension decides. example "image/heic"
`sizeBytes`required	`integer`	1 to 20971520
`source`	`string (ReceiptCaptureSource)`	One of: `camera`, `upload`
`clientReference`	`string (uuid)`	The app’s own id for this capture: sending it again returns the same receipt (offline retries).
`capturedAt`	`string (date-time)`

Responses

201 Created, `application/json`

Body: object (ReceiptUpload).

201 Created response for POST /api/v1/books/receipts
Field	Type	Description
`receipt`required	`object (Receipt)`	A receipt or bill: the file (kept as the record), what Tolvi AI read from it, and what the person confirmed.
`receipt.id`required	`string (uuid)`
`receipt.source`required	`string (ReceiptSource)`	One of: `camera`, `upload`, `email`
`receipt.fileName`required	`string`
`receipt.contentType`required	`string`
`receipt.sizeBytes`required	`integer`
`receipt.status`required	`string (ReceiptFileStatus)`	pending_upload, pending_scan (being checked for viruses), available, or rejected (with the reason). One of: `pending_upload`, `pending_scan`, `available`, `rejected`
`receipt.rejectedReason`required	`string`nullable
`receipt.readingStatus`required	`string (ReceiptReadingStatus)`	waiting (until the virus check passes), queued, reading, done or failed. One of: `waiting`, `queued`, `reading`, `done`, `failed`
`receipt.readingError`required	`string`nullable	Why reading failed, in plain English.
`receipt.reading`required	`object (ReceiptReading)`nullable	What Tolvi AI read from the receipt: a suggestion for the person to confirm or correct. Money in integer pence.
`receipt.reading.documentType`required	`string (ReceiptDocumentType)`	One of: `till_receipt`, `simplified_vat_invoice`, `vat_invoice`, `order_confirmation`, `statement`, `not_a_receipt`, `other`
`receipt.reading.supplierName`required	`string`nullable
`receipt.reading.supplierVatNumber`required	`string`nullable	As printed on the receipt.
`receipt.reading.documentNumber`required	`string`nullable
`receipt.reading.date`required	`string (date)`nullable	example "2026-03-31"
`receipt.reading.currency`required	`string`nullable	example "GBP"
`receipt.reading.totalPence`required	`integer`nullable	Integer pence (GBP).
`receipt.reading.netPence`required	`integer`nullable	Integer pence (GBP).
`receipt.reading.vatPence`required	`integer`nullable	Integer pence (GBP).
`receipt.reading.vatBreakdown`required	`array of ReceiptVatRow`
`receipt.reading.vatBreakdown[].rateBps`required	`integer`	VAT rate in basis points (2000 = 20%).
`receipt.reading.vatBreakdown[].netPence`required	`integer`nullable	Integer pence (GBP).
`receipt.reading.vatBreakdown[].vatPence`required	`integer`	Integer pence (GBP).
`receipt.reading.lineItems`required	`array of ReceiptLineItem`
`receipt.reading.lineItems[].description`required	`string`
`receipt.reading.lineItems[].quantity`required	`string`nullable
`receipt.reading.lineItems[].amountPence`required	`integer`	Integer pence (GBP).
`receipt.reading.lineItems[].vatRateBps`required	`integer`nullable
`receipt.reading.lineItems[].vatPence`	`integer`nullable	Integer pence (GBP). The VAT shown on this line. Absent on a reading from before lines were captured.
`receipt.reading.lineItems[].accountCode`	`string`nullable	The category Tolvi AI suggests, from the chart of accounts.
`receipt.reading.lineItems[].confidence`	`integer`	How sure Tolvi AI is of this line, from 0 to 100. 0 to 100
`receipt.reading.lineItems[].reason`	`string`nullable	Why it is unsure, when it is; otherwise empty.
`receipt.reading.moreLines`	`boolean`	The document has more lines than Tolvi AI kept.
`receipt.reading.paymentMethod`required	`string (ReceiptPaymentMethod)`	One of: `card`, `cash`, `bank_transfer`, `direct_debit`, `other`, `unknown`
`receipt.reading.cardLast4`required	`string`nullable	The last four digits of the card only.
`receipt.reading.fields`required	`object (ReceiptFieldNotes)`
`receipt.reading.fields.supplierName`required	`object (ReceiptFieldNote)`	How sure Tolvi AI is of one field, and why.
`receipt.reading.fields.supplierName.confidence`required	`string (ReceiptConfidence)`	One of: `high`, `medium`, `low`
`receipt.reading.fields.supplierName.reason`required	`string`
`receipt.reading.fields.supplierName.alternative`required	`string`nullable	Another reading worth checking, e.g. "£36.20".
`receipt.reading.fields.date`required	`object (ReceiptFieldNote)`	How sure Tolvi AI is of one field, and why.
`receipt.reading.fields.date.confidence`required	`string (ReceiptConfidence)`	One of: `high`, `medium`, `low`
`receipt.reading.fields.date.reason`required	`string`
`receipt.reading.fields.date.alternative`required	`string`nullable	Another reading worth checking, e.g. "£36.20".
`receipt.reading.fields.total`required	`object (ReceiptFieldNote)`	How sure Tolvi AI is of one field, and why.
`receipt.reading.fields.total.confidence`required	`string (ReceiptConfidence)`	One of: `high`, `medium`, `low`
`receipt.reading.fields.total.reason`required	`string`
`receipt.reading.fields.total.alternative`required	`string`nullable	Another reading worth checking, e.g. "£36.20".
`receipt.reading.fields.vat`required	`object (ReceiptFieldNote)`	How sure Tolvi AI is of one field, and why.
`receipt.reading.fields.vat.confidence`required	`string (ReceiptConfidence)`	One of: `high`, `medium`, `low`
`receipt.reading.fields.vat.reason`required	`string`
`receipt.reading.fields.vat.alternative`required	`string`nullable	Another reading worth checking, e.g. "£36.20".
`receipt.reading.fields.vatNumber`required	`object (ReceiptFieldNote)`	How sure Tolvi AI is of one field, and why.
`receipt.reading.fields.vatNumber.confidence`required	`string (ReceiptConfidence)`	One of: `high`, `medium`, `low`
`receipt.reading.fields.vatNumber.reason`required	`string`
`receipt.reading.fields.vatNumber.alternative`required	`string`nullable	Another reading worth checking, e.g. "£36.20".
`receipt.reading.notes`required	`string`
`receipt.reading.model`required	`string`	The model that read it.
`receipt.reading.promptVersion`required	`string`	example "extract_receipt@1"
`receipt.reading.readAt`required	`string (date-time)`
`receipt.suggestedLines`required	`array of ReceiptSuggestedLine`
`receipt.suggestedLines[].description`required	`string`
`receipt.suggestedLines[].accountCode`required	`string`nullable	The suggested category, from the chart of accounts.
`receipt.suggestedLines[].grossPence`required	`integer`	Integer pence (GBP). What the line cost, including any VAT.
`receipt.suggestedLines[].vatPence`required	`integer`	Integer pence (GBP). The VAT in that cost.
`receipt.suggestedLines[].vatCode`required	`string (VatCode)`	One of: `S20`, `R5`, `Z0`, `EX`, `OS`, `RC_SERV`, `DRC_SALE`, `DRC_SALE_R5`, `DRC_PURCH`, `RC_GOODS_SALE`, `RC_GOODS_PURCH`, `PIVA`, `IMPORT_C79`, `BLOCKED`
`receipt.suggestedLines[].checkThis`required	`boolean`	Tolvi AI was barely sure of this line: highlight it for the person to check. It never stops them.
`receipt.suggestedLines[].checkReason`required	`string`nullable
`receipt.checks`required	`object (ReceiptChecks)`nullable
`receipt.checks.of`required	`string (ReceiptChecksOf)`	Whether these checks are on what Tolvi AI read or on what the person confirmed. One of: `reading`, `confirmed`
`receipt.checks.problems`required	`array of ReceiptProblem`
`receipt.checks.problems[].code`required	`string`	example "no_vat_number"
`receipt.checks.problems[].severity`required	`string (ReceiptProblemSeverity)`	One of: `warning`, `info`
`receipt.checks.problems[].field`required	`string`nullable	example "vatNumber"
`receipt.checks.problems[].message`required	`string`
`receipt.checks.problems[].source`required	`string`nullable	The rule behind it.
`receipt.checks.vatClaimable`required	`boolean`	Whether the VAT on it can be reclaimed: the business is VAT registered and the receipt shows VAT and a valid UK VAT number.
`receipt.checks.suggestedVatCode`required	`string (VatCode)`nullable	One of: `S20`, `R5`, `Z0`, `EX`, `OS`, `RC_SERV`, `DRC_SALE`, `DRC_SALE_R5`, `DRC_PURCH`, `RC_GOODS_SALE`, `RC_GOODS_PURCH`, `PIVA`, `IMPORT_C79`, `BLOCKED`
`receipt.checks.vatNumber`required	`string`nullable	The VAT number without GB, when it passes the check digits.
`receipt.duplicateOfId`required	`string (uuid)`nullable	An earlier receipt this looks like a copy of.
`receipt.matches`required	`array of ReceiptMatch`
`receipt.matches[].bankLineId`required	`string (uuid)`
`receipt.matches[].bankAccountId`required	`string (uuid)`
`receipt.matches[].bookedAt`required	`string (date)`	example "2026-03-31"
`receipt.matches[].amountPence`required	`integer`	Integer pence (GBP). As on the bank line: money out is negative.
`receipt.matches[].description`required	`string`
`receipt.matches[].score`required	`integer`	0 to 100
`receipt.matches[].band`required	`string (ReceiptMatchBand)`	One of: `high`, `medium`, `low`
`receipt.matches[].summary`required	`string`
`receipt.matches[].reasons`required	`array of string`
`receipt.reviewStatus`required	`string (ReceiptReviewStatus)`	One of: `to_review`, `confirmed`, `discarded`
`receipt.confirmed`required	`object (ReceiptConfirmed)`nullable	What the person confirmed. Money in integer pence.
`receipt.confirmed.supplierName`required	`string`
`receipt.confirmed.supplierVatNumber`required	`string`nullable
`receipt.confirmed.date`required	`string (date)`	example "2026-03-31"
`receipt.confirmed.currency`required	`string`	example "GBP"
`receipt.confirmed.totalPence`required	`integer`	Integer pence (GBP).
`receipt.confirmed.netPence`required	`integer`nullable	Integer pence (GBP).
`receipt.confirmed.vatPence`required	`integer`nullable	Integer pence (GBP).
`receipt.confirmed.vatCode`required	`string (VatCode)`nullable	One of: `S20`, `R5`, `Z0`, `EX`, `OS`, `RC_SERV`, `DRC_SALE`, `DRC_SALE_R5`, `DRC_PURCH`, `RC_GOODS_SALE`, `RC_GOODS_PURCH`, `PIVA`, `IMPORT_C79`, `BLOCKED`
`receipt.confirmed.accountCode`required	`string`nullable
`receipt.confirmed.paymentMethod`required	`string (ReceiptPaymentMethod)`nullable	One of: `card`, `cash`, `bank_transfer`, `direct_debit`, `other`, `unknown`
`receipt.confirmed.cardLast4`required	`string`nullable
`receipt.confirmed.paidPersonally`required	`boolean`
`receipt.confirmed.bankLineId`required	`string (uuid)`nullable
`receipt.confirmed.note`required	`string`nullable
`receipt.confirmed.correctedFields`required	`array of string`	Fields the person changed from what Tolvi AI read; line1.category is the first line’s category.
`receipt.confirmed.lines`required	`array of ReceiptConfirmedLine`	The lines it went into the books as. Empty when it was confirmed as one amount.
`receipt.confirmed.lines[].description`required	`string`
`receipt.confirmed.lines[].accountCode`required	`string`nullable
`receipt.confirmed.lines[].grossPence`required	`integer`	Integer pence (GBP). What the line cost, including any VAT.
`receipt.confirmed.lines[].vatPence`required	`integer`	Integer pence (GBP).
`receipt.confirmed.confirmedBy`required	`string (uuid)`nullable
`receipt.confirmed.confirmedAt`required	`string (date-time)`
`receipt.postingStatus`required	`string (ReceiptPostingStatus)`	none, proposed (confirmed; waiting for the books), or posted. One of: `none`, `proposed`, `posted`
`receipt.postingProposal`required	`object`nullable	What confirming proposes for the books (version 1, or version 2 with lines).
`receipt.ledgerEntryId`required	`string (uuid)`nullable
`receipt.emailFrom`required	`string`nullable	For an emailed receipt: who sent it.
`receipt.emailSubject`required	`string`nullable
`receipt.previewable`required	`boolean`	Whether a browser can show the image (a HEIC photo has a JPEG preview once read).
`receipt.uploadedBy`required	`string (uuid)`nullable
`receipt.capturedAt`required	`string (date-time)`nullable
`receipt.createdAt`required	`string (date-time)`
`receipt.updatedAt`required	`string (date-time)`
`upload`required	`object (PresignedUpload)`nullable	PUT the file here with exactly these headers, then call upload-complete. Null when the file has already been uploaded.
`upload.url`required	`string (uri)`
`upload.method`required	`string (PresignedMethod)`	One of: `PUT`, `GET`
`upload.headers`required	`object`	Headers to send with the request.
`upload.expiresAt`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 the address for emailing receipts in

GET/api/v1/books/receipts/email-address

Scopes: books:read

Null until one is created. Part of the books product: the firm must have it and you must have access to it.

Responses

200 OK, `application/json`

Body: object (ReceiptEmailAddress).

Where to email receipts in. Anything sent here is read as a receipt for this business.

200 OK response for GET /api/v1/books/receipts/email-address
Field	Type	Description
`address`required	`string (email)`nullable	example "k3v9x2m8q4p7w1z6@receipts.tolvi.co.uk"
`createdAt`required	`string (date-time)`nullable

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

Create or replace the address for emailing receipts in

POST/api/v1/books/receipts/email-address

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

Anything emailed to it is read as a receipt for this business. Replacing it stops the old address working at once. The business’s owners and admins, signed in. Part of the books product: the firm must have it and you must have access to it.

Responses

200 OK, `application/json`

Body: object (ReceiptEmailAddress).

Where to email receipts in. Anything sent here is read as a receipt for this business.

200 OK response for POST /api/v1/books/receipts/email-address
Field	Type	Description
`address`required	`string (email)`nullable	example "k3v9x2m8q4p7w1z6@receipts.tolvi.co.uk"
`createdAt`required	`string (date-time)`nullable

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

Get a receipt

GET/api/v1/books/receipts/{id}

Scopes: books:read

The file’s state, what Tolvi AI read (with how sure it is), the checks, possible bank payments and what was confirmed. Part of the books product: the firm must have it and you must have access to it.

Parameters

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

Responses

200 OK, `application/json`

Body: object (Receipt).

A receipt or bill: the file (kept as the record), what Tolvi AI read from it, and what the person confirmed.

200 OK response for GET /api/v1/books/receipts/{id}
Field	Type	Description
`id`required	`string (uuid)`
`source`required	`string (ReceiptSource)`	One of: `camera`, `upload`, `email`
`fileName`required	`string`
`contentType`required	`string`
`sizeBytes`required	`integer`
`status`required	`string (ReceiptFileStatus)`	pending_upload, pending_scan (being checked for viruses), available, or rejected (with the reason). One of: `pending_upload`, `pending_scan`, `available`, `rejected`
`rejectedReason`required	`string`nullable
`readingStatus`required	`string (ReceiptReadingStatus)`	waiting (until the virus check passes), queued, reading, done or failed. One of: `waiting`, `queued`, `reading`, `done`, `failed`
`readingError`required	`string`nullable	Why reading failed, in plain English.
`reading`required	`object (ReceiptReading)`nullable	What Tolvi AI read from the receipt: a suggestion for the person to confirm or correct. Money in integer pence.
`reading.documentType`required	`string (ReceiptDocumentType)`	One of: `till_receipt`, `simplified_vat_invoice`, `vat_invoice`, `order_confirmation`, `statement`, `not_a_receipt`, `other`
`reading.supplierName`required	`string`nullable
`reading.supplierVatNumber`required	`string`nullable	As printed on the receipt.
`reading.documentNumber`required	`string`nullable
`reading.date`required	`string (date)`nullable	example "2026-03-31"
`reading.currency`required	`string`nullable	example "GBP"
`reading.totalPence`required	`integer`nullable	Integer pence (GBP).
`reading.netPence`required	`integer`nullable	Integer pence (GBP).
`reading.vatPence`required	`integer`nullable	Integer pence (GBP).
`reading.vatBreakdown`required	`array of ReceiptVatRow`
`reading.vatBreakdown[].rateBps`required	`integer`	VAT rate in basis points (2000 = 20%).
`reading.vatBreakdown[].netPence`required	`integer`nullable	Integer pence (GBP).
`reading.vatBreakdown[].vatPence`required	`integer`	Integer pence (GBP).
`reading.lineItems`required	`array of ReceiptLineItem`
`reading.lineItems[].description`required	`string`
`reading.lineItems[].quantity`required	`string`nullable
`reading.lineItems[].amountPence`required	`integer`	Integer pence (GBP).
`reading.lineItems[].vatRateBps`required	`integer`nullable
`reading.lineItems[].vatPence`	`integer`nullable	Integer pence (GBP). The VAT shown on this line. Absent on a reading from before lines were captured.
`reading.lineItems[].accountCode`	`string`nullable	The category Tolvi AI suggests, from the chart of accounts.
`reading.lineItems[].confidence`	`integer`	How sure Tolvi AI is of this line, from 0 to 100. 0 to 100
`reading.lineItems[].reason`	`string`nullable	Why it is unsure, when it is; otherwise empty.
`reading.moreLines`	`boolean`	The document has more lines than Tolvi AI kept.
`reading.paymentMethod`required	`string (ReceiptPaymentMethod)`	One of: `card`, `cash`, `bank_transfer`, `direct_debit`, `other`, `unknown`
`reading.cardLast4`required	`string`nullable	The last four digits of the card only.
`reading.fields`required	`object (ReceiptFieldNotes)`
`reading.fields.supplierName`required	`object (ReceiptFieldNote)`	How sure Tolvi AI is of one field, and why.
`reading.fields.supplierName.confidence`required	`string (ReceiptConfidence)`	One of: `high`, `medium`, `low`
`reading.fields.supplierName.reason`required	`string`
`reading.fields.supplierName.alternative`required	`string`nullable	Another reading worth checking, e.g. "£36.20".
`reading.fields.date`required	`object (ReceiptFieldNote)`	How sure Tolvi AI is of one field, and why.
`reading.fields.date.confidence`required	`string (ReceiptConfidence)`	One of: `high`, `medium`, `low`
`reading.fields.date.reason`required	`string`
`reading.fields.date.alternative`required	`string`nullable	Another reading worth checking, e.g. "£36.20".
`reading.fields.total`required	`object (ReceiptFieldNote)`	How sure Tolvi AI is of one field, and why.
`reading.fields.total.confidence`required	`string (ReceiptConfidence)`	One of: `high`, `medium`, `low`
`reading.fields.total.reason`required	`string`
`reading.fields.total.alternative`required	`string`nullable	Another reading worth checking, e.g. "£36.20".
`reading.fields.vat`required	`object (ReceiptFieldNote)`	How sure Tolvi AI is of one field, and why.
`reading.fields.vat.confidence`required	`string (ReceiptConfidence)`	One of: `high`, `medium`, `low`
`reading.fields.vat.reason`required	`string`
`reading.fields.vat.alternative`required	`string`nullable	Another reading worth checking, e.g. "£36.20".
`reading.fields.vatNumber`required	`object (ReceiptFieldNote)`	How sure Tolvi AI is of one field, and why.
`reading.fields.vatNumber.confidence`required	`string (ReceiptConfidence)`	One of: `high`, `medium`, `low`
`reading.fields.vatNumber.reason`required	`string`
`reading.fields.vatNumber.alternative`required	`string`nullable	Another reading worth checking, e.g. "£36.20".
`reading.notes`required	`string`
`reading.model`required	`string`	The model that read it.
`reading.promptVersion`required	`string`	example "extract_receipt@1"
`reading.readAt`required	`string (date-time)`
`suggestedLines`required	`array of ReceiptSuggestedLine`
`suggestedLines[].description`required	`string`
`suggestedLines[].accountCode`required	`string`nullable	The suggested category, from the chart of accounts.
`suggestedLines[].grossPence`required	`integer`	Integer pence (GBP). What the line cost, including any VAT.
`suggestedLines[].vatPence`required	`integer`	Integer pence (GBP). The VAT in that cost.
`suggestedLines[].vatCode`required	`string (VatCode)`	One of: `S20`, `R5`, `Z0`, `EX`, `OS`, `RC_SERV`, `DRC_SALE`, `DRC_SALE_R5`, `DRC_PURCH`, `RC_GOODS_SALE`, `RC_GOODS_PURCH`, `PIVA`, `IMPORT_C79`, `BLOCKED`
`suggestedLines[].checkThis`required	`boolean`	Tolvi AI was barely sure of this line: highlight it for the person to check. It never stops them.
`suggestedLines[].checkReason`required	`string`nullable
`checks`required	`object (ReceiptChecks)`nullable
`checks.of`required	`string (ReceiptChecksOf)`	Whether these checks are on what Tolvi AI read or on what the person confirmed. One of: `reading`, `confirmed`
`checks.problems`required	`array of ReceiptProblem`
`checks.problems[].code`required	`string`	example "no_vat_number"
`checks.problems[].severity`required	`string (ReceiptProblemSeverity)`	One of: `warning`, `info`
`checks.problems[].field`required	`string`nullable	example "vatNumber"
`checks.problems[].message`required	`string`
`checks.problems[].source`required	`string`nullable	The rule behind it.
`checks.vatClaimable`required	`boolean`	Whether the VAT on it can be reclaimed: the business is VAT registered and the receipt shows VAT and a valid UK VAT number.
`checks.suggestedVatCode`required	`string (VatCode)`nullable	One of: `S20`, `R5`, `Z0`, `EX`, `OS`, `RC_SERV`, `DRC_SALE`, `DRC_SALE_R5`, `DRC_PURCH`, `RC_GOODS_SALE`, `RC_GOODS_PURCH`, `PIVA`, `IMPORT_C79`, `BLOCKED`
`checks.vatNumber`required	`string`nullable	The VAT number without GB, when it passes the check digits.
`duplicateOfId`required	`string (uuid)`nullable	An earlier receipt this looks like a copy of.
`matches`required	`array of ReceiptMatch`
`matches[].bankLineId`required	`string (uuid)`
`matches[].bankAccountId`required	`string (uuid)`
`matches[].bookedAt`required	`string (date)`	example "2026-03-31"
`matches[].amountPence`required	`integer`	Integer pence (GBP). As on the bank line: money out is negative.
`matches[].description`required	`string`
`matches[].score`required	`integer`	0 to 100
`matches[].band`required	`string (ReceiptMatchBand)`	One of: `high`, `medium`, `low`
`matches[].summary`required	`string`
`matches[].reasons`required	`array of string`
`reviewStatus`required	`string (ReceiptReviewStatus)`	One of: `to_review`, `confirmed`, `discarded`
`confirmed`required	`object (ReceiptConfirmed)`nullable	What the person confirmed. Money in integer pence.
`confirmed.supplierName`required	`string`
`confirmed.supplierVatNumber`required	`string`nullable
`confirmed.date`required	`string (date)`	example "2026-03-31"
`confirmed.currency`required	`string`	example "GBP"
`confirmed.totalPence`required	`integer`	Integer pence (GBP).
`confirmed.netPence`required	`integer`nullable	Integer pence (GBP).
`confirmed.vatPence`required	`integer`nullable	Integer pence (GBP).
`confirmed.vatCode`required	`string (VatCode)`nullable	One of: `S20`, `R5`, `Z0`, `EX`, `OS`, `RC_SERV`, `DRC_SALE`, `DRC_SALE_R5`, `DRC_PURCH`, `RC_GOODS_SALE`, `RC_GOODS_PURCH`, `PIVA`, `IMPORT_C79`, `BLOCKED`
`confirmed.accountCode`required	`string`nullable
`confirmed.paymentMethod`required	`string (ReceiptPaymentMethod)`nullable	One of: `card`, `cash`, `bank_transfer`, `direct_debit`, `other`, `unknown`
`confirmed.cardLast4`required	`string`nullable
`confirmed.paidPersonally`required	`boolean`
`confirmed.bankLineId`required	`string (uuid)`nullable
`confirmed.note`required	`string`nullable
`confirmed.correctedFields`required	`array of string`	Fields the person changed from what Tolvi AI read; line1.category is the first line’s category.
`confirmed.lines`required	`array of ReceiptConfirmedLine`	The lines it went into the books as. Empty when it was confirmed as one amount.
`confirmed.lines[].description`required	`string`
`confirmed.lines[].accountCode`required	`string`nullable
`confirmed.lines[].grossPence`required	`integer`	Integer pence (GBP). What the line cost, including any VAT.
`confirmed.lines[].vatPence`required	`integer`	Integer pence (GBP).
`confirmed.confirmedBy`required	`string (uuid)`nullable
`confirmed.confirmedAt`required	`string (date-time)`
`postingStatus`required	`string (ReceiptPostingStatus)`	none, proposed (confirmed; waiting for the books), or posted. One of: `none`, `proposed`, `posted`
`postingProposal`required	`object`nullable	What confirming proposes for the books (version 1, or version 2 with lines).
`ledgerEntryId`required	`string (uuid)`nullable
`emailFrom`required	`string`nullable	For an emailed receipt: who sent it.
`emailSubject`required	`string`nullable
`previewable`required	`boolean`	Whether a browser can show the image (a HEIC photo has a JPEG preview once read).
`uploadedBy`required	`string (uuid)`nullable
`capturedAt`required	`string (date-time)`nullable
`createdAt`required	`string (date-time)`
`updatedAt`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).

Delete a receipt for good

DELETE/api/v1/books/receipts/{id}

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

Removes a receipt that isn’t in the books, with its files. It can’t be undone. 409, saying why, when it has been confirmed, is in the books, is matched to a bank payment or is attached to a bill: those are accounting records. Signed in people only; recorded in the audit log. Part of the books product: the firm must have it and you must have access to it.

Parameters

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

Responses

204 No content

Deleted.

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

Get a short-lived link to a receipt’s image

GET/api/v1/books/receipts/{id}/image

Scopes: books:read

Only once the file has passed the virus check. Recorded in the audit log. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/books/receipts/{id}/image
Name	In	Type	Description
`id`required	path	`string (uuid)`
`variant`	query	`string`	preview (default): the JPEG made from a HEIC photo when there is one; original: the file as received. One of: `preview`, `original`

Responses

200 OK, `application/json`

Body: object (ReceiptImage).

A short-lived link to the receipt’s image (or its JPEG preview for a HEIC photo).

200 OK response for GET /api/v1/books/receipts/{id}/image
Field	Type	Description
`url`required	`string (uri)`
`contentType`required	`string`
`expiresAt`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).

Presign a receipt upload again

POST/api/v1/books/receipts/{id}/upload

Scopes: books:write

A fresh PUT for a receipt still waiting for its file (the first PUT failed or expired). Only the person who added it; 409 once 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/receipts/{id}/upload
Name	In	Type	Description
`id`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (ReceiptUpload).

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

Finish a receipt upload

POST/api/v1/books/receipts/{id}/upload-complete

Scopes: books:write

Call after the PUT. Checks the stored file’s size, type and contents, records its checksum and starts the virus check. Once it passes, Tolvi AI reads it (readingStatus). 422 if the file is refused or malware is found. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/receipts/{id}/upload-complete
Name	In	Type	Description
`id`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (Receipt).

A receipt or bill: the file (kept as the record), what Tolvi AI read from it, and what the person confirmed.

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

Read a receipt again

POST/api/v1/books/receipts/{id}/read-again

Scopes: books:write

After a reading failed. Only for receipts still to review. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/receipts/{id}/read-again
Name	In	Type	Description
`id`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (Receipt).

A receipt or bill: the file (kept as the record), what Tolvi AI read from it, and what the person confirmed.

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

Confirm a receipt

POST/api/v1/books/receipts/{id}/confirm

Scopes: books:write

The person’s figures (what Tolvi AI read, checked or corrected), optionally the bank payment it matches or that it was paid personally. Checks run again on these figures. Confirming records what it means for the books (postingProposal); the ledger posts it. Needs a person, not an API client. Part of the books product: the firm must have it and you must have access to it.

Parameters

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

Request body

Required. application/json: object (ConfirmReceipt).

The person’s figures. Money in integer pence. Net plus VAT must equal the total.

Request body for POST /api/v1/books/receipts/{id}/confirm
Field	Type	Description
`supplierName`required	`string`	up to 200 characters
`supplierVatNumber`	`string`nullable	up to 20 characters
`date`required	`string (date)`	example "2026-03-31"
`currency`	`string`	example "GBP"
`totalPence`required	`integer`	Integer pence (GBP). at least 1
`poundsPence`	`integer`nullable	Integer pence (GBP). What a foreign receipt paid with the person’s own money cost in pounds. Required then; ignored otherwise. at least 1
`netPence`	`integer`nullable	Integer pence (GBP). at least 0
`vatPence`	`integer`nullable	Integer pence (GBP). at least 0
`vatCode`	`string (VatCode)`nullable	One of: `S20`, `R5`, `Z0`, `EX`, `OS`, `RC_SERV`, `DRC_SALE`, `DRC_SALE_R5`, `DRC_PURCH`, `RC_GOODS_SALE`, `RC_GOODS_PURCH`, `PIVA`, `IMPORT_C79`, `BLOCKED`
`accountCode`	`string`nullable	The account it goes to, from the chart of accounts (or chosen later, when the bank payment is confirmed).
`paymentMethod`	`string (ReceiptPaymentMethod)`nullable	One of: `card`, `cash`, `bank_transfer`, `direct_debit`, `other`, `unknown`
`cardLast4`	`string`nullable	pattern ^\d{4}$
`paidPersonally`	`boolean`	Paid with the owner’s own money: the business owes it back.
`bankLineId`	`string (uuid)`nullable	The bank payment it matches, from `matches`.
`note`	`string`nullable	up to 1000 characters
`lines`	`array of ConfirmReceiptLine`	The lines, each with its own category. They must add up to the total. Ignored for a receipt in another currency, where the amount in pounds comes from the bank payment. Left out, the whole amount is one line.
`lines[].description`required	`string`	up to 500 characters
`lines[].accountCode`	`string`nullable	The account this line goes to. Left out, it is chosen when the bank payment is confirmed, or goes to general costs.
`lines[].grossPence`required	`integer`	Integer pence (GBP). What the line cost, including any VAT. A discount is negative.
`lines[].vatPence`	`integer`nullable	Integer pence (GBP). The VAT in that cost. Used only when the VAT can be reclaimed.
`lines[].vatCode`	`string (VatCode)`nullable	One of: `S20`, `R5`, `Z0`, `EX`, `OS`, `RC_SERV`, `DRC_SALE`, `DRC_SALE_R5`, `DRC_PURCH`, `RC_GOODS_SALE`, `RC_GOODS_PURCH`, `PIVA`, `IMPORT_C79`, `BLOCKED`

Responses

200 OK, `application/json`

Body: object (Receipt).

A receipt or bill: the file (kept as the record), what Tolvi AI read from it, and what the person confirmed.

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

Discard a receipt

POST/api/v1/books/receipts/{id}/discard

Scopes: books:write

Not a receipt, or a copy of one already added. The file is kept until the receipt is deleted. A confirmed receipt can’t be discarded. Part of the books product: the firm must have it and you must have access to it.

Parameters

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

Responses

200 OK, `application/json`

Body: object (Receipt).

A receipt or bill: the file (kept as the record), what Tolvi AI read from it, and what the person confirmed.

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

What the business owes

GET/api/v1/books/purchases/summary

Scopes: books:read

What is owed, overdue and due in the next 7 days as at today, by supplier (most overdue first), with drafts. Part of the books product: the firm must have it and you must have access to it.

Responses

200 OK, `application/json`

Body: object (BooksPurchasesSummary).

What the business owes as at today.

200 OK response for GET /api/v1/books/purchases/summary
Field	Type	Description
`asAt`required	`string (date)`	example "2026-03-31"
`owedPence`required	`integer`	Integer pence (GBP).
`overduePence`required	`integer`	Integer pence (GBP).
`dueSoonPence`required	`integer`	Integer pence (GBP). What falls due in the next 7 days.
`unpaidBills`required	`integer`
`overdueBills`required	`integer`
`drafts`required	`integer`
`creditors`required	`array of BooksPurchasesCreditor`
`creditors[].supplierId`required	`string (uuid)`
`creditors[].supplierName`required	`string`
`creditors[].owedPence`required	`integer`	Integer pence (GBP).
`creditors[].overduePence`required	`integer`	Integer pence (GBP).
`creditors[].bills`required	`integer`

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

List suppliers

GET/api/v1/books/suppliers

Scopes: books:read

By name, with what is still owed to each. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/books/suppliers
Name	In	Type	Description
`q`	query	`string`
`archived`	query	`string`	One of: `live`, `archived`, `all`

Responses

200 OK, `application/json`

Body: object (BooksSupplierList).

200 OK response for GET /api/v1/books/suppliers
Field	Type	Description
`items`required	`array of BooksSupplier`
`items[].id`required	`string (uuid)`
`items[].name`required	`string`
`items[].email`required	`string`nullable
`items[].addressLines`required	`array of string`
`items[].postcode`required	`string`nullable
`items[].vatNumber`required	`string`nullable
`items[].paymentTermsDays`required	`integer`nullable	Days to pay; null means 30 days unless a bill gives a due date.
`items[].defaultAccountId`required	`string (uuid)`nullable	The account used on the last bill, to fill in the next one.
`items[].defaultVatCode`required	`string`nullable
`items[].owedPence`required	`integer`	What is still owed, in pence.
`items[].openBills`required	`integer`
`items[].archived`required	`boolean`

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

Add a supplier

POST/api/v1/books/suppliers

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

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

Parameters

Parameters for POST /api/v1/books/suppliers
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 (BooksSupplierInput).

Request body for POST /api/v1/books/suppliers
Field	Type	Description
`name`required	`string`	up to 200 characters
`email`	`string`nullable
`addressLines`	`array of string`
`postcode`	`string`nullable
`vatNumber`	`string`nullable
`paymentTermsDays`	`integer`nullable	0 to 365

Responses

201 Created, `application/json`

Body: object (BooksSupplier).

A business this business buys from.

201 Created response for POST /api/v1/books/suppliers
Field	Type	Description
`id`required	`string (uuid)`
`name`required	`string`
`email`required	`string`nullable
`addressLines`required	`array of string`
`postcode`required	`string`nullable
`vatNumber`required	`string`nullable
`paymentTermsDays`required	`integer`nullable	Days to pay; null means 30 days unless a bill gives a due date.
`defaultAccountId`required	`string (uuid)`nullable	The account used on the last bill, to fill in the next one.
`defaultVatCode`required	`string`nullable
`owedPence`required	`integer`	What is still owed, in pence.
`openBills`required	`integer`
`archived`required	`boolean`

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 supplier

GET/api/v1/books/suppliers/{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/suppliers/{id}
Name	In	Type	Description
`id`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (BooksSupplier).

A business this business buys from.

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

Change or archive a supplier

PATCH/api/v1/books/suppliers/{id}

Scopes: books:write

A supplier who is still owed money can’t be archived. Posted bills keep the name they were posted with. Part of the books product: the firm must have it and you must have access to it.

Parameters

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

Request body

Required. application/json: object (BooksSupplierPatch).

Request body for PATCH /api/v1/books/suppliers/{id}
Field	Type	Description
`name`	`string`	up to 200 characters
`email`	`string`nullable
`addressLines`	`array of string`
`postcode`	`string`nullable
`vatNumber`	`string`nullable
`paymentTermsDays`	`integer`nullable	0 to 365
`archived`	`boolean`

Responses

200 OK, `application/json`

Body: object (BooksSupplier).

A business this business buys from.

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 bills

GET/api/v1/books/bills

Scopes: books:read

Newest first. Status is worked out as at today: to_pay includes part-paid bills; overdue is past its due date with something still to pay. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/books/bills
Name	In	Type	Description
`limit`	query	`number`
`supplierId`	query	`string (uuid)`
`kind`	query	`string`	One of: `bill`, `supplier_credit`, `all`
`status`	query	`string`	One of: `all`, `draft`, `to_pay`, `overdue`, `paid`, `void`

Responses

200 OK, `application/json`

Body: object (BooksBillList).

200 OK response for GET /api/v1/books/bills
Field	Type	Description
`items`required	`array of BooksBill`
`items[].id`required	`string (uuid)`
`items[].kind`required	`string (BooksBillKind)`	One of: `bill`, `supplier_credit`
`items[].state`required	`string (BooksBillState)`	One of: `draft`, `posted`
`items[].status`required	`string (BooksBillStatus)`	One of: `draft`, `to_pay`, `part_paid`, `overdue`, `paid`, `void`
`items[].supplierId`required	`string (uuid)`
`items[].supplierName`required	`string`
`items[].reference`required	`string`nullable	The supplier’s own invoice or credit note number.
`items[].billDate`required	`string (date)`nullable	example "2026-03-31"
`items[].dueDate`required	`string (date)`nullable	example "2026-03-31"
`items[].notes`required	`string`nullable
`items[].reason`required	`string`nullable
`items[].creditsId`required	`string (uuid)`nullable
`items[].opening`required	`boolean`	Brought forward with the starting balances: dated before the books start, with no VAT breakdown.
`items[].receiptId`required	`string (uuid)`nullable	The photo or PDF this came from (GET /books/receipts/{id}/image).
`items[].netPence`required	`integer`	Integer pence (GBP).
`items[].vatPence`required	`integer`	Integer pence (GBP).
`items[].grossPence`required	`integer`	Integer pence (GBP).
`items[].paidPence`required	`integer`	Integer pence (GBP).
`items[].creditedPence`required	`integer`	Integer pence (GBP).
`items[].outstandingPence`required	`integer`	Integer pence (GBP).
`items[].overpaidPence`required	`integer`	Integer pence (GBP).
`items[].daysOverdue`required	`integer`
`items[].ledgerEntryId`required	`string (uuid)`nullable
`items[].createdAt`required	`string (date-time)`
`items[].postedAt`required	`string (date-time)`nullable

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

Start or add a bill

POST/api/v1/books/bills

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

Give a supplierId, or a supplierName to find or add one. With post: true it goes into the books straight away (Dr costs and VAT, Cr creditors); otherwise it stays a draft. With a receiptId the photo or PDF stays with the bill; posting confirms the receipt with these figures, which is the person’s decision on what Tolvi AI read. 409 if the same supplier reference has already been added. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/bills
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 (BooksCreateBill).

A supplierId, or a supplierName to find or add one.

Request body for POST /api/v1/books/bills
Field	Type	Description
`supplierId`	`string (uuid)`
`supplierName`	`string`	up to 200 characters
`reference`	`string`nullable	The supplier’s own invoice number.
`billDate`	`string (date)`nullable	example "2026-03-31"
`dueDate`	`string (date)`nullable	Left out: the supplier’s terms, or 30 days. example "2026-03-31"
`notes`	`string`nullable
`lines`	`array of BooksBillLineInput`
`lines[].description`required	`string`	up to 500 characters
`lines[].accountId`required	`string (uuid)`	A cost or asset account.
`lines[].netPence`required	`integer`	Integer pence (GBP).
`lines[].vatCode`required	`string`	example "S20"
`lines[].vatPence`	`integer`	Integer pence (GBP). The VAT on the bill; worked from the rate at the bill’s date when left out.
`receiptId`	`string (uuid)`	The receipt or bill photo this came from.
`post`	`boolean`	Add it to the books straight away.

Responses

201 Created, `application/json`

Body: object (BooksBillDetail).

201 Created response for POST /api/v1/books/bills
Field	Type	Description
`id`required	`string (uuid)`
`kind`required	`string (BooksBillKind)`	One of: `bill`, `supplier_credit`
`state`required	`string (BooksBillState)`	One of: `draft`, `posted`
`status`required	`string (BooksBillStatus)`	One of: `draft`, `to_pay`, `part_paid`, `overdue`, `paid`, `void`
`supplierId`required	`string (uuid)`
`supplierName`required	`string`
`reference`required	`string`nullable	The supplier’s own invoice or credit note number.
`billDate`required	`string (date)`nullable	example "2026-03-31"
`dueDate`required	`string (date)`nullable	example "2026-03-31"
`notes`required	`string`nullable
`reason`required	`string`nullable
`creditsId`required	`string (uuid)`nullable
`opening`required	`boolean`	Brought forward with the starting balances: dated before the books start, with no VAT breakdown.
`receiptId`required	`string (uuid)`nullable	The photo or PDF this came from (GET /books/receipts/{id}/image).
`netPence`required	`integer`	Integer pence (GBP).
`vatPence`required	`integer`	Integer pence (GBP).
`grossPence`required	`integer`	Integer pence (GBP).
`paidPence`required	`integer`	Integer pence (GBP).
`creditedPence`required	`integer`	Integer pence (GBP).
`outstandingPence`required	`integer`	Integer pence (GBP).
`overpaidPence`required	`integer`	Integer pence (GBP).
`daysOverdue`required	`integer`
`ledgerEntryId`required	`string (uuid)`nullable
`createdAt`required	`string (date-time)`
`postedAt`required	`string (date-time)`nullable
`lines`required	`array of BooksBillLine`
`lines[].id`required	`string (uuid)`
`lines[].description`required	`string`
`lines[].accountId`required	`string (uuid)`
`lines[].accountName`required	`string`
`lines[].netPence`required	`integer`	Integer pence (GBP).
`lines[].vatCode`required	`string`	example "S20"
`lines[].vatPence`required	`integer`	Integer pence (GBP).
`payments`required	`array of BooksBillPayment`
`payments[].id`required	`string (uuid)`
`payments[].paidOn`required	`string (date)`	example "2026-03-31"
`payments[].amountPence`required	`integer`	Integer pence (GBP).
`payments[].method`required	`string (BooksBillPaymentMethod)`	One of: `bank_transfer`, `card`, `cash`, `cheque`, `other`
`payments[].accountId`required	`string (uuid)`
`payments[].accountName`required	`string`
`payments[].reference`required	`string`nullable
`payments[].bankLineId`required	`string (uuid)`nullable	Set when it was matched from a bank line: undo it in Bank.
`payments[].undone`required	`boolean`
`credits`required	`array of BooksBillCredit`
`credits[].id`required	`string (uuid)`
`credits[].reference`required	`string`nullable
`credits[].date`required	`string (date)`nullable	example "2026-03-31"
`credits[].amountPence`required	`integer`	Integer pence (GBP).
`credits[].reason`required	`string`nullable

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

A bill as Tolvi AI read it

GET/api/v1/books/bills/from-receipt/{receiptId}

Scopes: books:read

A suggestion to check, from a receipt or bill that has been read. Nothing is saved or posted. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/books/bills/from-receipt/{receiptId}
Name	In	Type	Description
`receiptId`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (BooksBillProposal).

A bill as Tolvi AI read it from a receipt or bill: a suggestion. Nothing is saved until the person checks it and creates the bill.

200 OK response for GET /api/v1/books/bills/from-receipt/{receiptId}
Field	Type	Description
`receiptId`required	`string (uuid)`
`existingBillId`required	`string (uuid)`nullable	A draft already started from this file: open that instead.
`supplierId`required	`string (uuid)`nullable	The supplier if the name read matches one.
`supplierName`required	`string`nullable
`reference`required	`string`nullable
`billDate`required	`string (date)`nullable	example "2026-03-31"
`dueDate`required	`string (date)`nullable	example "2026-03-31"
`lines`required	`array of BooksBillProposalLine`
`lines[].description`required	`string`
`lines[].accountId`required	`string (uuid)`nullable
`lines[].netPence`required	`integer`	Integer pence (GBP).
`lines[].vatCode`required	`string`
`lines[].vatPence`required	`integer`	Integer pence (GBP).
`lines[].checkThis`required	`boolean`	Tolvi AI was barely sure of this line: highlight it for the person to check. It never stops them.
`lines[].checkReason`required	`string`nullable
`warnings`required	`array of string`	What to check, in plain English.
`documentTotalPence`required	`integer`nullable	Integer pence (GBP). The total printed on the document, to compare the lines with. Null when it couldn’t be read or isn’t in pounds.
`linesWarning`required	`string`nullable	Which of the warnings says the lines don’t add up, so it can go once they do.
`readingStatus`required	`string (BooksBillProposalReading)`	One of: `waiting`, `queued`, `reading`, `done`, `failed`
`foreignCurrency`required	`string`nullable	The currency, when the document isn’t in pounds. Bills are in pounds, so no amount is suggested.

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

Get a bill

GET/api/v1/books/bills/{id}

Scopes: books:read

With its lines, what is owed, payments and credits. Part of the books product: the firm must have it and you must have access to it.

Parameters

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

Responses

200 OK, `application/json`

Body: object (BooksBillDetail).

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

Change a draft bill

PATCH/api/v1/books/bills/{id}

Scopes: books:write

409 once it is in the books: a posted bill is corrected with a credit. Part of the books product: the firm must have it and you must have access to it.

Parameters

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

Request body

Required. application/json: object (BooksUpdateBill).

Request body for PATCH /api/v1/books/bills/{id}
Field	Type	Description
`supplierId`	`string (uuid)`
`supplierName`	`string`	up to 200 characters
`reference`	`string`nullable
`billDate`	`string (date)`nullable	example "2026-03-31"
`dueDate`	`string (date)`nullable	example "2026-03-31"
`notes`	`string`nullable
`lines`	`array of BooksBillLineInput`
`lines[].description`required	`string`	up to 500 characters
`lines[].accountId`required	`string (uuid)`	A cost or asset account.
`lines[].netPence`required	`integer`	Integer pence (GBP).
`lines[].vatCode`required	`string`	example "S20"
`lines[].vatPence`	`integer`	Integer pence (GBP). The VAT on the bill; worked from the rate at the bill’s date when left out.

Responses

200 OK, `application/json`

Body: object (BooksBillDetail).

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

Delete a draft bill

DELETE/api/v1/books/bills/{id}

Scopes: books:write

409 once it is in the books. The file it came from is kept. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for DELETE /api/v1/books/bills/{id}
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).

Add a draft bill to the books

POST/api/v1/books/bills/{id}/post

Scopes: books:write

Posts it through the ledger with VAT on every line, in one step. 422 with the reasons when it can’t post (for example a locked period). Part of the books product: the firm must have it and you must have access to it.

Parameters

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

Responses

200 OK, `application/json`

Body: object (BooksBillDetail).

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

Record a supplier credit note

POST/api/v1/books/bills/{id}/credit

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

All of what hasn’t been credited, or amountPence gross shared across the bill’s lines, at the VAT rates of the original supply (VAT Notice 700 section 19). Posts 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/bills/{id}/credit
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 (BooksCreditBill).

Request body for POST /api/v1/books/bills/{id}/credit
Field	Type	Description
`reason`required	`string`	up to 200 characters
`reference`	`string`nullable	The supplier’s credit note number.
`date`	`string (date)`	example "2026-03-31"
`amountPence`	`integer`	Integer pence (GBP). Gross. Left out, everything not credited yet. at least 1

Responses

201 Created, `application/json`

Body: object (BooksBillDetail).

The fields are as shown above.

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

Cancel a bill

POST/api/v1/books/bills/{id}/void

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

Posts a credit for the whole bill, so the record stays and the books balance. 409 if anything has been paid or credited. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/bills/{id}/void
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 (BooksVoidBill).

Request body for POST /api/v1/books/bills/{id}/void
Field	Type	Description
`reason`required	`string`	up to 200 characters
`date`	`string (date)`	example "2026-03-31"

Responses

200 OK, `application/json`

Body: object (BooksBillDetail).

The fields are as shown above.

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

Record a payment made

POST/api/v1/books/bills/{id}/payments

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

For money paid outside the bank feed. Part payments are fine; no more than is owed. Dr creditors, Cr the account it came from, and the share of the bill’s VAT settled for cash accounting. Tolvi doesn’t send the money. A bank line is matched in Bank instead. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/bills/{id}/payments
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 (BooksPayBill).

Request body for POST /api/v1/books/bills/{id}/payments
Field	Type	Description
`paidOn`required	`string (date)`	example "2026-03-31"
`amountPence`required	`integer`	Integer pence (GBP). at least 1
`accountId`required	`string (uuid)`	The bank, cash or card account it came from, or the owner’s own account (director’s loan, capital introduced, partner’s current account).
`method`	`string (BooksBillPayMethod)`	One of: `bank_transfer`, `card`, `cash`, `cheque`, `other`
`reference`	`string`nullable

Responses

201 Created, `application/json`

Body: object (BooksBillDetail).

The fields are as shown above.

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

Undo a payment recorded by hand

POST/api/v1/books/bills/{id}/payments/{paymentId}/undo

Scopes: books:write

Posts the reversal and reverses its VAT settlement. 409 for one matched from a bank line: undo that in Bank. Part of the books product: the firm must have it and you must have access to it.

Parameters

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

Responses

200 OK, `application/json`

Body: object (BooksBillDetail).

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

Books: purchases and receipts

List receipts

Parameters

Responses

200 OK, application/json

Add a receipt

Parameters

Request body

Responses

201 Created, application/json

Get the address for emailing receipts in

Responses

200 OK, application/json

Create or replace the address for emailing receipts in

Responses

200 OK, application/json

Get a receipt

Parameters

Responses

200 OK, application/json

Delete a receipt for good

Parameters

Responses

204 No content

Get a short-lived link to a receipt’s image

Parameters

Responses

200 OK, application/json

Presign a receipt upload again

Parameters

Responses

200 OK, application/json

Finish a receipt upload

Parameters

Responses

200 OK, application/json

Read a receipt again

Parameters

Responses

200 OK, application/json

Confirm a receipt

Parameters

Request body

Responses

200 OK, application/json

Discard a receipt

Parameters

Responses

200 OK, application/json

What the business owes

Responses

200 OK, application/json

List suppliers

Parameters

Responses

200 OK, application/json

Add a supplier

Parameters

Request body

Responses

201 Created, application/json

Get a supplier

Parameters

Responses

200 OK, application/json

Change or archive a supplier

Parameters

Request body

Responses

200 OK, application/json

List bills

Parameters

Responses

200 OK, application/json

Start or add a bill

Parameters

Request body

Responses

201 Created, application/json

A bill as Tolvi AI read it

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`

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`

201 Created, `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`

201 Created, `application/json`

200 OK, `application/json`