Books: VAT and reports

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

Get the profit and loss

GET/api/v1/books/reports/profit-and-loss

Scopes: books:read

For any period, with a comparison period (by default the same dates a year earlier). Derived from posted entries. Every figure has a drillKey for the drill-down. Anyone who can read the books: the business’s own people (including view-only) and a linked practice. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/books/reports/profit-and-loss
Name	In	Type	Description
`compareTo`	query	`string (date)`	An explicit comparison period (with compareFrom).
`compareFrom`	query	`string (date)`	An explicit comparison period (with compareTo).
`compare`	query	`string`	previous_year (default), previous_period or none. Ignored when explicit comparison dates are given. One of: `previous_year`, `previous_period`, `none`
`to`	query	`string (date)`	Defaults to today.
`from`	query	`string (date)`	Defaults to the start of the financial year containing `to`.

Responses

200 OK, `application/json`

Body: object (BooksProfitAndLoss).

Profit and loss for a period, with an optional comparison period (FRS 102 Section 1A layout, grouped by each account’s lead schedule line), and the same figures grouped for owners.

200 OK response for GET /api/v1/books/reports/profit-and-loss
Field	Type	Description
`from`required	`string (date)`	example "2026-03-31"
`to`required	`string (date)`	example "2026-03-31"
`compareFrom`required	`string (date)`nullable	example "2026-03-31"
`compareTo`required	`string (date)`nullable	example "2026-03-31"
`throughSeq`required	`integer`	The ledger point the report reflects.
`sections`required	`array of BooksReportSection`
`sections[].id`required	`string`	Profit and loss: turnover, cost_of_sales, overheads, other_income, interest, tax. Balance sheet: fixed_assets, current_assets, current_liabilities, long_term_liabilities, unsorted, capital.
`sections[].label`required	`string`
`sections[].lines`required	`array of BooksReportLine`
`sections[].lines[].accountId`required	`string (uuid)`nullable
`sections[].lines[].code`required	`string`
`sections[].lines[].name`required	`string`
`sections[].lines[].ownerName`required	`string`
`sections[].lines[].ownerCategory`required	`string (BooksOwnerCategory)`	One of: `sales`, `other_income`, `direct_costs`, `staff`, `premises`, `travel`, `office`, `marketing`, `professional`, `finance_costs`, `other_costs`, `write_offs`, `tax`, `bank_and_cash`, `owed_to_you`, `you_owe`, `equipment`, `stock`, `owner`, `behind_the_scenes`
`sections[].lines[].currentPence`required	`integer`	Integer pence (GBP).
`sections[].lines[].comparePence`required	`integer`nullable	Integer pence (GBP). Null when no comparison was asked for.
`sections[].lines[].drillKey`required	`string`	Pass to the drill-down to list the entries behind this figure.
`sections[].currentPence`required	`integer`	Integer pence (GBP).
`sections[].comparePence`required	`integer`nullable	Integer pence (GBP).
`sections[].drillKey`required	`string`
`totals`required	`array of BooksReportTotal`
`totals[].id`required	`string`	Profit and loss: gross_profit, operating_profit, profit_before_tax, net_profit. Balance sheet: net_current_assets, total_assets_less_current_liabilities, net_assets, capital_and_reserves.
`totals[].label`required	`string`
`totals[].currentPence`required	`integer`	Integer pence (GBP).
`totals[].comparePence`required	`integer`nullable	Integer pence (GBP).
`totals[].drillKey`required	`string`
`ownerView`required	`object (BooksProfitAndLossOwnerView)`
`ownerView.moneyIn`required	`array of BooksReportOwnerGroup`
`ownerView.moneyIn[].category`required	`string (BooksOwnerCategory)`	One of: `sales`, `other_income`, `direct_costs`, `staff`, `premises`, `travel`, `office`, `marketing`, `professional`, `finance_costs`, `other_costs`, `write_offs`, `tax`, `bank_and_cash`, `owed_to_you`, `you_owe`, `equipment`, `stock`, `owner`, `behind_the_scenes`
`ownerView.moneyIn[].label`required	`string`
`ownerView.moneyIn[].lines`required	`array of BooksReportLine`
`ownerView.moneyIn[].lines[].accountId`required	`string (uuid)`nullable
`ownerView.moneyIn[].lines[].code`required	`string`
`ownerView.moneyIn[].lines[].name`required	`string`
`ownerView.moneyIn[].lines[].ownerName`required	`string`
`ownerView.moneyIn[].lines[].ownerCategory`required	`string (BooksOwnerCategory)`	One of: `sales`, `other_income`, `direct_costs`, `staff`, `premises`, `travel`, `office`, `marketing`, `professional`, `finance_costs`, `other_costs`, `write_offs`, `tax`, `bank_and_cash`, `owed_to_you`, `you_owe`, `equipment`, `stock`, `owner`, `behind_the_scenes`
`ownerView.moneyIn[].lines[].currentPence`required	`integer`	Integer pence (GBP).
`ownerView.moneyIn[].lines[].comparePence`required	`integer`nullable	Integer pence (GBP). Null when no comparison was asked for.
`ownerView.moneyIn[].lines[].drillKey`required	`string`	Pass to the drill-down to list the entries behind this figure.
`ownerView.moneyIn[].currentPence`required	`integer`	Integer pence (GBP).
`ownerView.moneyIn[].comparePence`required	`integer`nullable	Integer pence (GBP).
`ownerView.moneyIn[].drillKey`required	`string`
`ownerView.costs`required	`array of BooksReportOwnerGroup`
`ownerView.costs[].category`required	`string (BooksOwnerCategory)`	One of: `sales`, `other_income`, `direct_costs`, `staff`, `premises`, `travel`, `office`, `marketing`, `professional`, `finance_costs`, `other_costs`, `write_offs`, `tax`, `bank_and_cash`, `owed_to_you`, `you_owe`, `equipment`, `stock`, `owner`, `behind_the_scenes`
`ownerView.costs[].label`required	`string`
`ownerView.costs[].lines`required	`array of BooksReportLine`
`ownerView.costs[].lines[].accountId`required	`string (uuid)`nullable
`ownerView.costs[].lines[].code`required	`string`
`ownerView.costs[].lines[].name`required	`string`
`ownerView.costs[].lines[].ownerName`required	`string`
`ownerView.costs[].lines[].ownerCategory`required	`string (BooksOwnerCategory)`	One of: `sales`, `other_income`, `direct_costs`, `staff`, `premises`, `travel`, `office`, `marketing`, `professional`, `finance_costs`, `other_costs`, `write_offs`, `tax`, `bank_and_cash`, `owed_to_you`, `you_owe`, `equipment`, `stock`, `owner`, `behind_the_scenes`
`ownerView.costs[].lines[].currentPence`required	`integer`	Integer pence (GBP).
`ownerView.costs[].lines[].comparePence`required	`integer`nullable	Integer pence (GBP). Null when no comparison was asked for.
`ownerView.costs[].lines[].drillKey`required	`string`	Pass to the drill-down to list the entries behind this figure.
`ownerView.costs[].currentPence`required	`integer`	Integer pence (GBP).
`ownerView.costs[].comparePence`required	`integer`nullable	Integer pence (GBP).
`ownerView.costs[].drillKey`required	`string`
`ownerView.moneyInPence`required	`integer`	Integer pence (GBP).
`ownerView.moneyInComparePence`required	`integer`nullable	Integer pence (GBP).
`ownerView.costsPence`required	`integer`	Integer pence (GBP).
`ownerView.costsComparePence`required	`integer`nullable	Integer pence (GBP).
`netProfitPence`required	`integer`	Integer pence (GBP).
`netProfitComparePence`required	`integer`nullable	Integer pence (GBP).

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

Get the balance sheet

GET/api/v1/books/reports/balance-sheet

Scopes: books:read

What the business owns and owes at a date, with a comparison date. Profit for the year so far is a line in capital and reserves. Anyone who can read the books: the business’s own people (including view-only) and a linked practice. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/books/reports/balance-sheet
Name	In	Type	Description
`compareAsAt`	query	`string (date)`	An explicit comparison date.
`compare`	query	`string`	previous_year (default: a year earlier), previous_period (the end of the previous financial year) or none. One of: `previous_year`, `previous_period`, `none`
`asAt`	query	`string (date)`	Defaults to today.

Responses

200 OK, `application/json`

Body: object (BooksBalanceSheet).

What the business owns and owes at a date, with an optional comparison date. Profit for the year so far is a line in capital and reserves.

200 OK response for GET /api/v1/books/reports/balance-sheet
Field	Type	Description
`asAt`required	`string (date)`	example "2026-03-31"
`yearStart`required	`string (date)`	example "2026-03-31"
`compareAsAt`required	`string (date)`nullable	example "2026-03-31"
`compareYearStart`required	`string (date)`nullable	example "2026-03-31"
`throughSeq`required	`integer`
`sections`required	`array of BooksReportSection`
`sections[].id`required	`string`	Profit and loss: turnover, cost_of_sales, overheads, other_income, interest, tax. Balance sheet: fixed_assets, current_assets, current_liabilities, long_term_liabilities, unsorted, capital.
`sections[].label`required	`string`
`sections[].lines`required	`array of BooksReportLine`
`sections[].lines[].accountId`required	`string (uuid)`nullable
`sections[].lines[].code`required	`string`
`sections[].lines[].name`required	`string`
`sections[].lines[].ownerName`required	`string`
`sections[].lines[].ownerCategory`required	`string (BooksOwnerCategory)`	One of: `sales`, `other_income`, `direct_costs`, `staff`, `premises`, `travel`, `office`, `marketing`, `professional`, `finance_costs`, `other_costs`, `write_offs`, `tax`, `bank_and_cash`, `owed_to_you`, `you_owe`, `equipment`, `stock`, `owner`, `behind_the_scenes`
`sections[].lines[].currentPence`required	`integer`	Integer pence (GBP).
`sections[].lines[].comparePence`required	`integer`nullable	Integer pence (GBP). Null when no comparison was asked for.
`sections[].lines[].drillKey`required	`string`	Pass to the drill-down to list the entries behind this figure.
`sections[].currentPence`required	`integer`	Integer pence (GBP).
`sections[].comparePence`required	`integer`nullable	Integer pence (GBP).
`sections[].drillKey`required	`string`
`totals`required	`array of BooksReportTotal`
`totals[].id`required	`string`	Profit and loss: gross_profit, operating_profit, profit_before_tax, net_profit. Balance sheet: net_current_assets, total_assets_less_current_liabilities, net_assets, capital_and_reserves.
`totals[].label`required	`string`
`totals[].currentPence`required	`integer`	Integer pence (GBP).
`totals[].comparePence`required	`integer`nullable	Integer pence (GBP).
`totals[].drillKey`required	`string`
`balanced`required	`boolean`	Net assets equal capital and reserves.

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

Get aged debtors (who owes the business)

GET/api/v1/books/reports/aged-debtors

Scopes: books:read

By customer and by how overdue. Anyone who can read the books: the business’s own people (including view-only) and a linked practice. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/books/reports/aged-debtors
Name	In	Type	Description
`asAt`	query	`string (date)`	Defaults to today.

Responses

200 OK, `application/json`

Body: object (BooksAgedReport).

Who owes the business (debtors) or whom it owes (creditors), by how overdue. Worked from unpaid invoices and bills where they exist (basis: documents), otherwise from the trade debtors or creditors control account by contact, payments set against the oldest amounts first and amounts assumed due termsDays after their date (basis: ledger). The control account balance is shown beside the total.

200 OK response for GET /api/v1/books/reports/aged-debtors
Field	Type	Description
`side`required	`string (BooksAgedSide)`	One of: `debtors`, `creditors`
`asAt`required	`string (date)`	example "2026-03-31"
`basis`required	`string (BooksAgedBasis)`	One of: `documents`, `ledger`
`termsDays`required	`integer`nullable
`contacts`required	`array of BooksAgedContact`
`contacts[].contactId`required	`string`nullable
`contacts[].name`required	`string`
`contacts[].buckets`required	`object (BooksAgedBuckets)`	Pence by how overdue: not yet due, 1–30, 31–60, 61–90 and over 90 days.
`contacts[].buckets.current`required	`integer`
`contacts[].buckets.days_1_30`required	`integer`
`contacts[].buckets.days_31_60`required	`integer`
`contacts[].buckets.days_61_90`required	`integer`
`contacts[].buckets.over_90`required	`integer`
`contacts[].totalPence`required	`integer`	Integer pence (GBP).
`contacts[].overduePence`required	`integer`	Integer pence (GBP).
`contacts[].items`required	`array of BooksAgedItem`
`contacts[].items[].reference`required	`string`
`contacts[].items[].date`required	`string (date)`	example "2026-03-31"
`contacts[].items[].dueDate`required	`string (date)`nullable	example "2026-03-31"
`contacts[].items[].daysOverdue`required	`integer`
`contacts[].items[].bucket`required	`string (BooksAgedBucket)`	One of: `current`, `days_1_30`, `days_31_60`, `days_61_90`, `over_90`
`contacts[].items[].outstandingPence`required	`integer`	Integer pence (GBP). Still owed; negative for money paid on account.
`contacts[].items[].documentId`required	`string`nullable	The invoice or bill, when worked from documents.
`contacts[].items[].entryId`required	`string (uuid)`nullable	The ledger entry, when worked from the ledger.
`totals`required	`object (BooksAgedBuckets)`	Pence by how overdue: not yet due, 1–30, 31–60, 61–90 and over 90 days.
`totals.current`required	`integer`
`totals.days_1_30`required	`integer`
`totals.days_31_60`required	`integer`
`totals.days_61_90`required	`integer`
`totals.over_90`required	`integer`
`totalPence`required	`integer`	Integer pence (GBP).
`overduePence`required	`integer`	Integer pence (GBP).
`controlBalancePence`required	`integer`	Integer pence (GBP). The control account at `asAt`; owed is positive.
`differencePence`required	`integer`	Integer pence (GBP). Control balance less the aged total (nil on the ledger basis).

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

Get aged creditors (whom the business owes)

GET/api/v1/books/reports/aged-creditors

Scopes: books:read

By supplier and by how overdue. Anyone who can read the books: the business’s own people (including view-only) and a linked practice. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/books/reports/aged-creditors
Name	In	Type	Description
`asAt`	query	`string (date)`	Defaults to today.

Responses

200 OK, `application/json`

Body: object (BooksAgedReport).

The fields are as shown above.

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

Get the VAT owed per the books

GET/api/v1/books/reports/vat

Scopes: books:read

The VAT control account over a period, explained. The VAT return itself is worked separately from each transaction’s VAT. Anyone who can read the books: the business’s own people (including view-only) and a linked practice. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/books/reports/vat
Name	In	Type	Description
`to`	query	`string (date)`	Defaults to today.
`from`	query	`string (date)`	Defaults to the start of the financial year containing `to`.

Responses

200 OK, `application/json`

Body: object (BooksVatOwed).

The VAT control account over a period: owed to HMRC at the start, VAT on sales, VAT on purchases, payments to or from HMRC, other adjustments, and owed at the end. Owed to HMRC is positive. This is what the books say; the VAT return is worked from each transaction’s VAT by tax point.

200 OK response for GET /api/v1/books/reports/vat
Field	Type	Description
`from`required	`string (date)`	example "2026-03-31"
`to`required	`string (date)`	example "2026-03-31"
`accountId`required	`string (uuid)`
`openingPence`required	`integer`	Integer pence (GBP).
`salesPence`required	`integer`	Integer pence (GBP).
`purchasesPence`required	`integer`	Integer pence (GBP). Negative: VAT you can reclaim reduces what is owed.
`paymentsPence`required	`integer`	Integer pence (GBP). Negative for a payment to HMRC.
`otherPence`required	`integer`	Integer pence (GBP).
`closingPence`required	`integer`	Integer pence (GBP).

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

Get cash flow by month

GET/api/v1/books/reports/cash-flow

Scopes: books:read

Money in and out of the bank, cash and card accounts, month by month, with the balance at each month end. Moving money between the business’s own accounts is neither. Up to five years. Anyone who can read the books: the business’s own people (including view-only) and a linked practice. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/books/reports/cash-flow
Name	In	Type	Description
`to`	query	`string (date)`	Defaults to today.
`from`	query	`string (date)`	Defaults to the start of the financial year containing `to`.

Responses

200 OK, `application/json`

Body: object (BooksCashFlow).

Money in and out of the bank, cash and card accounts, by month. Moving money between the business’s own accounts is neither.

200 OK response for GET /api/v1/books/reports/cash-flow
Field	Type	Description
`from`required	`string (date)`	example "2026-03-31"
`to`required	`string (date)`	example "2026-03-31"
`openingPence`required	`integer`	Integer pence (GBP).
`months`required	`array of BooksCashFlowMonth`
`months[].month`required	`string`	example "2026-10"
`months[].from`required	`string (date)`	example "2026-03-31"
`months[].to`required	`string (date)`	example "2026-03-31"
`months[].inPence`required	`integer`	Integer pence (GBP).
`months[].outPence`required	`integer`	Integer pence (GBP).
`months[].netPence`required	`integer`	Integer pence (GBP).
`months[].closingPence`required	`integer`	Integer pence (GBP). Across bank, cash and card accounts at the end of the month.
`inPence`required	`integer`	Integer pence (GBP).
`outPence`required	`integer`	Integer pence (GBP).
`netPence`required	`integer`	Integer pence (GBP).
`closingPence`required	`integer`	Integer pence (GBP).

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

Get SA103 totals (sole traders)

GET/api/v1/books/reports/sa103

Scopes: books:read

The income and expense boxes of HMRC’s SA103F (boxes 15 to 31 and 32 to 46, net profit or loss in 47 or 48), added up from each account’s SA103 line on the chart. An aid for the return, never a filing. The balance sheet boxes aren’t included. 422 unless the business is a sole trader. Anyone who can read the books: the business’s own people (including view-only) and a linked practice. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/books/reports/sa103
Name	In	Type	Description
`taxYear`	query	`integer`	By the year it starts: 2026 is 2026/27. Defaults to the current tax year. 2024 to 2100

Responses

200 OK, `application/json`

Body: object (BooksSa103Totals).

The income and expense boxes of HMRC’s SA103F for a sole trader, added up from the chart. An aid for the return, never a filing.

200 OK response for GET /api/v1/books/reports/sa103
Field	Type	Description
`from`required	`string (date)`	example "2026-03-31"
`to`required	`string (date)`	example "2026-03-31"
`taxYear`required	`integer`	The tax year, by the year it starts: 2026 is 2026/27.
`taxYearLabel`required	`string`
`source`required	`string`	The HMRC form the box numbers come from.
`income`required	`array of BooksSa103IncomeBox`
`income[].box`required	`integer`
`income[].label`required	`string`
`income[].amountPence`required	`integer`	Integer pence (GBP).
`income[].accounts`required	`array of BooksSa103Account`
`income[].accounts[].code`required	`string`
`income[].accounts[].name`required	`string`
`income[].accounts[].amountPence`required	`integer`	Integer pence (GBP).
`income[].accounts[].drillKey`required	`string`	Pass to the drill-down (report profit-and-loss) to list the entries.
`expenses`required	`array of BooksSa103ExpenseBox`
`expenses[].box`required	`integer`
`expenses[].label`required	`string`
`expenses[].amountPence`required	`integer`	Integer pence (GBP).
`expenses[].accounts`required	`array of BooksSa103Account`
`expenses[].accounts[].code`required	`string`
`expenses[].accounts[].name`required	`string`
`expenses[].accounts[].amountPence`required	`integer`	Integer pence (GBP).
`expenses[].accounts[].drillKey`required	`string`	Pass to the drill-down (report profit-and-loss) to list the entries.
`expenses[].disallowableBox`required	`integer`
`expenses[].disallowablePence`required	`integer`	Integer pence (GBP). The part of this box tax doesn’t allow.
`totalExpensesBox`required	`integer`
`totalExpensesPence`required	`integer`	Integer pence (GBP).
`totalDisallowableBox`required	`integer`
`totalDisallowablePence`required	`integer`	Integer pence (GBP).
`netProfitBox`required	`integer`
`netLossBox`required	`integer`
`netPence`required	`integer`	Integer pence (GBP). Income less expenses; negative is a loss.
`netPounds`required	`integer`	The net figure in whole pounds, rounded down, without a sign.
`notTrading`required	`array of BooksSa103Account`	Income left out: it goes on SA100.
`notTrading[].code`required	`string`
`notTrading[].name`required	`string`
`notTrading[].amountPence`required	`integer`	Integer pence (GBP).
`notTrading[].drillKey`required	`string`	Pass to the drill-down (report profit-and-loss) to list the entries.
`unmapped`required	`array of BooksSa103Account`	Income or cost accounts with no SA103 line.
`unmapped[].code`required	`string`
`unmapped[].name`required	`string`
`unmapped[].amountPence`required	`integer`	Integer pence (GBP).
`unmapped[].drillKey`required	`string`	Pass to the drill-down (report profit-and-loss) to list the entries.

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

List the entries behind a report figure

GET/api/v1/books/reports/drill-down

Scopes: books:read

The postings that make up one figure, adding up to it. 422 for a figure that isn’t in the report. Anyone who can read the books: the business’s own people (including view-only) and a linked practice. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/books/reports/drill-down
Name	In	Type	Description
`asAt`	query	`string (date)`	Balance sheet: the date (defaults to today); lines run from the year start.
`to`	query	`string (date)`	Profit and loss: the period end (defaults to today).
`from`	query	`string (date)`	Profit and loss: the period start (defaults to the year start).
`key`required	query	`string`	A figure’s drillKey, e.g. account:6100, section:overheads, category:premises, total:net_profit. up to 80 characters
`report`required	query	`string`	One of: `profit-and-loss`, `balance-sheet`

Responses

200 OK, `application/json`

Body: object (BooksDrillDown).

The postings behind one report figure. Lines are in the figure’s sense (sense), so they add up to it; a balance sheet figure starts from the balance brought forward at the start of the year (including earlier years’ profit in reserves).

200 OK response for GET /api/v1/books/reports/drill-down
Field	Type	Description
`report`required	`string (BooksDrillReport)`	One of: `profit-and-loss`, `balance-sheet`
`key`required	`string`
`label`required	`string`
`from`required	`string (date)`	example "2026-03-31"
`to`required	`string (date)`	example "2026-03-31"
`sense`required	`string (BooksNormalBalance)`	One of: `debit`, `credit`
`accounts`required	`array of BooksDrillAccount`
`accounts[].accountId`required	`string (uuid)`
`accounts[].code`required	`string`
`accounts[].name`required	`string`
`accounts[].ownerName`required	`string`
`openingPence`required	`integer`	Integer pence (GBP).
`lines`required	`array of BooksDrillLine`
`lines[].entryId`required	`string (uuid)`
`lines[].seq`required	`integer`
`lines[].lineIndex`required	`integer`
`lines[].date`required	`string (date)`	example "2026-03-31"
`lines[].kind`required	`string`
`lines[].description`required	`string`
`lines[].accountId`required	`string (uuid)`
`lines[].accountCode`required	`string`
`lines[].amountPence`required	`integer`	Integer pence (GBP). In the figure’s sense, so the lines add up to it.
`lines[].runningPence`required	`integer`	Integer pence (GBP).
`closingPence`required	`integer`	Integer pence (GBP).

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

Estimate the tax to set aside

GET/api/v1/books/reports/tax-estimate

Scopes: books:read

Income tax and Class 4 National Insurance (sole traders) or corporation tax (companies) on the profit so far, annualised. Uses the extra information the owner saved for the tax year (other income, PAYE and pension contributions; a director’s salary and dividends), if any, and says which figures it used. Always an estimate, with its working and assumptions; never a figure for filing. 422 for a partnership or LLP, whose partners are taxed on their shares. Anyone who can read the books: the business’s own people (including view-only) and a linked practice. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/books/reports/tax-estimate
Name	In	Type	Description
`otherIncomePence`	query	`integer`	Sole traders: other non-savings income for the year (a salary, say), in pence, assumed already taxed. When given, it is used instead of the extra information saved for the tax year (PUT /books/tax-details/{taxYear}). at least 0
`asAt`	query	`string (date)`	Defaults to today.

Responses

200 OK, `application/json`

Body: object (BooksTaxEstimate).

An estimate (never a calculation for filing) of the tax to set aside: income tax and Class 4 National Insurance for a sole trader, corporation tax for a company, on the profit so far annualised over the year. Shows its working and what it assumed.

200 OK response for GET /api/v1/books/reports/tax-estimate
Field	Type	Description
`estimate`required	`boolean`	One of: `true`
`kind`required	`string (BooksTaxEstimateKind)`	One of: `sole_trader`, `company`
`periodFrom`required	`string (date)`	example "2026-03-31"
`periodTo`required	`string (date)`	example "2026-03-31"
`asAt`required	`string (date)`	example "2026-03-31"
`daysElapsed`required	`integer`
`daysInPeriod`required	`integer`
`profitBeforeTaxPence`required	`integer`	Integer pence (GBP).
`addBacks`required	`array of BooksTaxWorkingLine`	Costs tax doesn’t allow, added back.
`addBacks[].accountId`required	`string (uuid)`nullable
`addBacks[].code`required	`string`
`addBacks[].name`required	`string`
`addBacks[].amountPence`required	`integer`	Integer pence (GBP).
`notTrading`required	`array of BooksTaxWorkingLine`	Income that isn’t trading income, taken out (sole traders).
`notTrading[].accountId`required	`string (uuid)`nullable
`notTrading[].code`required	`string`
`notTrading[].name`required	`string`
`notTrading[].amountPence`required	`integer`	Integer pence (GBP).
`profitToDatePence`required	`integer`	Integer pence (GBP). Taxable profit so far, whole pounds (floored).
`annualisedProfitPence`required	`integer`	Integer pence (GBP). For the whole year at the same rate, whole pounds (floored).
`taxYearLabel`required	`string`nullable	example "2026/27"
`financialYears`required	`array of integer`	Companies: the financial years whose rates were used.
`otherIncomePence`required	`integer`	Integer pence (GBP).
`lines`required	`array of BooksTaxEstimateLine`
`lines[].key`required	`string (BooksTaxEstimateLineKey)`	other_income_tax: a sole trader’s tax on their other income less what PAYE took (only when they entered other income). One of: `income_tax`, `other_income_tax`, `class4_nic`, `corporation_tax`
`lines[].label`required	`string`
`lines[].annualPence`required	`integer`	Integer pence (GBP). For the whole year, if profit carries on at the same rate.
`lines[].toDatePence`required	`integer`	Integer pence (GBP). The share to have set aside by now.
`annualTaxPence`required	`integer`	Integer pence (GBP).
`setAsideToDatePence`required	`integer`	Integer pence (GBP).
`effectiveRateBps`required	`integer`	Annual tax as a share of annualised profit, basis points.
`assumptions`required	`array of string`
`extraInfoTaxYear`required	`integer`	The tax year the owner’s extra information is for (starting year): the one containing the year end. Use it with /books/tax-details/{taxYear}.
`extraInfoTaxYearLabel`required	`string`	example "2026/27"
`basedOn`required	`object (BooksTaxEstimateBasedOn)`nullable	The owner’s extra information used, or null when none was entered.
`basedOn.otherIncome`required	`integer`	Sole traders: employment, pensions, property profits and savings interest added up.
`basedOn.taxPaidThroughPaye`required	`integer`	Sole traders: tax already taken under PAYE.
`basedOn.pensionContributions`required	`integer`	Sole traders: personal pension contributions paid in.
`basedOn.directorSalary`required	`integer`	Companies: the director’s planned salary.
`basedOn.dividends`required	`integer`	Companies: the director’s planned dividends.
`ownerDividendTax`required	`object (BooksOwnerDividendTax)`nullable	Companies with planned dividends: the director’s own tax on them.
`ownerDividendTax.taxYear`required	`integer`
`ownerDividendTax.taxYearLabel`required	`string`	example "2026/27"
`ownerDividendTax.directorSalary`required	`integer`
`ownerDividendTax.dividends`required	`integer`
`ownerDividendTax.dividendTax`required	`integer`	Income tax on the dividends, after the salary uses the personal allowance and bands first.
`ownerDividendTax.assumptions`required	`array of string`

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

Download a report as CSV or PDF

GET/api/v1/books/reports/{report}/export

Scopes: books:read

The same figures as the report (same query parameters), as a CSV (RFC 4180; amounts in pounds with two decimals, minus for negatives) or an A4 PDF (credits in brackets). Anyone who can read the books: the business’s own people (including view-only) and a linked practice. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/books/reports/{report}/export
Name	In	Type	Description
`report`required	path	`string`	One of: `profit-and-loss`, `balance-sheet`, `aged-debtors`, `aged-creditors`, `vat`, `drill-down`, `cash-flow`, `sa103`
`drillReport`	query	`string`	drill-down only: profit-and-loss or balance-sheet. One of: `profit-and-loss`, `balance-sheet`
`key`	query	`string`	drill-down only: the figure’s drillKey. up to 80 characters
`taxYear`	query	`integer`	sa103 only: the year the tax year starts.
`compareAsAt`	query	`string (date)`
`compareTo`	query	`string (date)`
`compareFrom`	query	`string (date)`
`compare`	query	`string`	previous_year (default), previous_period or none. Ignored when explicit comparison dates are given. One of: `previous_year`, `previous_period`, `none`
`asAt`	query	`string (date)`
`to`	query	`string (date)`
`from`	query	`string (date)`
`format`required	query	`string`	One of: `csv`, `pdf`

Responses

200 OK, `text/csv`

The file, as an attachment.

Body: string (binary).

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

Get the home screen figures

GET/api/v1/books/home

Scopes: books:read

How the business is doing (money in and out this month, profit so far this year, cash across accounts, who owes it and whom it owes, VAT owed), the tax to set aside (an estimate) and what needs the owner. Anyone who can read the books: the business’s own people (including view-only) and a linked practice. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/books/home
Name	In	Type	Description
`asAt`	query	`string (date)`	Defaults to today.

Responses

200 OK, `application/json`

Body: object (BooksHome).

The owner’s home screen: money in and out this month, profit so far this year, cash across accounts, who owes the business and whom it owes, VAT owed, the tax to set aside (an estimate) and what needs the owner.

200 OK response for GET /api/v1/books/home
Field	Type	Description
`asAt`required	`string (date)`	example "2026-03-31"
`businessName`required	`string`
`yearStart`required	`string (date)`	example "2026-03-31"
`yearEnd`required	`string (date)`	example "2026-03-31"
`thisMonth`required	`object (BooksMoneyInOut)`	Money in and out of bank, cash and card accounts; moves between the business’s own accounts are neither.
`thisMonth.from`required	`string (date)`	example "2026-03-31"
`thisMonth.to`required	`string (date)`	example "2026-03-31"
`thisMonth.inPence`required	`integer`	Integer pence (GBP).
`thisMonth.outPence`required	`integer`	Integer pence (GBP).
`lastMonth`required	`object (BooksMoneyInOut)`	Money in and out of bank, cash and card accounts; moves between the business’s own accounts are neither.
`lastMonth.from`required	`string (date)`	example "2026-03-31"
`lastMonth.to`required	`string (date)`	example "2026-03-31"
`lastMonth.inPence`required	`integer`	Integer pence (GBP).
`lastMonth.outPence`required	`integer`	Integer pence (GBP).
`profit`required	`object (BooksHomeProfit)`	Profit for the year so far, with the same stretch of last year when the books go back that far.
`profit.from`required	`string (date)`	example "2026-03-31"
`profit.to`required	`string (date)`	example "2026-03-31"
`profit.profitPence`required	`integer`	Integer pence (GBP).
`profit.moneyInPence`required	`integer`	Integer pence (GBP).
`profit.costsPence`required	`integer`	Integer pence (GBP).
`profit.compareFrom`required	`string (date)`nullable	example "2026-03-31"
`profit.compareTo`required	`string (date)`nullable	example "2026-03-31"
`profit.comparePence`required	`integer`nullable	Integer pence (GBP).
`cash`required	`object (BooksHomeCash)`
`cash.totalPence`required	`integer`	Integer pence (GBP).
`cash.accounts`required	`array of BooksCashAccount`
`cash.accounts[].accountId`required	`string (uuid)`
`cash.accounts[].code`required	`string`
`cash.accounts[].name`required	`string`
`cash.accounts[].ownerName`required	`string`
`cash.accounts[].kind`required	`string (BooksCashAccountKind)`	One of: `bank`, `cash`, `credit_card`
`cash.accounts[].balancePence`required	`integer`	Integer pence (GBP). Debit positive: money held is positive, a card balance owed negative.
`owedToYou`required	`object (BooksHomeOwed)`
`owedToYou.totalPence`required	`integer`	Integer pence (GBP).
`owedToYou.overduePence`required	`integer`	Integer pence (GBP).
`owedToYou.contacts`required	`integer`	Customers (or suppliers) with something outstanding.
`owedToYou.basis`required	`string (BooksAgedBasis)`	One of: `documents`, `ledger`
`youOwe`required	`object (BooksHomeOwed)`
`youOwe.totalPence`required	`integer`	Integer pence (GBP).
`youOwe.overduePence`required	`integer`	Integer pence (GBP).
`youOwe.contacts`required	`integer`	Customers (or suppliers) with something outstanding.
`youOwe.basis`required	`string (BooksAgedBasis)`	One of: `documents`, `ledger`
`vat`required	`object (BooksHomeVat)`
`vat.registered`required	`boolean`
`vat.owedPence`required	`integer`	Integer pence (GBP). The VAT control account: owed to HMRC is positive.
`tax`required	`object (BooksTaxEstimate)`nullable	Null for partnerships and LLPs (each partner is taxed on their share).
`tax.estimate`required	`boolean`	One of: `true`
`tax.kind`required	`string (BooksTaxEstimateKind)`	One of: `sole_trader`, `company`
`tax.periodFrom`required	`string (date)`	example "2026-03-31"
`tax.periodTo`required	`string (date)`	example "2026-03-31"
`tax.asAt`required	`string (date)`	example "2026-03-31"
`tax.daysElapsed`required	`integer`
`tax.daysInPeriod`required	`integer`
`tax.profitBeforeTaxPence`required	`integer`	Integer pence (GBP).
`tax.addBacks`required	`array of BooksTaxWorkingLine`	Costs tax doesn’t allow, added back.
`tax.addBacks[].accountId`required	`string (uuid)`nullable
`tax.addBacks[].code`required	`string`
`tax.addBacks[].name`required	`string`
`tax.addBacks[].amountPence`required	`integer`	Integer pence (GBP).
`tax.notTrading`required	`array of BooksTaxWorkingLine`	Income that isn’t trading income, taken out (sole traders).
`tax.notTrading[].accountId`required	`string (uuid)`nullable
`tax.notTrading[].code`required	`string`
`tax.notTrading[].name`required	`string`
`tax.notTrading[].amountPence`required	`integer`	Integer pence (GBP).
`tax.profitToDatePence`required	`integer`	Integer pence (GBP). Taxable profit so far, whole pounds (floored).
`tax.annualisedProfitPence`required	`integer`	Integer pence (GBP). For the whole year at the same rate, whole pounds (floored).
`tax.taxYearLabel`required	`string`nullable	example "2026/27"
`tax.financialYears`required	`array of integer`	Companies: the financial years whose rates were used.
`tax.otherIncomePence`required	`integer`	Integer pence (GBP).
`tax.lines`required	`array of BooksTaxEstimateLine`
`tax.lines[].key`required	`string (BooksTaxEstimateLineKey)`	other_income_tax: a sole trader’s tax on their other income less what PAYE took (only when they entered other income). One of: `income_tax`, `other_income_tax`, `class4_nic`, `corporation_tax`
`tax.lines[].label`required	`string`
`tax.lines[].annualPence`required	`integer`	Integer pence (GBP). For the whole year, if profit carries on at the same rate.
`tax.lines[].toDatePence`required	`integer`	Integer pence (GBP). The share to have set aside by now.
`tax.annualTaxPence`required	`integer`	Integer pence (GBP).
`tax.setAsideToDatePence`required	`integer`	Integer pence (GBP).
`tax.effectiveRateBps`required	`integer`	Annual tax as a share of annualised profit, basis points.
`tax.assumptions`required	`array of string`
`tax.extraInfoTaxYear`required	`integer`	The tax year the owner’s extra information is for (starting year): the one containing the year end. Use it with /books/tax-details/{taxYear}.
`tax.extraInfoTaxYearLabel`required	`string`	example "2026/27"
`tax.basedOn`required	`object (BooksTaxEstimateBasedOn)`nullable	The owner’s extra information used, or null when none was entered.
`tax.basedOn.otherIncome`required	`integer`	Sole traders: employment, pensions, property profits and savings interest added up.
`tax.basedOn.taxPaidThroughPaye`required	`integer`	Sole traders: tax already taken under PAYE.
`tax.basedOn.pensionContributions`required	`integer`	Sole traders: personal pension contributions paid in.
`tax.basedOn.directorSalary`required	`integer`	Companies: the director’s planned salary.
`tax.basedOn.dividends`required	`integer`	Companies: the director’s planned dividends.
`tax.ownerDividendTax`required	`object (BooksOwnerDividendTax)`nullable	Companies with planned dividends: the director’s own tax on them.
`tax.ownerDividendTax.taxYear`required	`integer`
`tax.ownerDividendTax.taxYearLabel`required	`string`	example "2026/27"
`tax.ownerDividendTax.directorSalary`required	`integer`
`tax.ownerDividendTax.dividends`required	`integer`
`tax.ownerDividendTax.dividendTax`required	`integer`	Income tax on the dividends, after the salary uses the personal allowance and bands first.
`tax.ownerDividendTax.assumptions`required	`array of string`
`taxUnavailable`required	`string`nullable	Why there is no estimate, in plain words.
`needsYou`required	`array of BooksNeedsYou`
`needsYou[].key`required	`string (BooksNeedsYouKey)`	invoices appears only when a repeating invoice has made drafts to check. One of: `inbox`, `receipts`, `vat`, `invoices`
`needsYou[].label`required	`string`
`needsYou[].count`required	`integer`nullable	Null when Tolvi can’t count it yet.
`needsYou[].detail`required	`string`nullable
`monthSentence`required	`object (BooksMonthSentence)`	"This month in a sentence": worked out from the figures with fixed wording, not written by AI.
`monthSentence.text`required	`string`
`monthSentence.parts`required	`array of BooksMonthSentencePart`
`monthSentence.parts[].text`required	`string`
`monthSentence.parts[].linked`required	`boolean`	A figure to link to the profit and loss for the period.
`monthSentence.from`required	`string (date)`	example "2026-03-31"
`monthSentence.to`required	`string (date)`	example "2026-03-31"
`monthSentence.hasFigures`required	`boolean`	False when nothing is in the books for the period.

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

Get the extra information for the tax estimate

GET/api/v1/books/tax-details/{taxYear}

Scopes: books:read

What the owner entered for a more accurate tax to set aside, for one tax year; every figure is nil when nothing was entered. Anyone who can read the books: the business’s own people (including view-only) and a linked practice. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/books/tax-details/{taxYear}
Name	In	Type	Description
`taxYear`required	path	`integer`	The tax year’s starting year (2026 = 2026/27). The tax estimate gives the year it uses as `extraInfoTaxYear`. 2000 to 2100

Responses

200 OK, `application/json`

Body: object (BooksTaxDetails).

Extra information the owner gave for a more accurate tax to set aside, for one tax year. All figures are optional (nil when not entered) and only ever used for the estimate.

200 OK response for GET /api/v1/books/tax-details/{taxYear}
Field	Type	Description
`taxYear`required	`integer`	The tax year’s starting year (2026 = 2026/27).
`taxYearLabel`required	`string`	example "2026/27"
`employmentIncomePence`required	`integer`	Integer pence (GBP). Sole traders. Pay from a job, before tax.
`employmentTaxPaidPence`required	`integer`	Integer pence (GBP). Sole traders. Tax taken from that pay under PAYE.
`pensionIncomePence`required	`integer`	Integer pence (GBP). Sole traders. State and private pensions received, before tax.
`pensionTaxPaidPence`required	`integer`	Integer pence (GBP). Sole traders. Tax taken from pensions under PAYE.
`propertyIncomePence`required	`integer`	Integer pence (GBP). Sole traders. Profit from letting property.
`savingsInterestPence`required	`integer`	Integer pence (GBP). Sole traders. Interest from savings.
`pensionContributionsPence`required	`integer`	Integer pence (GBP). Sole traders. Personal pension contributions paid in.
`directorSalaryPence`required	`integer`	Integer pence (GBP). Companies: the director’s own figure. Planned salary.
`dividendsPence`required	`integer`	Integer pence (GBP). Companies: the director’s own figure. Planned dividends.
`updatedAt`required	`string (date-time)`nullable	When it was last saved; null when nothing has been entered.

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

Save the extra information for the tax estimate

PUT/api/v1/books/tax-details/{taxYear}

Scopes: books:write

Replaces the figures for the tax year (anything left out is saved as nil). Only ever used for the estimate on Home; nothing is filed. The business’s people who can change the books, or an accountant whose link lets them (year_end or full_bookkeeping). View-only people and read-only links get 403. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for PUT /api/v1/books/tax-details/{taxYear}
Name	In	Type	Description
`taxYear`required	path	`integer`	The tax year’s starting year (2026 = 2026/27). The tax estimate gives the year it uses as `extraInfoTaxYear`. 2000 to 2100

Request body

Required. application/json: object (BooksTaxDetailsUpdate).

Replaces the extra information for the tax year. A figure left out is saved as nil.

Request body for PUT /api/v1/books/tax-details/{taxYear}
Field	Type	Description
`employmentIncomePence`	`integer`	Integer pence (GBP). Sole traders. Pay from a job, before tax. at least 0
`employmentTaxPaidPence`	`integer`	Integer pence (GBP). Sole traders. Tax taken from that pay under PAYE. at least 0
`pensionIncomePence`	`integer`	Integer pence (GBP). Sole traders. State and private pensions received, before tax. at least 0
`pensionTaxPaidPence`	`integer`	Integer pence (GBP). Sole traders. Tax taken from pensions under PAYE. at least 0
`propertyIncomePence`	`integer`	Integer pence (GBP). Sole traders. Profit from letting property. at least 0
`savingsInterestPence`	`integer`	Integer pence (GBP). Sole traders. Interest from savings. at least 0
`pensionContributionsPence`	`integer`	Integer pence (GBP). Sole traders. Personal pension contributions paid in (relief at source); Tolvi adds basic rate relief. at least 0
`directorSalaryPence`	`integer`	Integer pence (GBP). Companies: the director’s own figure. Planned salary for the tax year. at least 0
`dividendsPence`	`integer`	Integer pence (GBP). Companies: the director’s own figure. Planned dividends for the tax year. at least 0

Responses

200 OK, `application/json`

Body: object (BooksTaxDetails).

Extra information the owner gave for a more accurate tax to set aside, for one tax year. All figures are optional (nil when not entered) and only ever used for the estimate.

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

Get VAT at a glance

GET/api/v1/books/vat/summary

Scopes: books:read

The next return and its deadline, what is owed (or due back) so far, the HMRC connection, whether filing from Tolvi is switched on, and anything that needs attention. Part of the books product: the firm must have it and you must have access to it.

Responses

200 OK, `application/json`

Body: object (BooksVatSummary).

VAT at a glance: the next deadline, what is owed so far, and anything that needs attention.

200 OK response for GET /api/v1/books/vat/summary
Field	Type	Description
`registered`required	`boolean`
`configured`required	`boolean`
`scheme`required	`string (VatScheme)`nullable	One of: `standard`, `cash_accounting`, `flat_rate`, `annual_accounting`
`connection`required	`object (BooksHmrcConnection)`	Tolvi’s authority to file VAT returns for the business at HMRC.
`connection.status`required	`string (BooksHmrcConnectionStatus)`	One of: `connected`, `needs_reconnect`, `disconnected`, `not_connected`, `not_available`
`connection.environment`required	`string`nullable	sandbox, production, custom, or fake (development).
`connection.connectedAt`required	`string (date-time)`nullable
`connection.grantExpiresAt`required	`string (date-time)`nullable	HMRC’s authority lasts 18 months, then you connect again.
`connection.reconnectSoon`required	`boolean`
`connection.message`required	`string`
`submissionEnabled`required	`boolean`	Whether returns can be sent to HMRC from this Tolvi (switched on once HMRC approves Tolvi).
`submissionMessage`required	`string`nullable
`next`required	`object (BooksVatNextReturn)`nullable
`next.periodKey`required	`string`
`next.start`required	`string (date)`	example "2026-03-31"
`next.end`required	`string (date)`	example "2026-03-31"
`next.due`required	`string (date)`	example "2026-03-31"
`next.source`required	`string (BooksVatObligationSource)`	One of: `hmrc`, `expected`
`next.status`required	`string (BooksVatPeriodStatus)`	One of: `open`, `filed`, `overdue`, `not_ended`
`next.received`required	`string (date)`nullable	example "2026-03-31"
`next.box5`required	`integer`	What is owed (or due back) so far, in pence.
`next.direction`required	`string (BooksVatDirection)`	One of: `pay`, `repay`, `nil`
`lastFiled`required	`object (BooksVatSubmission)`nullable	A return sent to HMRC, with HMRC’s receipt once accepted. The figures never change.
`lastFiled.id`required	`string (uuid)`
`lastFiled.periodKey`required	`string`	example "26AC"
`lastFiled.start`required	`string (date)`	example "2026-03-31"
`lastFiled.end`required	`string (date)`	example "2026-03-31"
`lastFiled.due`required	`string (date)`nullable	example "2026-03-31"
`lastFiled.status`required	`string (BooksVatSubmissionStatus)`	pending (being sent), accepted, rejected, or unknown (no answer from HMRC: Tolvi checks with HMRC before trying again). One of: `pending`, `accepted`, `rejected`, `unknown`
`lastFiled.boxes`required	`object (BooksVatBoxes)`	The nine boxes in pence. Boxes 6 to 9 are whole pounds (123400 is £1,234). Box 5 is never negative: see `direction`.
`lastFiled.boxes.box1`required	`integer`
`lastFiled.boxes.box2`required	`integer`
`lastFiled.boxes.box3`required	`integer`
`lastFiled.boxes.box4`required	`integer`
`lastFiled.boxes.box5`required	`integer`
`lastFiled.boxes.box6`required	`integer`
`lastFiled.boxes.box7`required	`integer`
`lastFiled.boxes.box8`required	`integer`
`lastFiled.boxes.box9`required	`integer`
`lastFiled.direction`required	`string (BooksVatDirection)`	One of: `pay`, `repay`, `nil`
`lastFiled.declaredAt`required	`string (date-time)`
`lastFiled.declaredByName`required	`string`nullable
`lastFiled.asAgent`required	`boolean`	Filed by an accountant for the business.
`lastFiled.processingDate`required	`string (date-time)`nullable
`lastFiled.formBundleNumber`required	`string`nullable	example "123456789012"
`lastFiled.paymentIndicator`required	`string`nullable	DD: HMRC collects by Direct Debit. BANK: HMRC repays to the bank account it holds.
`lastFiled.chargeRefNumber`required	`string`nullable
`lastFiled.errorMessage`required	`string`nullable
`problems`required	`array of BooksVatProblem`
`problems[].code`required	`string`
`problems[].severity`required	`string (BooksVatFindingSeverity)`	One of: `check`, `info`
`problems[].message`required	`string`

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

Get the VAT settings

GET/api/v1/books/vat/settings

Scopes: books:read

The VAT number, return periods (stagger), registration date and the schemes over time, with the flat rate business types. Part of the books product: the firm must have it and you must have access to it.

Responses

200 OK, `application/json`

Body: object (BooksVatSettings).

The business’s VAT registration, return periods and schemes.

200 OK response for GET /api/v1/books/vat/settings
Field	Type	Description
`registered`required	`boolean`
`configured`required	`boolean`	False until VAT settings are saved (the return periods are then a guess).
`vrn`required	`string`nullable
`stagger`required	`string (BooksVatStagger)`	One of: `stagger_1`, `stagger_2`, `stagger_3`, `monthly`, `annual`
`staggerLabel`required	`string`
`annualEndMonth`required	`integer`nullable
`registeredFrom`required	`string (date)`nullable	example "2026-03-31"
`scheme`required	`string (VatScheme)`nullable	One of: `standard`, `cash_accounting`, `flat_rate`, `annual_accounting`
`schemes`required	`array of BooksVatSchemePeriod`
`schemes[].from`required	`string (date)`	example "2026-03-31"
`schemes[].to`required	`string (date)`nullable	example "2026-03-31"
`schemes[].accounting`required	`string (BooksVatAccounting)`	One of: `accrual`, `cash`
`schemes[].flatRateSector`required	`string`nullable
`schemes[].flatRateSectorLabel`required	`string`nullable
`schemes[].flatRatePercentBps`required	`integer`nullable	The flat rate percentage in basis points today (the sector’s, less 1% in the first year).
`schemes[].firstYearDiscount`required	`boolean`
`schemes[].annualAccounting`required	`boolean`
`filedTo`required	`string (date)`nullable	Returns are filed up to this date: earlier scheme stretches can’t change. example "2026-03-31"
`flatRateSectors`required	`array of BooksVatFlatRateSectorOption`
`flatRateSectors[].key`required	`string`
`flatRateSectors[].label`required	`string`
`flatRateSectors[].percentBps`required	`integer`

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

Change the VAT settings

PUT/api/v1/books/vat/settings

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

The business’s owners and admins, signed in. The VAT number’s check digits are checked. A change of scheme (cash accounting, flat rate, annual accounting) starts a new stretch from schemeFrom; nothing a filed return covers can change. Part of the books product: the firm must have it and you must have access to it.

Request body

Required. application/json: object (BooksUpdateVatSettings).

The business’s VAT registration and scheme. Changing the scheme starts a new stretch from schemeFrom; stretches covering a filed return never change.

Request body for PUT /api/v1/books/vat/settings
Field	Type	Description
`vrn`required	`string`	The 9-digit VAT registration number, with or without GB. Its check digits are checked. example "123456782"
`stagger`required	`string (BooksVatStagger)`	One of: `stagger_1`, `stagger_2`, `stagger_3`, `monthly`, `annual`
`annualEndMonth`	`integer`nullable	Annual accounting: the month the VAT year ends.
`registeredFrom`required	`string (date)`	The effective date of registration. example "2026-03-31"
`accounting`required	`string (BooksVatAccounting)`	accrual (invoice dates) or cash (when money moves, Notice 731). One of: `accrual`, `cash`
`flatRate`	`object (BooksVatFlatRateChoice)`nullable	The flat rate scheme; leave it out (or null) when not on it.
`flatRate.sector`required	`string (BooksVatFlatRateSector)`	One of: `accountancy-or-book-keeping`, `advertising`, `agricultural-services`, `any-other-activity`, `architect-engineer-or-surveyor`, `boarding-or-care-of-animals`, `business-services`, `catering`, `computer-and-it-consultancy`, `computer-repair`, `entertainment-or-journalism`, `estate-agency-or-property-management`, `farming-or-agriculture`, `film-radio-tv-or-video-production`, `financial-services`, `forestry-or-fishing`, `general-building-or-construction`, `hairdressing-or-beauty`, `hiring-or-renting-goods`, `hotel-or-accommodation`, `investigation-or-security`, `labour-only-building-or-construction`, `laundry-or-dry-cleaning`, `lawyer-or-legal-services`, `library-archive-museum-or-cultural`, `management-consultancy`, `manufacturing-fabricated-metal-products`, `manufacturing-food`, `manufacturing-other`, `manufacturing-yarn-textiles-or-clothing`, `membership-organisation`, `mining-or-quarrying`, `packaging`, `photography`, `post-offices`, `printing`, `publishing`, `pubs`, `real-estate-other`, `repairing-personal-or-household-goods`, `repairing-vehicles`, `retailing-food-confectionery-tobacco-newspapers-childrens-clothing`, `retailing-pharmaceuticals-medical-cosmetics-toiletries`, `retailing-other`, `retailing-vehicles-or-fuel`, `secretarial-services`, `social-work`, `sport-or-recreation`, `transport-or-storage`, `travel-agency`, `veterinary-medicine`, `wholesaling-agricultural-products`, `wholesaling-food`, `wholesaling-other`
`flatRate.firstYearDiscount`required	`boolean`	The 1% reduction in the first year of VAT registration (Notice 733 para 4.7).
`annualAccounting`	`boolean`
`schemeFrom`	`string (date)`	example "2026-03-31"

Responses

200 OK, `application/json`

Body: object (BooksVatSettings).

The business’s VAT registration, return periods and schemes.

The fields are as shown above.

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

List the VAT periods

GET/api/v1/books/vat/obligations

Scopes: books:read

HMRC’s obligations as last fetched; before Tolvi is connected to HMRC, the periods expected from the return periods. Part of the books product: the firm must have it and you must have access to it.

Responses

200 OK, `application/json`

Body: object (BooksVatPeriods).

200 OK response for GET /api/v1/books/vat/obligations
Field	Type	Description
`periods`required	`array of BooksVatPeriod`
`periods[].periodKey`required	`string`
`periods[].start`required	`string (date)`	example "2026-03-31"
`periods[].end`required	`string (date)`	example "2026-03-31"
`periods[].due`required	`string (date)`	example "2026-03-31"
`periods[].source`required	`string (BooksVatObligationSource)`	One of: `hmrc`, `expected`
`periods[].status`required	`string (BooksVatPeriodStatus)`	One of: `open`, `filed`, `overdue`, `not_ended`
`periods[].received`required	`string (date)`nullable	example "2026-03-31"
`fetchedAt`required	`string (date-time)`nullable	When HMRC was last asked (null: never, the periods are expected ones).

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

Get a VAT return

GET/api/v1/books/vat/returns/{periodKey}

Scopes: books:read

Worked out from the books now, with Tolvi’s own checks and the latest check before filing; once filed, the figures HMRC accepted and its receipt. returnHash identifies these exact figures. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/books/vat/returns/{periodKey}
Name	In	Type	Description
`periodKey`required	path	`string`	HMRC’s period key (4 characters; `#` written as %23). example "26AC"

Responses

200 OK, `application/json`

Body: object (BooksVatReturn).

A VAT return for one period: worked out from the books until it is filed, then the figures HMRC accepted.

200 OK response for GET /api/v1/books/vat/returns/{periodKey}
Field	Type	Description
`periodKey`required	`string`	example "26AC"
`start`required	`string (date)`	example "2026-03-31"
`end`required	`string (date)`	example "2026-03-31"
`due`required	`string (date)`nullable	example "2026-03-31"
`source`required	`string (BooksVatPeriodSource)`	hmrc (an obligation), filed, or expected (from the return periods; not connected to HMRC yet). One of: `hmrc`, `filed`, `expected`
`status`required	`string (BooksVatReturnStatus)`	One of: `open`, `filed`, `not_ended`, `sending`
`boxes`required	`object (BooksVatBoxes)`	The nine boxes in pence. Boxes 6 to 9 are whole pounds (123400 is £1,234). Box 5 is never negative: see `direction`.
`boxes.box1`required	`integer`
`boxes.box2`required	`integer`
`boxes.box3`required	`integer`
`boxes.box4`required	`integer`
`boxes.box5`required	`integer`
`boxes.box6`required	`integer`
`boxes.box7`required	`integer`
`boxes.box8`required	`integer`
`boxes.box9`required	`integer`
`direction`required	`string (BooksVatDirection)`	One of: `pay`, `repay`, `nil`
`boxesInPence`required	`object (BooksVatBoxesInPence)`
`boxesInPence.box6`required	`integer`
`boxesInPence.box7`required	`integer`
`boxesInPence.box8`required	`integer`
`boxesInPence.box9`required	`integer`
`lineCount`required	`integer`
`lateCount`required	`integer`	Payments brought in from a period already filed (cash accounting).
`flatRate`required	`object (BooksVatFlatRateSummary)`nullable
`flatRate.turnoverGrossPence`required	`integer`	Integer pence (GBP).
`flatRate.limitedCost`required	`boolean`
`flatRate.explanation`required	`string`
`flatRate.buckets`required	`array of BooksVatFlatRateBucket`
`flatRate.buckets[].bps`required	`integer`
`flatRate.buckets[].turnoverGrossPence`required	`integer`	Integer pence (GBP).
`flatRate.buckets[].vatPence`required	`integer`	Integer pence (GBP).
`flatRate.buckets[].firstYearReduction`required	`boolean`
`findings`required	`array of BooksVatFinding`	Tolvi’s own checks (no AI).
`findings[].kind`required	`string`	example "missing_receipt"
`findings[].severity`required	`string (BooksVatFindingSeverity)`	One of: `check`, `info`
`findings[].title`required	`string`
`findings[].detail`required	`string`
`findings[].box`required	`integer`nullable
`findings[].lineRefs`required	`array of string`	The lines it is about, as `seq:lineIndex`.
`errorNotification`required	`object (BooksVatErrorNotification)`nullable	Corrections to earlier returns over the Notice 700/45 limit. They are not on this return: the business must tell HMRC separately (form VAT652).
`errorNotification.netErrorPence`required	`integer`	What the corrections do to box 5, in pence: positive is more owed to HMRC.
`errorNotification.limitPence`required	`integer`	The limit for this return, in pence.
`errorNotification.box6Pence`required	`integer`	Integer pence (GBP).
`errorNotification.message`required	`string`
`errorNotification.source`required	`string`	The legislation or HMRC notice.
`errorNotification.lineRefs`required	`array of string`
`takenBackCount`required	`integer`	Payments undone after an earlier return included them, taken back on this one.
`returnHash`required	`string`	Send it back when filing: the figures filed are the ones reviewed.
`check`required	`object (BooksVatCheck)`nullable	The check before filing: Tolvi’s own checks and Tolvi AI’s suggestions. It never changes the return.
`check.id`required	`string (uuid)`
`check.createdAt`required	`string (date-time)`
`check.returnHash`required	`string`
`check.current`required	`boolean`
`check.summary`required	`string`
`check.findings`required	`array of BooksVatFinding`
`check.findings[].kind`required	`string`	example "missing_receipt"
`check.findings[].severity`required	`string (BooksVatFindingSeverity)`	One of: `check`, `info`
`check.findings[].title`required	`string`
`check.findings[].detail`required	`string`
`check.findings[].box`required	`integer`nullable
`check.findings[].lineRefs`required	`array of string`	The lines it is about, as `seq:lineIndex`.
`check.ai`required	`boolean`
`submission`required	`object (BooksVatSubmission)`nullable	A return sent to HMRC, with HMRC’s receipt once accepted. The figures never change.
`submission.id`required	`string (uuid)`
`submission.periodKey`required	`string`	example "26AC"
`submission.start`required	`string (date)`	example "2026-03-31"
`submission.end`required	`string (date)`	example "2026-03-31"
`submission.due`required	`string (date)`nullable	example "2026-03-31"
`submission.status`required	`string (BooksVatSubmissionStatus)`	pending (being sent), accepted, rejected, or unknown (no answer from HMRC: Tolvi checks with HMRC before trying again). One of: `pending`, `accepted`, `rejected`, `unknown`
`submission.boxes`required	`object (BooksVatBoxes)`	The nine boxes in pence. Boxes 6 to 9 are whole pounds (123400 is £1,234). Box 5 is never negative: see `direction`.
`submission.boxes.box1`required	`integer`
`submission.boxes.box2`required	`integer`
`submission.boxes.box3`required	`integer`
`submission.boxes.box4`required	`integer`
`submission.boxes.box5`required	`integer`
`submission.boxes.box6`required	`integer`
`submission.boxes.box7`required	`integer`
`submission.boxes.box8`required	`integer`
`submission.boxes.box9`required	`integer`
`submission.direction`required	`string (BooksVatDirection)`	One of: `pay`, `repay`, `nil`
`submission.declaredAt`required	`string (date-time)`
`submission.declaredByName`required	`string`nullable
`submission.asAgent`required	`boolean`	Filed by an accountant for the business.
`submission.processingDate`required	`string (date-time)`nullable
`submission.formBundleNumber`required	`string`nullable	example "123456789012"
`submission.paymentIndicator`required	`string`nullable	DD: HMRC collects by Direct Debit. BANK: HMRC repays to the bank account it holds.
`submission.chargeRefNumber`required	`string`nullable
`submission.errorMessage`required	`string`nullable
`canSubmit`required	`boolean`
`cannotSubmitReason`required	`string`nullable
`declaration`required	`object (BooksVatDeclaration)`	The legal declaration to show and accept before filing (HMRC’s wording).
`declaration.version`required	`string`
`declaration.text`required	`string`
`declaration.asAgent`required	`boolean`

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

List the lines behind a VAT return

GET/api/v1/books/vat/returns/{periodKey}/lines

Scopes: books:read

Each line (or payment, under cash accounting) in the return and what it adds to each box, with why. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/books/vat/returns/{periodKey}/lines
Name	In	Type	Description
`periodKey`required	path	`string`	HMRC’s period key (4 characters; `#` written as %23). example "26AC"
`box`	query	`integer`	Only the lines that add to this box (1 to 9). Box 3 shows boxes 1 and 2; box 5 shows 1, 2 and 4. 1 to 9

Responses

200 OK, `application/json`

Body: object (BooksVatReturnLines).

200 OK response for GET /api/v1/books/vat/returns/{periodKey}/lines
Field	Type	Description
`box`required	`integer`nullable
`totalPence`required	`integer`	The box’s total, in pence.
`title`required	`string`
`meaning`required	`string`
`lines`required	`array of BooksVatReturnLine`
`lines[].ref`required	`string`	`seq:lineIndex` example "12:0"
`lines[].lineId`required	`string (uuid)`
`lines[].entryId`required	`string (uuid)`
`lines[].entrySeq`required	`integer`
`lines[].date`required	`string (date)`	example "2026-03-31"
`lines[].taxPoint`required	`string (date)`	example "2026-03-31"
`lines[].accountingDate`required	`string (date)`nullable	The date that put it in this return (the tax point, or when it was paid under cash accounting). example "2026-03-31"
`lines[].description`required	`string`
`lines[].accountCode`required	`string`
`lines[].accountName`required	`string`
`lines[].accountOwnerName`required	`string`
`lines[].vatCodeId`required	`string`
`lines[].side`required	`string (BooksVatSide)`	One of: `sale`, `purchase`
`lines[].netPence`required	`integer`	Integer pence (GBP).
`lines[].vatPence`required	`integer`	Integer pence (GBP).
`lines[].boxes`required	`array of BooksVatBoxAmount`
`lines[].boxes[].box`required	`integer`
`lines[].boxes[].amountPence`required	`integer`	Integer pence (GBP).
`lines[].flatRateTurnoverPence`required	`integer`	Integer pence (GBP).
`lines[].explanation`required	`string`
`lines[].late`required	`boolean`
`lines[].settlementId`required	`string (uuid)`nullable
`lines[].hasReceipt`required	`boolean`

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

Check a VAT return before filing

POST/api/v1/books/vat/returns/{periodKey}/check

Scopes: books:write

Tolvi’s own checks and Tolvi AI’s suggestions: unusual movements, purchases without receipts and reverse charge oddities. Suggestions only: nothing in the return or the books changes. Included in the Books price; not available through MCP. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/vat/returns/{periodKey}/check
Name	In	Type	Description
`periodKey`required	path	`string`	HMRC’s period key (4 characters; `#` written as %23). example "26AC"

Responses

200 OK, `application/json`

Body: object (BooksVatCheck).

The check before filing: Tolvi’s own checks and Tolvi AI’s suggestions. It never changes the return.

200 OK response for POST /api/v1/books/vat/returns/{periodKey}/check
Field	Type	Description
`id`required	`string (uuid)`
`createdAt`required	`string (date-time)`
`returnHash`required	`string`
`current`required	`boolean`
`summary`required	`string`
`findings`required	`array of BooksVatFinding`
`findings[].kind`required	`string`	example "missing_receipt"
`findings[].severity`required	`string (BooksVatFindingSeverity)`	One of: `check`, `info`
`findings[].title`required	`string`
`findings[].detail`required	`string`
`findings[].box`required	`integer`nullable
`findings[].lineRefs`required	`array of string`	The lines it is about, as `seq:lineIndex`.
`ai`required	`boolean`

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

Record telling HMRC about corrections over the limit

POST/api/v1/books/vat/returns/{periodKey}/error-notification

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

Corrections to earlier returns over the VAT Notice 700/45 limit can’t go on a return: the business tells HMRC separately (form VAT652), then records it here so they stay off every return. The business’s owners and admins, or an accountant through a full bookkeeping link (who accepts the agent’s declaration). Signed in only: never an API token, a connected app or MCP. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/vat/returns/{periodKey}/error-notification
Name	In	Type	Description
`periodKey`required	path	`string`	HMRC’s period key (4 characters; `#` written as %23). example "26AC"

Request body

Required. application/json: object (BooksVatRecordErrorNotification).

The business has told HMRC about corrections over the limit: they stay off every return from now on.

Request body for POST /api/v1/books/vat/returns/{periodKey}/error-notification
Field	Type	Description
`notifiedOn`required	`string (date)`	example "2026-03-31"
`reference`	`string`

Responses

200 OK, `application/json`

Body: object (BooksVatReturn).

A VAT return for one period: worked out from the books until it is filed, then the figures HMRC accepted.

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

File a VAT return with HMRC

POST/api/v1/books/vat/returns/{periodKey}/submit

Scopes: books:write
Access: A signed-in Tolvi session only, never an API token.
Retries: Send an Idempotency-Key to make retries safe.

The business’s owners and admins, or an accountant through a full bookkeeping link (who accepts the agent’s declaration). Signed in only: never an API token, a connected app or MCP. The person accepts HMRC’s declaration; returnHash must match the return they reviewed, or 409. A pending record is written before HMRC is called, so a lost answer is checked with HMRC rather than sent twice. When HMRC accepts, the period’s VAT lines lock. Answers 503 while filing from Tolvi is switched off (until HMRC approves Tolvi). Open even while Books is suspended. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/vat/returns/{periodKey}/submit
Name	In	Type	Description
`periodKey`required	path	`string`	HMRC’s period key (4 characters; `#` written as %23). example "26AC"
`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 (BooksSubmitVatReturn).

File the return. The person accepts HMRC’s declaration; returnHash must be the preview’s, so what was reviewed is what is filed.

Request body for POST /api/v1/books/vat/returns/{periodKey}/submit
Field	Type	Description
`returnHash`required	`string`
`declaration`	`object`
`declaration.accepted`required	`boolean`	One of: `true`
`declaration.version`required	`string`
`checkId`	`string (uuid)`
`clientFacts`required	`object (BooksVatClientFacts)`	What the browser knows about itself, for HMRC’s fraud prevention headers (Gov-Client-*). Send it with every request that reaches HMRC.
`clientFacts.deviceId`required	`string (uuid)`	A UUID kept on this device (local storage).
`clientFacts.userAgent`required	`string`	navigator.userAgent
`clientFacts.screens`required	`array of object`
`clientFacts.screens[].width`required	`integer`
`clientFacts.screens[].height`required	`integer`
`clientFacts.screens[].scalingFactor`required	`number`
`clientFacts.screens[].colourDepth`required	`integer`
`clientFacts.windowWidth`required	`integer`
`clientFacts.windowHeight`required	`integer`
`clientFacts.timezone`required	`string`	example "UTC+01:00"
`clientFacts.appVersion`	`string`

Responses

200 OK, `application/json`

Body: object (BooksVatReturn).

A VAT return for one period: worked out from the books until it is filed, then the figures HMRC accepted.

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

List VAT returns sent to HMRC

GET/api/v1/books/vat/submissions

Scopes: books:read

Newest first, with HMRC’s receipts. Part of the books product: the firm must have it and you must have access to it.

Responses

200 OK, `application/json`

Body: object (BooksVatSubmissions).

200 OK response for GET /api/v1/books/vat/submissions
Field	Type	Description
`submissions`required	`array of BooksVatSubmission`
`submissions[].id`required	`string (uuid)`
`submissions[].periodKey`required	`string`	example "26AC"
`submissions[].start`required	`string (date)`	example "2026-03-31"
`submissions[].end`required	`string (date)`	example "2026-03-31"
`submissions[].due`required	`string (date)`nullable	example "2026-03-31"
`submissions[].status`required	`string (BooksVatSubmissionStatus)`	pending (being sent), accepted, rejected, or unknown (no answer from HMRC: Tolvi checks with HMRC before trying again). One of: `pending`, `accepted`, `rejected`, `unknown`
`submissions[].boxes`required	`object (BooksVatBoxes)`	The nine boxes in pence. Boxes 6 to 9 are whole pounds (123400 is £1,234). Box 5 is never negative: see `direction`.
`submissions[].boxes.box1`required	`integer`
`submissions[].boxes.box2`required	`integer`
`submissions[].boxes.box3`required	`integer`
`submissions[].boxes.box4`required	`integer`
`submissions[].boxes.box5`required	`integer`
`submissions[].boxes.box6`required	`integer`
`submissions[].boxes.box7`required	`integer`
`submissions[].boxes.box8`required	`integer`
`submissions[].boxes.box9`required	`integer`
`submissions[].direction`required	`string (BooksVatDirection)`	One of: `pay`, `repay`, `nil`
`submissions[].declaredAt`required	`string (date-time)`
`submissions[].declaredByName`required	`string`nullable
`submissions[].asAgent`required	`boolean`	Filed by an accountant for the business.
`submissions[].processingDate`required	`string (date-time)`nullable
`submissions[].formBundleNumber`required	`string`nullable	example "123456789012"
`submissions[].paymentIndicator`required	`string`nullable	DD: HMRC collects by Direct Debit. BANK: HMRC repays to the bank account it holds.
`submissions[].chargeRefNumber`required	`string`nullable
`submissions[].errorMessage`required	`string`nullable

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

Get VAT owed and paid at HMRC

GET/api/v1/books/vat/payments

Scopes: books:read

HMRC’s liabilities and payments for the last year, as last fetched. Part of the books product: the firm must have it and you must have access to it.

Responses

200 OK, `application/json`

Body: object (BooksVatPaymentsAndLiabilities).

What HMRC says is owed and has been paid, as last fetched.

200 OK response for GET /api/v1/books/vat/payments
Field	Type	Description
`liabilities`required	`array of BooksVatLiability`
`liabilities[].periodStart`required	`string (date)`nullable	example "2026-03-31"
`liabilities[].periodEnd`required	`string (date)`nullable	example "2026-03-31"
`liabilities[].type`required	`string`	example "VAT Return Debit Charge"
`liabilities[].originalAmountPence`required	`integer`	Integer pence (GBP).
`liabilities[].outstandingAmountPence`required	`integer`nullable	Integer pence (GBP).
`liabilities[].due`required	`string (date)`nullable	example "2026-03-31"
`payments`required	`array of BooksVatPayment`
`payments[].amountPence`required	`integer`	Integer pence (GBP).
`payments[].received`required	`string (date)`nullable	example "2026-03-31"
`fetchedAt`required	`string (date-time)`nullable

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

Get the HMRC connection

GET/api/v1/books/vat/hmrc

Scopes: books:read

Whether Tolvi may file for the business at HMRC, and when the authority ends (HMRC’s lasts 18 months). Part of the books product: the firm must have it and you must have access to it.

Responses

200 OK, `application/json`

Body: object (BooksHmrcConnection).

Tolvi’s authority to file VAT returns for the business at HMRC.

200 OK response for GET /api/v1/books/vat/hmrc
Field	Type	Description
`status`required	`string (BooksHmrcConnectionStatus)`	One of: `connected`, `needs_reconnect`, `disconnected`, `not_connected`, `not_available`
`environment`required	`string`nullable	sandbox, production, custom, or fake (development).
`connectedAt`required	`string (date-time)`nullable
`grantExpiresAt`required	`string (date-time)`nullable	HMRC’s authority lasts 18 months, then you connect again.
`reconnectSoon`required	`boolean`
`message`required	`string`

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

Disconnect from HMRC

DELETE/api/v1/books/vat/hmrc

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

The business’s owners and admins, signed in. Tolvi forgets the tokens; filed returns stay. Part of the books product: the firm must have it and you must have access to it.

Responses

200 OK, `application/json`

Body: object (BooksHmrcConnection).

Tolvi’s authority to file VAT returns for the business at HMRC.

The fields are as shown above.

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

Start connecting to HMRC

POST/api/v1/books/vat/hmrc/authorize

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

The business’s owners and admins, signed in. Returns HMRC’s sign-in URL; HMRC sends the person back to the Books app, which finishes with POST /books/vat/hmrc/callback. Never through MCP. Part of the books product: the firm must have it and you must have access to it.

Responses

200 OK, `application/json`

Body: object (BooksHmrcAuthorize).

200 OK response for POST /api/v1/books/vat/hmrc/authorize
Field	Type	Description
`url`required	`string`	Send the person here to sign in to HMRC and give Tolvi authority.

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

Finish connecting to HMRC

POST/api/v1/books/vat/hmrc/callback

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

Called by the Books app’s HMRC return page with the code and state, as the person who started. The state is single use and lasts 10 minutes. Tokens are encrypted and never returned. Part of the books product: the firm must have it and you must have access to it.

Request body

Required. application/json: object (BooksHmrcCallback).

Request body for POST /api/v1/books/vat/hmrc/callback
Field	Type	Description
`code`required	`string`
`state`required	`string`

Responses

200 OK, `application/json`

Body: object (BooksHmrcConnection).

Tolvi’s authority to file VAT returns for the business at HMRC.

The fields are as shown above.

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

Get the VAT periods from HMRC

POST/api/v1/books/vat/hmrc/obligations/refresh

Scopes: books:write

Asks HMRC for the business’s obligations (about eight months back and four ahead) and keeps them. Send the browser’s facts for the fraud prevention headers. Part of the books product: the firm must have it and you must have access to it.

Request body

Required. application/json: object (BooksVatWithClientFacts).

Request body for POST /api/v1/books/vat/hmrc/obligations/refresh
Field	Type	Description
`clientFacts`required	`object (BooksVatClientFacts)`	What the browser knows about itself, for HMRC’s fraud prevention headers (Gov-Client-*). Send it with every request that reaches HMRC.
`clientFacts.deviceId`required	`string (uuid)`	A UUID kept on this device (local storage).
`clientFacts.userAgent`required	`string`	navigator.userAgent
`clientFacts.screens`required	`array of object`
`clientFacts.screens[].width`required	`integer`
`clientFacts.screens[].height`required	`integer`
`clientFacts.screens[].scalingFactor`required	`number`
`clientFacts.screens[].colourDepth`required	`integer`
`clientFacts.windowWidth`required	`integer`
`clientFacts.windowHeight`required	`integer`
`clientFacts.timezone`required	`string`	example "UTC+01:00"
`clientFacts.appVersion`	`string`

Responses

200 OK, `application/json`

Body: object (BooksVatPeriods).

The fields are as shown above.

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

Get VAT owed and paid from HMRC

POST/api/v1/books/vat/hmrc/payments/refresh

Scopes: books:write

Asks HMRC for the business’s liabilities and payments over the last year and keeps them. Part of the books product: the firm must have it and you must have access to it.

Request body

Required. application/json: object (BooksVatWithClientFacts).

The fields are as shown above.

Responses

200 OK, `application/json`

Body: object (BooksVatPaymentsAndLiabilities).

What HMRC says is owed and has been paid, as last fetched.

The fields are as shown above.

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

Books: VAT and reports

Get the profit and loss

Parameters

Responses

200 OK, application/json

Get the balance sheet

Parameters

Responses

200 OK, application/json

Get aged debtors (who owes the business)

Parameters

Responses

200 OK, application/json

Get aged creditors (whom the business owes)

Parameters

Responses

200 OK, application/json

Get the VAT owed per the books

Parameters

Responses

200 OK, application/json

Get cash flow by month

Parameters

Responses

200 OK, application/json

Get SA103 totals (sole traders)

Parameters

Responses

200 OK, application/json

List the entries behind a report figure

Parameters

Responses

200 OK, application/json

Estimate the tax to set aside

Parameters

Responses

200 OK, application/json

Download a report as CSV or PDF

Parameters

Responses

200 OK, text/csv

Get the home screen figures

Parameters

Responses

200 OK, application/json

Get the extra information for the tax estimate

Parameters

Responses

200 OK, application/json

Save the extra information for the tax estimate

Parameters

Request body

Responses

200 OK, application/json

Get VAT at a glance

Responses

200 OK, application/json

Get the VAT settings

Responses

200 OK, application/json

Change the VAT settings

Request body

Responses

200 OK, application/json

List the VAT periods

Responses

200 OK, application/json

Get a VAT return

Parameters

Responses

200 OK, application/json

List the lines behind a VAT return

Parameters

Responses

200 OK, application/json

Check a VAT return before filing

Parameters

Responses

200 OK, application/json

Record telling HMRC about corrections over the limit

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, `text/csv`

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`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`