Journals

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

List journals

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

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}/journals
Name	In	Type	Description
`id`required	path	`string (uuid)`	Engagement id.

Responses

200 OK, `application/json`

Body: array of Journal.

200 OK response for GET /api/v1/engagements/{id}/journals
Field	Type	Description
`[].id`required	`string (uuid)`
`[].ref`required	`string`	example "JNL-03"
`[].date`required	`string (date)`	example "2026-03-31"
`[].type`required	`string (JournalType)`	One of: `Adjusting`, `Reclassification`, `Correction`
`[].status`required	`string (JournalStatus)`	One of: `draft`, `posted`
`[].narrative`required	`string`
`[].autoKind`required	`string (JournalAutoKind)`nullable	Posted by Tolvi from the tax computation (ct, deferred) or the fixed asset register (fixed_assets). One of: `ct`, `deferred`, `fixed_assets`
`[].lines`required	`array of JournalLine`
`[].lines[].accountCode`required	`string`
`[].lines[].accountName`required	`string`nullable
`[].lines[].debitPence`required	`integer`	Integer pence (GBP).
`[].lines[].creditPence`required	`integer`	Integer pence (GBP).
`[].sectionCodes`required	`array of string`	Lead sections the journal touches.
`[].lockedBySections`required	`array of string`	Reviewed sections that lock it: only a reviewer or above can unpost or delete it.
`[].createdBy`required	`string (uuid)`nullable
`[].createdAt`required	`string (date-time)`
`[].postedBy`required	`string (uuid)`nullable
`[].postedAt`required	`string (date-time)`nullable

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

Create a journal (draft by default)

POST/api/v1/engagements/{id}/journals

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

Debits must equal credits. A draft raises an issue on every lead section it touches. Preparers, reviewers, managers and partners can all do this; the audit trail records who. 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}/journals
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 (CreateJournal).

Request body for POST /api/v1/engagements/{id}/journals
Field	Type	Description
`date`	`string (date)`	Default: the period end. example "2026-03-31"
`type`required	`string (JournalType)`	One of: `Adjusting`, `Reclassification`, `Correction`
`narrative`required	`string`	1 to 1000 characters
`status`	`string (JournalStatus)`	Default draft. One of: `draft`, `posted`
`lines`required	`array of JournalLineInput`	2 to 200 items
`lines[].accountCode`required	`string`
`lines[].debitPence`required	`integer`	Integer pence (GBP). at least 0
`lines[].creditPence`required	`integer`	Integer pence (GBP). at least 0

Responses

201 Created, `application/json`

Body: object (Journal).

201 Created response for POST /api/v1/engagements/{id}/journals
Field	Type	Description
`id`required	`string (uuid)`
`ref`required	`string`	example "JNL-03"
`date`required	`string (date)`	example "2026-03-31"
`type`required	`string (JournalType)`	One of: `Adjusting`, `Reclassification`, `Correction`
`status`required	`string (JournalStatus)`	One of: `draft`, `posted`
`narrative`required	`string`
`autoKind`required	`string (JournalAutoKind)`nullable	Posted by Tolvi from the tax computation (ct, deferred) or the fixed asset register (fixed_assets). One of: `ct`, `deferred`, `fixed_assets`
`lines`required	`array of JournalLine`
`lines[].accountCode`required	`string`
`lines[].accountName`required	`string`nullable
`lines[].debitPence`required	`integer`	Integer pence (GBP).
`lines[].creditPence`required	`integer`	Integer pence (GBP).
`sectionCodes`required	`array of string`	Lead sections the journal touches.
`lockedBySections`required	`array of string`	Reviewed sections that lock it: only a reviewer or above can unpost or delete it.
`createdBy`required	`string (uuid)`nullable
`createdAt`required	`string (date-time)`
`postedBy`required	`string (uuid)`nullable
`postedAt`required	`string (date-time)`nullable

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

Preview what a journal change would do

POST/api/v1/engagements/{id}/journals/impact

Scopes: engagements:read

Works out, without saving anything, which sections’ content would change and whose sign-offs would go out of date if a new journal were saved (give its lines) or a saved journal were posted, unposted or deleted (give journalId and action). Also the headline figures that would move. Read access is enough. 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}/journals/impact
Name	In	Type	Description
`id`required	path	`string (uuid)`	Engagement id.

Request body

Required. application/json: object (JournalImpactRequest).

Either a journal not yet saved (lines, with status) or a saved one and what would be done to it.

Request body for POST /api/v1/engagements/{id}/journals/impact
Field	Type	Description
`journalId`	`string (uuid)`	A saved journal. Give action too.
`action`	`string (JournalImpactAction)`	One of: `post`, `unpost`, `delete`
`lines`	`array of JournalLineInput`	A new journal’s lines (instead of journalId). 1 to 200 items
`lines[].accountCode`required	`string`
`lines[].debitPence`required	`integer`	Integer pence (GBP). at least 0
`lines[].creditPence`required	`integer`	Integer pence (GBP). at least 0
`status`	`string (JournalStatus)`	For new lines: posted (default) or draft. One of: `draft`, `posted`
`date`	`string (date)`	For new lines. Default: the period end. example "2026-03-31"

Responses

200 OK, `application/json`

Body: object (JournalImpact).

What a journal change would do, worked out without saving anything.

200 OK response for POST /api/v1/engagements/{id}/journals/impact
Field	Type	Description
`sections`required	`array of SectionImpact`	Sections whose content would change, in file order.
`sections[].code`required	`string`
`sections[].name`required	`string`
`sections[].staleSignOffs`required	`array of StaleSignOff`	Live sign-offs on the section that would go out of date.
`sections[].staleSignOffs[].stageId`required	`string`
`sections[].staleSignOffs[].stageName`required	`string`
`sections[].staleSignOffs[].userId`required	`string (uuid)`
`figures`required	`array of FigureChange`	Headline figures that would move.
`figures[].key`required	`string (FigureKey)`	One of: `profit_before_tax`, `corporation_tax`, `tax_charge`, `net_profit`
`figures[].label`required	`string`
`figures[].beforePence`required	`integer`	Integer pence (GBP).
`figures[].afterPence`required	`integer`	Integer pence (GBP).

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

Post a draft journal

POST/api/v1/engagements/{id}/journals/{journalId}/post

Scopes: engagements:write and engagements:read

Records who posted it (postedBy). Preparers, reviewers, managers and partners can all do this; the audit trail records who. 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}/journals/{journalId}/post
Name	In	Type	Description
`id`required	path	`string (uuid)`	Engagement id.
`journalId`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (Journal).

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

Unpost a journal

POST/api/v1/engagements/{id}/journals/{journalId}/unpost

Scopes: engagements:write and engagements:read

Preparers, reviewers, managers and partners can unpost; the audit trail records who. A posted journal touching a section with a current review sign-off can only be unposted by a reviewer or above (403 for a preparer). 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}/journals/{journalId}/unpost
Name	In	Type	Description
`id`required	path	`string (uuid)`	Engagement id.
`journalId`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (Journal).

The fields are as shown above.

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

Delete a journal

DELETE/api/v1/engagements/{id}/journals/{journalId}

Scopes: engagements:write and engagements:read

Same people and lock rule as unposting: a posted journal touching a reviewed section can only be deleted by a reviewer or above. Part of the working_papers product: the firm must have it and you must have access to it.

Parameters

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

Responses

204 No content

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

List journal-only accounts

GET/api/v1/engagements/{id}/journal-accounts

Scopes: engagements:read

Accounts Tolvi added for journals when the client’s bookkeeping has none (for example a corporation tax charge and creditor), and the standard ones it suggests. They are in no TB version; the final TB shows them from posted journals only. 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}/journal-accounts
Name	In	Type	Description
`id`required	path	`string (uuid)`	Engagement id.

Responses

200 OK, `application/json`

Body: object (JournalAccounts).

200 OK response for GET /api/v1/engagements/{id}/journal-accounts
Field	Type	Description
`accounts`required	`array of JournalAccount`
`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[].lineLabel`required	`string`nullable
`accounts[].journalRefs`required	`array of string`	Journals that post to it (it cannot be removed while any do).
`suggestions`required	`array of JournalAccountSuggestion`
`suggestions[].purpose`required	`string (JournalAccountPurpose)`	One of: `ct_charge`, `ct_creditor`, `dt_charge`, `dt_provision`, `disposal`, `disposal_proceeds`
`suggestions[].code`required	`string`
`suggestions[].name`required	`string`
`suggestions[].lineId`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`
`suggestions[].needed`required	`boolean`	Nothing on the TB or among Tolvi’s accounts serves this purpose yet.

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

Add journal-only accounts

POST/api/v1/engagements/{id}/journal-accounts

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

Each needs a code not already on the engagement and a lead schedule line. The TB version is not changed. Returns the list. 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}/journal-accounts
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 (CreateJournalAccounts).

Request body for POST /api/v1/engagements/{id}/journal-accounts
Field	Type	Description
`accounts`required	`array of NewJournalAccount`
`accounts[].code`required	`string`	Letters, digits, - . or /; not already an account on the engagement. up to 50 characters
`accounts[].name`required	`string`	up to 200 characters
`accounts[].lineId`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`

Responses

201 Created, `application/json`

Body: object (JournalAccounts).

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

Remove a journal-only account

DELETE/api/v1/engagements/{id}/journal-accounts/{code}

Scopes: engagements:write and engagements:read

Refused (409) while any journal posts to it, C uses it for disposal proceeds, or an asset class uses it. Part of the working_papers product: the firm must have it and you must have access to it.

Parameters

Parameters for DELETE /api/v1/engagements/{id}/journal-accounts/{code}
Name	In	Type	Description
`id`required	path	`string (uuid)`	Engagement id.
`code`required	path	`string`	up to 50 characters

Responses

204 No content

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

List the accounts to choose from

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

Scopes: engagements:read

Every account C’s pickers and journal lines can use: the trial balance’s accounts, Tolvi’s journal-only accounts, and the client’s chart of accounts (read from their bookkeeping software, or imported from a CSV), including accounts with no balance in this TB. Each has its lead schedule line. An account with no balance yet that a class or journal uses shows in the final TB under the client’s own code. 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}/accounts
Name	In	Type	Description
`id`required	path	`string (uuid)`	Engagement id.

Responses

200 OK, `application/json`

Body: object (EngagementAccounts).

200 OK response for GET /api/v1/engagements/{id}/accounts
Field	Type	Description
`source`required	`string`nullable	Where the client’s chart of accounts came from: xero, quickbooks, sage, freeagent or csv; null when there is none (the TB’s accounts only).
`sourceLabel`required	`string`nullable	example "Xero"
`syncedAt`required	`string (date-time)`nullable	When the chart was last read or imported.
`connectedTo`required	`string`nullable	The software the client’s books are connected to, so the chart can be refreshed; null when not connected. example "Xero"
`accounts`required	`array of EngagementAccount`
`accounts[].code`required	`string`
`accounts[].name`required	`string`
`accounts[].lineId`required	`string (LeadLineId)`nullable	The account’s lead schedule line: B’s mapping, else what the chart suggests. Null when unmapped. 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	The lead schedule (section) of the line.
`accounts[].inTb`required	`boolean`	In the imported trial balance. False for a chart account with no balance in this TB, and for journal-only accounts.
`accounts[].journalOnly`required	`boolean`
`accounts[].inChart`required	`boolean`	On the client’s chart of accounts.
`accounts[].active`required	`boolean`	False for an account archived or inactive in the client’s books.
`accounts[].finalPence`required	`integer`	Final TB balance, integer pence, debit positive (nil for an account with no balance yet).

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

Journals

List journals

Parameters

Responses

200 OK, application/json

Create a journal (draft by default)

Parameters

Request body

Responses

201 Created, application/json

Preview what a journal change would do

Parameters

Request body

Responses

200 OK, application/json

Post a draft journal

Parameters

Responses

200 OK, application/json

Unpost a journal

Parameters

Responses

200 OK, application/json

Delete a journal

Parameters

Responses

204 No content

List journal-only accounts

Parameters

Responses

200 OK, application/json

Add journal-only accounts

Parameters

Request body

Responses

201 Created, application/json

Remove a journal-only account

Parameters

Responses

204 No content

List the accounts to choose from

Parameters

Responses

200 OK, application/json

200 OK, `application/json`

201 Created, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

201 Created, `application/json`

200 OK, `application/json`