Trial balance

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

Preview a trial balance import

POST/api/v1/engagements/{id}/tb/preview

Scopes: engagements:write and engagements:read

Nothing is stored. Shows the header row and columns read (layout; send columns to choose them yourself), whether it balances, new and removed codes, the journals a re-import would remove and the sign-offs it would put out of date. Part of the working_papers product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/engagements/{id}/tb/preview
Name	In	Type	Description
`id`required	path	`string (uuid)`	Engagement id.

Request body

Required. application/json: object (TbImport).

A CSV export (format: csv, content), one worksheet of a workbook (format: sheet, sheet) or structured accounts (format: json, accounts).

Request body for POST /api/v1/engagements/{id}/tb/preview
Field	Type	Description
`format`required	`string (TbImportFormat)`	One of: `csv`, `sheet`, `json`
`content`	`string`	up to 2000000 characters
`sheet`	`object (TbSheet)`	One worksheet read from a workbook (.xlsx/.xls) by the caller, e.g. SheetJS `sheet_to_json(ws, { header: 1, raw: true })`. Dates as YYYY-MM-DD strings.
`sheet.name`	`string`	Worksheet name, used as the source label when there is no file name. up to 100 characters
`sheet.firstRow`	`integer`	Spreadsheet row number of rows[0], for messages. Default 1. at least 1
`sheet.rows`required	`array of array of one of: string, number, boolean, null`	The worksheet’s cells, row by row. up to 20000 items
`accounts`	`array of TbAccountInput`	up to 20000 items
`accounts[].code`required	`string`	up to 50 characters
`accounts[].name`required	`string`	up to 200 characters
`accounts[].cyPence`required	`integer`	Integer pence (GBP).
`accounts[].pyPence`	`integer`	Integer pence (GBP).
`accounts[].type`	`string (AccountType)`	One of: `asset`, `liability`, `equity`, `revenue`, `expense`
`asAt`	`string (date)`	Overrides any date in the file. example "2026-03-31"
`sourceLabel`	`string`	File name, shown in the version list. up to 200 characters
`provider`	`string (TbProvider)`	One of: `xero`, `quickbooks`, `sage`, `freeagent`, `tolvi_books`
`confirmJournalRemoval`	`boolean`	Required when the import removes journals (see the preview).
`reopenFile`	`boolean`	Required to import into a file signed off at every stage (the preview’s `importLock` says so): the import reopens the file for re-approval, as `POST …/workflow/reopen`, in the same transaction. Only a reviewer or above (review:write) can reopen; 409 without it, 403 for anyone else.
`columns`	`object (TbColumns)`	csv and sheet only: read these columns instead of detecting them. The preview’s `layout` shows what was detected.
`columns.headerRow`required	`integer`nullable	1 to 1000000
`columns.code`	`integer`	0 to 49
`columns.name`	`integer`	0 to 49
`columns.type`	`integer`	Account type (asset, liability…), when the file has one. 0 to 49
`columns.debit`	`integer`	0 to 49
`columns.credit`	`integer`	0 to 49
`columns.balance`	`integer`	0 to 49
`columns.pyDebit`	`integer`	0 to 49
`columns.pyCredit`	`integer`	0 to 49
`columns.pyBalance`	`integer`	0 to 49

Responses

200 OK, `application/json`

Body: object (TbImportPreview).

What an import would do. Nothing is stored.

200 OK response for POST /api/v1/engagements/{id}/tb/preview
Field	Type	Description
`accountCount`required	`integer`
`addedCodes`required	`array of string`
`removedCodes`required	`array of string`
`changedCount`required	`integer`	Accounts whose balances differ from the current version.
`cyTotalPence`required	`integer`	Integer pence (GBP).
`balanced`required	`boolean`
`hash`required	`string`
`sameAsCurrent`required	`boolean`	Identical to the current version (an import would be refused).
`journalsToRemove`required	`array of JournalRef`	Journals whose accounts are not in the new TB: confirm before they are removed.
`journalsToRemove[].id`required	`string (uuid)`
`journalsToRemove[].ref`required	`string`
`journalsToRemove[].status`required	`string (JournalStatus)`	One of: `draft`, `posted`
`unmappedCount`required	`integer`	Accounts nothing could map.
`debitTotalPence`required	`integer`	Current year debit balances added up, in integer pence.
`creditTotalPence`required	`integer`	Current year credit balances added up, in integer pence (negative).
`accounts`required	`array of TbPreviewAccount`	The accounts as read, in file order.
`accounts[].code`required	`string`
`accounts[].name`required	`string`
`accounts[].cyPence`required	`integer`	Current year balance in integer pence: debits positive, credits negative.
`accounts[].pyPence`required	`integer`	Prior year balance in integer pence: debits positive, credits negative.
`accounts[].lineId`required	`string (LeadLineId)`nullable	The mapping already held for this code, else the one found automatically; null when it needs mapping. One of: `C.cost`, `C.dep`, `D.stk`, `E.td`, `E.pre`, `F.bank`, `G.tc`, `G.acc`, `H.vat`, `I.paye`, `J.dla`, `J.loanst`, `J.loan`, `K.cap`, `K.res`, `K.div`, `L.sales`, `L.intrec`, `M.cos`, `M.adm`, `M.dis`, `M.dep`, `M.int`, `M.disp`, `T.chg`, `T.liab`, `T.dtc`, `P.dt`, `J.cap`, `J.draw`
`warnings`required	`array of TbWarning`
`warnings[].code`required	`string`
`warnings[].message`required	`string`
`layout`required	`object (TbColumns)`nullable	The header row and columns read (detected, or as given in `columns`). Null for structured accounts.
`layout.headerRow`required	`integer`nullable	1 to 1000000
`layout.code`	`integer`	0 to 49
`layout.name`	`integer`	0 to 49
`layout.type`	`integer`	Account type (asset, liability…), when the file has one. 0 to 49
`layout.debit`	`integer`	0 to 49
`layout.credit`	`integer`	0 to 49
`layout.balance`	`integer`	0 to 49
`layout.pyDebit`	`integer`	0 to 49
`layout.pyCredit`	`integer`	0 to 49
`layout.pyBalance`	`integer`	0 to 49
`staleSignOffs`required	`array of TbStaleSignOff`	Sections whose current sign-offs this import would put out of date.
`staleSignOffs[].sectionCode`required	`string`
`staleSignOffs[].sectionName`required	`string`
`staleSignOffs[].stages`required	`array of string`	The stages whose sign-off would go out of date, e.g. "Preparer", "Reviewer".
`importLock`	`object (TbImportLock)`nullable	Set when the file is signed off at every stage: the import is refused unless it reopens the file.
`importLock.code`required	`string (TbImportLockCode)`	One of: `file_signed_off`, `reopen_not_permitted`
`importLock.reason`required	`string`	In plain words, for the import screen.
`importLock.canReopen`required	`boolean`	The caller can import anyway by reopening the file (send `reopenFile: true`). False for a preparer: a reviewer or above reopens it first.

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

List trial balance versions, newest first

GET/api/v1/engagements/{id}/tb/versions

Scopes: engagements:read

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

Parameters

Parameters for GET /api/v1/engagements/{id}/tb/versions
Name	In	Type	Description
`id`required	path	`string (uuid)`	Engagement id.

Responses

200 OK, `application/json`

Body: array of TbVersion.

200 OK response for GET /api/v1/engagements/{id}/tb/versions
Field	Type	Description
`[].id`required	`string (uuid)`
`[].version`required	`integer`	at least 1
`[].sourceKind`required	`string (TbSourceKind)`	One of: `csv`, `excel`, `api`, `manual`
`[].sourceLabel`required	`string`nullable
`[].provider`required	`string`nullable
`[].asAt`required	`string (date)`nullable	example "2026-03-31"
`[].booksThroughSeq`required	`integer`nullable	Pulled from Tolvi Books: the ledger point it was read at (the last entry included), so the same trial balance can be recomputed and later entries found exactly. Null for any other source.
`[].hash`required	`string`	Content hash (sha256): the same balances give the same hash.
`[].accountCount`required	`integer`	at least 0
`[].cyTotalPence`required	`integer`	Integer pence (GBP). Net of current year balances (nil when balanced).
`[].pyTotalPence`required	`integer`	Integer pence (GBP).
`[].balanced`required	`boolean`
`[].removedJournalRefs`required	`array of string`
`[].createdBy`required	`string (uuid)`nullable
`[].createdAt`required	`string (date-time)`

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

Import a trial balance (CSV or JSON)

POST/api/v1/engagements/{id}/tb/versions

Scopes: engagements:write and engagements:read
Retries: Send an Idempotency-Key to make retries safe.

Adds an immutable version in pence. If journals would be removed, send confirmJournalRemoval: true after showing the preview (409 otherwise). A file signed off at every stage takes a new trial balance only with reopenFile: true, which reopens it for re-approval in the same transaction: 409 without it, 403 for anyone who cannot reopen a file (a reviewer or above does). The preview’s importLock and GET …/mappings say so first. Part of the working_papers product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/engagements/{id}/tb/versions
Name	In	Type	Description
`id`required	path	`string (uuid)`	Engagement id.
`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 (TbImport).

A CSV export (format: csv, content), one worksheet of a workbook (format: sheet, sheet) or structured accounts (format: json, accounts).

The fields are as shown above.

Responses

201 Created, `application/json`

Body: object (TbImportResult).

201 Created response for POST /api/v1/engagements/{id}/tb/versions
Field	Type	Description
`version`required	`object (TbVersion)`
`version.id`required	`string (uuid)`
`version.version`required	`integer`	at least 1
`version.sourceKind`required	`string (TbSourceKind)`	One of: `csv`, `excel`, `api`, `manual`
`version.sourceLabel`required	`string`nullable
`version.provider`required	`string`nullable
`version.asAt`required	`string (date)`nullable	example "2026-03-31"
`version.booksThroughSeq`required	`integer`nullable	Pulled from Tolvi Books: the ledger point it was read at (the last entry included), so the same trial balance can be recomputed and later entries found exactly. Null for any other source.
`version.hash`required	`string`	Content hash (sha256): the same balances give the same hash.
`version.accountCount`required	`integer`	at least 0
`version.cyTotalPence`required	`integer`	Integer pence (GBP). Net of current year balances (nil when balanced).
`version.pyTotalPence`required	`integer`	Integer pence (GBP).
`version.balanced`required	`boolean`
`version.removedJournalRefs`required	`array of string`
`version.createdBy`required	`string (uuid)`nullable
`version.createdAt`required	`string (date-time)`
`removedJournalRefs`required	`array of string`
`warnings`required	`array of TbWarning`
`warnings[].code`required	`string`
`warnings[].message`required	`string`
`unmappedCount`required	`integer`

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

Get the final trial balance

GET/api/v1/engagements/{id}/tb

Scopes: engagements:read

Current version + posted journals, derived on every request and never stored. Part of the working_papers product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/engagements/{id}/tb
Name	In	Type	Description
`id`required	path	`string (uuid)`	Engagement id.

Responses

200 OK, `application/json`

Body: object (FinalTrialBalance).

Draft TB + posted journals, derived on every request (never stored).

200 OK response for GET /api/v1/engagements/{id}/tb
Field	Type	Description
`version`required	`object (TbVersion)`nullable
`version.id`required	`string (uuid)`
`version.version`required	`integer`	at least 1
`version.sourceKind`required	`string (TbSourceKind)`	One of: `csv`, `excel`, `api`, `manual`
`version.sourceLabel`required	`string`nullable
`version.provider`required	`string`nullable
`version.asAt`required	`string (date)`nullable	example "2026-03-31"
`version.booksThroughSeq`required	`integer`nullable	Pulled from Tolvi Books: the ledger point it was read at (the last entry included), so the same trial balance can be recomputed and later entries found exactly. Null for any other source.
`version.hash`required	`string`	Content hash (sha256): the same balances give the same hash.
`version.accountCount`required	`integer`	at least 0
`version.cyTotalPence`required	`integer`	Integer pence (GBP). Net of current year balances (nil when balanced).
`version.pyTotalPence`required	`integer`	Integer pence (GBP).
`version.balanced`required	`boolean`
`version.removedJournalRefs`required	`array of string`
`version.createdBy`required	`string (uuid)`nullable
`version.createdAt`required	`string (date-time)`
`accounts`required	`array of FinalTbAccount`
`accounts[].code`required	`string`
`accounts[].name`required	`string`
`accounts[].journalOnly`	`boolean`	Added in Tolvi for journals (journal-only): in no TB version, so draft and prior year are nil and the final balance is journals only.
`accounts[].chartOnly`	`boolean`	An account on the client’s chart of accounts with no balance in this TB, used here by C or a journal: shown under the client’s own code, with nil draft and prior year, so it matches their books once they post it.
`accounts[].lineId`required	`string (LeadLineId)`nullable	One of: `C.cost`, `C.dep`, `D.stk`, `E.td`, `E.pre`, `F.bank`, `G.tc`, `G.acc`, `H.vat`, `I.paye`, `J.dla`, `J.loanst`, `J.loan`, `K.cap`, `K.res`, `K.div`, `L.sales`, `L.intrec`, `M.cos`, `M.adm`, `M.dis`, `M.dep`, `M.int`, `M.disp`, `T.chg`, `T.liab`, `T.dtc`, `P.dt`, `J.cap`, `J.draw`
`accounts[].lineLabel`required	`string`nullable
`accounts[].sectionCode`required	`string`nullable
`accounts[].pyPence`required	`integer`	Integer pence (GBP).
`accounts[].draftPence`required	`integer`	Integer pence (GBP).
`accounts[].adjustmentsPence`required	`integer`	Integer pence (GBP).
`accounts[].draftJournalsPence`required	`integer`	Integer pence (GBP).
`accounts[].finalPence`required	`integer`	Integer pence (GBP).
`accounts[].needsExplanation`required	`boolean`	Final against prior year moved by at least both of the year-end file’s review thresholds: the same test as a lead schedule line. T’s accounts are explained by the tax computation, so never.
`draftTotalPence`required	`integer`	Integer pence (GBP).
`finalTotalPence`required	`integer`	Integer pence (GBP).
`pyTotalPence`required	`integer`	Integer pence (GBP).
`balanced`required	`boolean`

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

Get account mappings

GET/api/v1/engagements/{id}/mappings

Scopes: engagements:read

Each account’s lead schedule line and why (client memory, firm rule or built-in). Part of the working_papers product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/engagements/{id}/mappings
Name	In	Type	Description
`id`required	path	`string (uuid)`	Engagement id.

Responses

200 OK, `application/json`

Body: object (Mappings).

200 OK response for GET /api/v1/engagements/{id}/mappings
Field	Type	Description
`accounts`required	`array of AccountMapping`
`accounts[].code`required	`string`
`accounts[].name`required	`string`
`accounts[].lineId`required	`string (LeadLineId)`nullable	One of: `C.cost`, `C.dep`, `D.stk`, `E.td`, `E.pre`, `F.bank`, `G.tc`, `G.acc`, `H.vat`, `I.paye`, `J.dla`, `J.loanst`, `J.loan`, `K.cap`, `K.res`, `K.div`, `L.sales`, `L.intrec`, `M.cos`, `M.adm`, `M.dis`, `M.dep`, `M.int`, `M.disp`, `T.chg`, `T.liab`, `T.dtc`, `P.dt`, `J.cap`, `J.draw`
`accounts[].source`required	`string (MappingSource)`nullable	chart: an account on the client’s chart of accounts with no balance in this TB, put on the line its use in C implies or the mapping order suggested. books: the account’s lead schedule line in the client’s Tolvi Books. One of: `client`, `firm`, `books`, `builtin`, `manual`, `chart`
`accounts[].explanation`required	`string`
`accounts[].allowed`required	`boolean`	The line can be used for this entity type.
`lines`required	`array of MappingLine`
`lines[].id`required	`string (LeadLineId)`	One of: `C.cost`, `C.dep`, `D.stk`, `E.td`, `E.pre`, `F.bank`, `G.tc`, `G.acc`, `H.vat`, `I.paye`, `J.dla`, `J.loanst`, `J.loan`, `K.cap`, `K.res`, `K.div`, `L.sales`, `L.intrec`, `M.cos`, `M.adm`, `M.dis`, `M.dep`, `M.int`, `M.disp`, `T.chg`, `T.liab`, `T.dtc`, `P.dt`, `J.cap`, `J.draw`
`lines[].label`required	`string`
`lines[].sectionCode`required	`string`
`lines[].allowed`required	`boolean`
`unmappedCount`required	`integer`
`lockedReason`	`string`nullable	Why the caller cannot change mappings now (B reviewed): ask the reviewer to reopen it.
`importLock`	`object (TbImportLock)`nullable	Set when a new trial balance cannot simply be imported: the file is signed off at every stage. B’s import panel says so before anyone starts.
`importLock.code`required	`string (TbImportLockCode)`	One of: `file_signed_off`, `reopen_not_permitted`
`importLock.reason`required	`string`	In plain words, for the import screen.
`importLock.canReopen`required	`boolean`	The caller can import anyway by reopening the file (send `reopenFile: true`). False for a preparer: a reviewer or above reopens it first.

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

Set account mappings

PUT/api/v1/engagements/{id}/mappings

Scopes: engagements:write and engagements:read

Remembered for the client’s future engagements unless remember is false. Once B’s review sign-off is current, only a reviewer or above can change mappings (403 with the reason, as for T and C); lockedReason on GET says so first. Part of the working_papers product: the firm must have it and you must have access to it.

Parameters

Parameters for PUT /api/v1/engagements/{id}/mappings
Name	In	Type	Description
`id`required	path	`string (uuid)`	Engagement id.

Request body

Required. application/json: object (SetMappings).

Request body for PUT /api/v1/engagements/{id}/mappings
Field	Type	Description
`mappings`required	`array of MappingChange`	1 to 5000 items
`mappings[].code`required	`string`
`mappings[].lineId`required	`string (LeadLineId)`nullable	Null to unmap. One of: `C.cost`, `C.dep`, `D.stk`, `E.td`, `E.pre`, `F.bank`, `G.tc`, `G.acc`, `H.vat`, `I.paye`, `J.dla`, `J.loanst`, `J.loan`, `K.cap`, `K.res`, `K.div`, `L.sales`, `L.intrec`, `M.cos`, `M.adm`, `M.dis`, `M.dep`, `M.int`, `M.disp`, `T.chg`, `T.liab`, `T.dtc`, `P.dt`, `J.cap`, `J.draw`
`remember`	`boolean`	Remember for this client’s future engagements (client memory). Default true.

Responses

200 OK, `application/json`

Body: object (Mappings).

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

Trial balance

Preview a trial balance import

Parameters

Request body

Responses

200 OK, application/json

List trial balance versions, newest first

Parameters

Responses

200 OK, application/json

Import a trial balance (CSV or JSON)

Parameters

Request body

Responses

201 Created, application/json

Get the final trial balance

Parameters

Responses

200 OK, application/json

Get account mappings

Parameters

Responses

200 OK, application/json

Set account mappings

Parameters

Request body

Responses

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`