Engagements

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

Start an engagement for a client

POST/api/v1/engagements

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

Creates the entity-aware section index and checklists (firm template, else built-in, plus the client’s own steps). Billable (engagement.started); AI tokens come from the plan’s monthly allowance, not from each start. 402 when billing blocks starting; 409 when the period overlaps one of the client’s existing engagements.

Needs the Preparer role or above. 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
Name	In	Type	Description
`Idempotency-Key`	header	`string`	A unique key (1-255 visible characters) to make retries safe. Replayed for 24 hours. 1 to 255 characters

Request body

Required. application/json: object (CreateEngagement).

Start an engagement for a client. The entity type defaults to the client’s.

Request body for POST /api/v1/engagements
Field	Type	Description
`clientId`required	`string (uuid)`
`entityType`	`string (EntityType)`	One of: `LTD_FRS102_1A`, `LTD_FRS105_MICRO`, `LLP`, `SOLE_TRADER`, `INDIVIDUAL`, `PARTNERSHIP`, `TRUST`, `ESTATE`, `CHARITY_UNINCORPORATED`, `CHARITY_TRUST`, `CIO`, `SCIO`, `CHARITABLE_COMPANY`
`periodStart`required	`string (date)`	example "2026-03-31"
`periodEnd`required	`string (date)`	example "2026-03-31"
`isFirstPeriod`	`boolean`	First period after incorporation (21-month Companies House deadline).
`workflowTemplateId`	`string`	Workflow template id (a preset id until firm templates exist). Default by entity type.
`preparerId`	`string (uuid)`nullable	Leave out to make the caller the preparer (when they are staff); null for nobody yet.
`reviewerId`	`string (uuid)`
`managerId`	`string (uuid)`
`partnerId`	`string (uuid)`
`risk`	`string (RiskLevel)`	One of: `standard`, `high`
`bringForward`	`object (RollForwardOptions)`	What to bring forward from the client’s previous engagement when it starts. Each part defaults to true. Set every part false to leave it as a deliberate step in the new file (POST /engagements/{id}/roll-forward).
`bringForward.priorYearFigures`	`boolean`	Last year’s final TB (draft + posted journals) as this year’s comparatives, kept when this year’s TB is imported.
`bringForward.mappings`	`boolean`	Last year’s account mappings (codes not yet mapped here).
`bringForward.fixedAssets`	`boolean`	The fixed asset register: closing cost and depreciation as opening balances, disposed assets left out.
`bringForward.taxBroughtForward`	`boolean`	Main and special rate pool WDVs and trading losses carried forward.
`bringForward.notes`	`boolean`	Last year’s variance notes, as hints on the lead schedules (never as this year’s explanations).

Responses

201 Created, `application/json`

Body: object (EngagementOverview).

201 Created response for POST /api/v1/engagements
Field	Type	Description
`id`required	`string (uuid)`
`clientId`required	`string (uuid)`
`clientName`required	`string`
`entityType`required	`string (EntityType)`	One of: `LTD_FRS102_1A`, `LTD_FRS105_MICRO`, `LLP`, `SOLE_TRADER`, `INDIVIDUAL`, `PARTNERSHIP`, `TRUST`, `ESTATE`, `CHARITY_UNINCORPORATED`, `CHARITY_TRUST`, `CIO`, `SCIO`, `CHARITABLE_COMPANY`
`periodStart`required	`string (date)`	example "2026-03-31"
`periodEnd`required	`string (date)`	example "2026-03-31"
`isFirstPeriod`required	`boolean`
`dueDate`required	`string (date)`	example "2026-03-31"
`risk`required	`string (RiskLevel)`	One of: `standard`, `high`
`team`required	`object (EngagementTeam)`
`team.preparerId`required	`string (uuid)`nullable
`team.reviewerId`required	`string (uuid)`nullable
`team.managerId`required	`string (uuid)`nullable
`team.partnerId`required	`string (uuid)`nullable
`thresholds`required	`object (Thresholds)`	Movements at or above both thresholds need an explanation.
`thresholds.absolutePence`required	`integer`	Integer pence (GBP).
`thresholds.percent`required	`integer`	at least 0
`workflow`required	`object (EngagementWorkflow)`
`workflow.templateId`required	`string`
`workflow.templateName`required	`string`
`workflow.status`required	`string (EngagementStatus)`	One of: `not_started`, `in_progress`, `submitted`, `returned`, `complete`
`workflow.workflowStatus`required	`string (WorkflowStatus)`	One of: `in_progress`, `submitted`, `returned`, `reopened`, `approved`
`workflow.currentStageId`required	`string`
`workflow.currentStageName`required	`string`
`workflow.currentStageIndex`required	`integer`	at least 0
`workflow.stages`required	`array of WorkflowStage`
`workflow.stages[].id`required	`string`
`workflow.stages[].name`required	`string`
`workflow.stages[].state`required	`string (TimelineStepState)`	One of: `done`, `now`, `todo`
`workflow.stages[].signedBy`required	`string (uuid)`nullable
`workflow.stages[].signedAt`required	`string (date-time)`nullable
`workflow.stages[].assigneeId`required	`string (uuid)`nullable	Who the engagement team assigns to this stage (preparer, reviewer, manager or partner), or null when nobody is.
`workflow.stages[].sentBackBy`required	`string (uuid)`nullable	While the workflow is returned: who sent it back from this stage.
`workflow.stages[].sentBackAt`required	`string (date-time)`nullable	While the workflow is returned: when it was sent back from this stage.
`workflow.round`required	`integer`	Amendment round (each return or reopen starts a new one). at least 1
`workflow.returnCount`required	`integer`	at least 0
`workflow.reopenCount`required	`integer`	at least 0
`workflow.changedAfterApproval`required	`boolean`
`workflow.returnTargets`required	`array of string`	Stages a return can go back to.
`workflow.actions`required	`object (EngagementActions)`	The engagement-level actions, checked for the caller.
`workflow.actions.submit`required	`object (GuardResult)`	Whether the caller can take an action now, and every reason not.
`workflow.actions.submit.allowed`required	`boolean`
`workflow.actions.submit.reasons`required	`array of string`
`workflow.actions.submit.codes`required	`array of string`	Machine-readable reason codes from @tolvi/workflow.
`workflow.actions.approve`required	`object (GuardResult)`	Whether the caller can take an action now, and every reason not.
`workflow.actions.approve.allowed`required	`boolean`
`workflow.actions.approve.reasons`required	`array of string`
`workflow.actions.approve.codes`required	`array of string`	Machine-readable reason codes from @tolvi/workflow.
`workflow.actions.return`required	`object (GuardResult)`	Whether the caller can take an action now, and every reason not.
`workflow.actions.return.allowed`required	`boolean`
`workflow.actions.return.reasons`required	`array of string`
`workflow.actions.return.codes`required	`array of string`	Machine-readable reason codes from @tolvi/workflow.
`workflow.actions.reopen`required	`object (GuardResult)`	Whether the caller can take an action now, and every reason not.
`workflow.actions.reopen.allowed`required	`boolean`
`workflow.actions.reopen.reasons`required	`array of string`
`workflow.actions.reopen.codes`required	`array of string`	Machine-readable reason codes from @tolvi/workflow.
`trialBalance`required	`object (TbVersion)`nullable
`trialBalance.id`required	`string (uuid)`
`trialBalance.version`required	`integer`	at least 1
`trialBalance.sourceKind`required	`string (TbSourceKind)`	One of: `csv`, `excel`, `api`, `manual`
`trialBalance.sourceLabel`required	`string`nullable
`trialBalance.provider`required	`string`nullable
`trialBalance.asAt`required	`string (date)`nullable	example "2026-03-31"
`trialBalance.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.
`trialBalance.hash`required	`string`	Content hash (sha256): the same balances give the same hash.
`trialBalance.accountCount`required	`integer`	at least 0
`trialBalance.cyTotalPence`required	`integer`	Integer pence (GBP). Net of current year balances (nil when balanced).
`trialBalance.pyTotalPence`required	`integer`	Integer pence (GBP).
`trialBalance.balanced`required	`boolean`
`trialBalance.removedJournalRefs`required	`array of string`
`trialBalance.createdBy`required	`string (uuid)`nullable
`trialBalance.createdAt`required	`string (date-time)`
`sections`required	`array of SectionSummary`
`sections[].code`required	`string`	example "C"
`sections[].name`required	`string`
`sections[].kind`required	`string (SectionKind)`	One of: `plan`, `tb`, `lead`, `jnl`, `fs`
`sections[].status`required	`string (SectionStatus)`	One of: `todo`, `progress`, `prepared`, `reviewed`, `changed`
`sections[].issueCount`required	`integer`	at least 0
`sections[].openReviewPoints`required	`integer`	at least 0
`sections[].signOffs`required	`array of SignOff`
`sections[].signOffs[].stageId`required	`string`
`sections[].signOffs[].stageName`required	`string`
`sections[].signOffs[].signAs`required	`string (SignOffRole)`	Who signs at this stage, for labels such as "Sign as reviewer". One of: `preparer`, `reviewer`, `manager`, `partner`
`sections[].signOffs[].userId`required	`string (uuid)`nullable
`sections[].signOffs[].at`required	`string (date-time)`nullable
`sections[].signOffs[].current`required	`boolean`	Signed against the content as it is now.
`sections[].currentStageId`required	`string`nullable	Stage the section is at.
`openReviewPoints`required	`integer`	at least 0
`unmappedAccounts`required	`integer`	Trial balance accounts not mapped to a lead schedule line (nil accounts are not counted). Figures from the final TB are incomplete while this is above 0. at least 0
`journalOnlyAccounts`	`integer`	Accounts Tolvi added for journals (journal-only: the tax and disposal accounts). B lists them with the TB’s own accounts, so B shows `trialBalance.accountCount` plus these. at least 0
`finalTbAccounts`	`integer`	Every account on the final TB (B): the TB version’s accounts, Tolvi’s journal-only accounts and accounts only in last year’s TB. at least 0
`nextStep`required	`object (NextStep)`	The first outstanding item and the one action that deals with it.
`nextStep.message`required	`string`
`nextStep.action`required	`string (NextStepAction)`	One of: `import`, `map`, `journal`, `explain`, `reconcile`, `post_tax`, `post_deferred_tax`, `open_tax`, `fixed_assets`, `post_fixed_assets`, `checklist`, `sign`, `resign`, `answer_review_point`, `check_review_point`, `raise_review_point`, `open_section`, `submit`, `approve`, `reopen`, `wait`, `none`, `generate_file`, `start_next_year`
`nextStep.label`required	`string`nullable	Button label, e.g. "Post tax journal".
`nextStep.target`required	`string`nullable	Section code, journal id, account code or review point id the action is about.
`nextStep.done`required	`boolean`	Nothing left for anyone to do here.
`nextStep.more`required	`integer`	Further outstanding items after this one. at least 0

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

Cancel an engagement

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

Scopes: engagements:write and engagements:read
Role: Manager or above

Only while nothing is signed off. Within 14 days of starting it is credited (not billed). The file stays readable; it leaves the Work queue.

Needs the Manager role or above. 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}/cancel
Name	In	Type	Description
`id`required	path	`string (uuid)`	Engagement id.

Responses

200 OK, `application/json`

Body: object (CancelResult).

200 OK response for POST /api/v1/engagements/{id}/cancel
Field	Type	Description
`cancelled`required	`boolean`
`credited`required	`boolean`	Cancelled within 14 days with no sign-offs: a billing credit was written.

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

Get an engagement overview

GET/api/v1/engagements/{id}

Scopes: engagements:read

Sections and statuses, workflow (with the actions checked for you), trial balance and your next step. 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}
Name	In	Type	Description
`id`required	path	`string (uuid)`	Engagement id.

Responses

200 OK, `application/json`

Body: object (EngagementOverview).

The fields are as shown above.

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

List the engagement’s sections and their statuses

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

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

Responses

200 OK, `application/json`

Body: array of SectionSummary.

200 OK response for GET /api/v1/engagements/{id}/sections
Field	Type	Description
`[].code`required	`string`	example "C"
`[].name`required	`string`
`[].kind`required	`string (SectionKind)`	One of: `plan`, `tb`, `lead`, `jnl`, `fs`
`[].status`required	`string (SectionStatus)`	One of: `todo`, `progress`, `prepared`, `reviewed`, `changed`
`[].issueCount`required	`integer`	at least 0
`[].openReviewPoints`required	`integer`	at least 0
`[].signOffs`required	`array of SignOff`
`[].signOffs[].stageId`required	`string`
`[].signOffs[].stageName`required	`string`
`[].signOffs[].signAs`required	`string (SignOffRole)`	Who signs at this stage, for labels such as "Sign as reviewer". One of: `preparer`, `reviewer`, `manager`, `partner`
`[].signOffs[].userId`required	`string (uuid)`nullable
`[].signOffs[].at`required	`string (date-time)`nullable
`[].signOffs[].current`required	`boolean`	Signed against the content as it is now.
`[].currentStageId`required	`string`nullable	Stage the section is at.

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

Get a section: checklist, issues, sign-off, review points, evidence and next step

GET/api/v1/engagements/{id}/sections/{code}

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}/sections/{code}
Name	In	Type	Description
`id`required	path	`string (uuid)`	Engagement id.
`code`required	path	`string`	Section code (W/P ref), e.g. C. One of: `A`, `B`, `C`, `D`, `E`, `F`, `G`, `H`, `I`, `J`, `K`, `L`, `M`, `T`, `X`, `Z`

Responses

200 OK, `application/json`

Body: object (SectionDetail).

200 OK response for GET /api/v1/engagements/{id}/sections/{code}
Field	Type	Description
`code`required	`string`	example "C"
`name`required	`string`
`kind`required	`string (SectionKind)`	One of: `plan`, `tb`, `lead`, `jnl`, `fs`
`status`required	`string (SectionStatus)`	One of: `todo`, `progress`, `prepared`, `reviewed`, `changed`
`issueCount`required	`integer`	at least 0
`openReviewPoints`required	`integer`	at least 0
`signOffs`required	`array of SignOff`
`signOffs[].stageId`required	`string`
`signOffs[].stageName`required	`string`
`signOffs[].signAs`required	`string (SignOffRole)`	Who signs at this stage, for labels such as "Sign as reviewer". One of: `preparer`, `reviewer`, `manager`, `partner`
`signOffs[].userId`required	`string (uuid)`nullable
`signOffs[].at`required	`string (date-time)`nullable
`signOffs[].current`required	`boolean`	Signed against the content as it is now.
`currentStageId`required	`string`nullable	Stage the section is at.
`checklist`required	`array of ChecklistItem`
`checklist[].id`required	`string (uuid)`
`checklist[].position`required	`integer`
`checklist[].text`required	`string`
`checklist[].origin`required	`string (ChecklistOrigin)`	One of: `builtin`, `firm`, `client`
`checklist[].status`required	`string (ChecklistStatus)`	"" is not yet done. One of: , `done`, `na`
`checklist[].auto`required	`boolean`	Ticked by Tolvi from the data (a person’s own tick always wins).
`checklist[].note`required	`string`
`checklist[].doneBy`required	`string (uuid)`nullable
`checklist[].doneAt`required	`string (date-time)`nullable
`checklist[].evidence`required	`array of Evidence`
`checklist[].evidence[].id`required	`string (uuid)`
`checklist[].evidence[].sectionCode`required	`string`nullable
`checklist[].evidence[].checklistItemId`required	`string (uuid)`nullable
`checklist[].evidence[].reviewPointId`required	`string (uuid)`nullable
`checklist[].evidence[].reviewPointMessageId`required	`string (uuid)`nullable
`checklist[].evidence[].fileName`required	`string`
`checklist[].evidence[].contentType`required	`string`
`checklist[].evidence[].sizeBytes`required	`integer`	at least 0
`checklist[].evidence[].status`required	`string (EvidenceStatus)`	pending_upload until POST …/evidence/{evidenceId}/confirm checks the stored file; then pending_scan (malware scan) and available. Only available files can be downloaded or read by Tolvi AI. rejected: the file failed the checks or the scan found malware (see rejectedReason); it can never be downloaded. One of: `pending_upload`, `pending_scan`, `available`, `rejected`
`checklist[].evidence[].rejectedReason`required	`string`nullable	Why a rejected file was rejected, e.g. "malware detected"; null otherwise.
`checklist[].evidence[].uploadedBy`required	`string (uuid)`nullable
`checklist[].evidence[].createdAt`required	`string (date-time)`
`issues`required	`array of Issue`
`issues[].message`required	`string`
`issues[].action`required	`string (IssueAction)`	One of: `import`, `map`, `journal`, `explain`, `reconcile`, `post_tax`, `post_deferred_tax`, `open_tax`, `fixed_assets`, `post_fixed_assets`, `checklist`
`issues[].label`required	`string`
`issues[].target`required	`string`nullable
`signOff`required	`object (SectionSignOffPanel)`
`signOff.stages`required	`array of SignOff`	Every stage that applies to sections, with its live sign-off.
`signOff.stages[].stageId`required	`string`
`signOff.stages[].stageName`required	`string`
`signOff.stages[].signAs`required	`string (SignOffRole)`	Who signs at this stage, for labels such as "Sign as reviewer". One of: `preparer`, `reviewer`, `manager`, `partner`
`signOff.stages[].userId`required	`string (uuid)`nullable
`signOff.stages[].at`required	`string (date-time)`nullable
`signOff.stages[].current`required	`boolean`	Signed against the content as it is now.
`signOff.currentStageId`required	`string`
`signOff.sign`required	`object (GuardResult)`	Can the caller sign at the current stage now?
`signOff.sign.allowed`required	`boolean`
`signOff.sign.reasons`required	`array of string`
`signOff.sign.codes`required	`array of string`	Machine-readable reason codes from @tolvi/workflow.
`signOff.ownSignOffStageId`required	`string`nullable	Stage of the caller’s own live sign-off, which they can remove.
`signOff.signStageId`	`string`nullable	The stage signing now would record the caller’s sign-off at. Usually `currentStageId`; the first stage when the caller re-signs their own out-of-date preparer sign-off (the section is reopened first). Null when there is nothing to sign.
`signOff.unsign`	`object (GuardResult)`	Can the caller remove their own sign-off now? Refused while the file is signed off at every stage.
`signOff.unsign.allowed`required	`boolean`
`signOff.unsign.reasons`required	`array of string`
`signOff.unsign.codes`required	`array of string`	Machine-readable reason codes from @tolvi/workflow.
`signOff.unsignRemoves`	`array of SignOff`	Removing the caller’s own sign-off removes these later sign-offs too (other people’s).
`signOff.unsignRemoves[].stageId`required	`string`
`signOff.unsignRemoves[].stageName`required	`string`
`signOff.unsignRemoves[].signAs`required	`string (SignOffRole)`	Who signs at this stage, for labels such as "Sign as reviewer". One of: `preparer`, `reviewer`, `manager`, `partner`
`signOff.unsignRemoves[].userId`required	`string (uuid)`nullable
`signOff.unsignRemoves[].at`required	`string (date-time)`nullable
`signOff.unsignRemoves[].current`required	`boolean`	Signed against the content as it is now.
`signOff.fingerprint`required	`string`	Content fingerprint now.
`nextStep`required	`object (NextStep)`	The first outstanding item and the one action that deals with it.
`nextStep.message`required	`string`
`nextStep.action`required	`string (NextStepAction)`	One of: `import`, `map`, `journal`, `explain`, `reconcile`, `post_tax`, `post_deferred_tax`, `open_tax`, `fixed_assets`, `post_fixed_assets`, `checklist`, `sign`, `resign`, `answer_review_point`, `check_review_point`, `raise_review_point`, `open_section`, `submit`, `approve`, `reopen`, `wait`, `none`, `generate_file`, `start_next_year`
`nextStep.label`required	`string`nullable	Button label, e.g. "Post tax journal".
`nextStep.target`required	`string`nullable	Section code, journal id, account code or review point id the action is about.
`nextStep.done`required	`boolean`	Nothing left for anyone to do here.
`nextStep.more`required	`integer`	Further outstanding items after this one. at least 0
`reviewPoints`required	`array of ReviewPoint`
`reviewPoints[].id`required	`string (uuid)`
`reviewPoints[].sectionCode`required	`string`nullable	Null for a point on the engagement as a whole.
`reviewPoints[].category`required	`string (ReviewPointCategory)`	One of: `query`, `error`, `presentation`, `missing_evidence`
`reviewPoints[].status`required	`string (ReviewPointStatus)`	One of: `open`, `answered`, `cleared`, `reopened`
`reviewPoints[].raisedAtStageId`required	`string`
`reviewPoints[].raisedInRound`required	`integer`	at least 1
`reviewPoints[].raisedBy`required	`string (uuid)`nullable
`reviewPoints[].raisedAt`required	`string (date-time)`
`reviewPoints[].clearedBy`required	`string (uuid)`nullable
`reviewPoints[].clearedAt`required	`string (date-time)`nullable
`reviewPoints[].sourceMeetingId`	`string (uuid)`nullable	The meeting whose next step this point came from (Create follow-ups in Tolvi Meetings), if any.
`reviewPoints[].messages`required	`array of ReviewPointMessage`
`reviewPoints[].messages[].id`required	`string (uuid)`
`reviewPoints[].messages[].kind`required	`string (ReviewPointMessageKind)`	One of: `raise`, `comment`, `answer`, `clear`, `reopen`
`reviewPoints[].messages[].authorId`required	`string (uuid)`nullable
`reviewPoints[].messages[].body`required	`string`
`reviewPoints[].messages[].mentions`required	`array of string (uuid)`
`reviewPoints[].messages[].at`required	`string (date-time)`
`reviewPoints[].messages[].evidence`required	`array of Evidence`
`reviewPoints[].messages[].evidence[].id`required	`string (uuid)`
`reviewPoints[].messages[].evidence[].sectionCode`required	`string`nullable
`reviewPoints[].messages[].evidence[].checklistItemId`required	`string (uuid)`nullable
`reviewPoints[].messages[].evidence[].reviewPointId`required	`string (uuid)`nullable
`reviewPoints[].messages[].evidence[].reviewPointMessageId`required	`string (uuid)`nullable
`reviewPoints[].messages[].evidence[].fileName`required	`string`
`reviewPoints[].messages[].evidence[].contentType`required	`string`
`reviewPoints[].messages[].evidence[].sizeBytes`required	`integer`	at least 0
`reviewPoints[].messages[].evidence[].status`required	`string (EvidenceStatus)`	pending_upload until POST …/evidence/{evidenceId}/confirm checks the stored file; then pending_scan (malware scan) and available. Only available files can be downloaded or read by Tolvi AI. rejected: the file failed the checks or the scan found malware (see rejectedReason); it can never be downloaded. One of: `pending_upload`, `pending_scan`, `available`, `rejected`
`reviewPoints[].messages[].evidence[].rejectedReason`required	`string`nullable	Why a rejected file was rejected, e.g. "malware detected"; null otherwise.
`reviewPoints[].messages[].evidence[].uploadedBy`required	`string (uuid)`nullable
`reviewPoints[].messages[].evidence[].createdAt`required	`string (date-time)`
`evidence`required	`array of Evidence`
`evidence[].id`required	`string (uuid)`
`evidence[].sectionCode`required	`string`nullable
`evidence[].checklistItemId`required	`string (uuid)`nullable
`evidence[].reviewPointId`required	`string (uuid)`nullable
`evidence[].reviewPointMessageId`required	`string (uuid)`nullable
`evidence[].fileName`required	`string`
`evidence[].contentType`required	`string`
`evidence[].sizeBytes`required	`integer`	at least 0
`evidence[].status`required	`string (EvidenceStatus)`	pending_upload until POST …/evidence/{evidenceId}/confirm checks the stored file; then pending_scan (malware scan) and available. Only available files can be downloaded or read by Tolvi AI. rejected: the file failed the checks or the scan found malware (see rejectedReason); it can never be downloaded. One of: `pending_upload`, `pending_scan`, `available`, `rejected`
`evidence[].rejectedReason`required	`string`nullable	Why a rejected file was rejected, e.g. "malware detected"; null otherwise.
`evidence[].uploadedBy`required	`string (uuid)`nullable
`evidence[].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).

Get a lead schedule

GET/api/v1/engagements/{id}/sections/{code}/lead-schedule

Scopes: engagements:read

Accounts by line with prior year, draft, journals and final balances, movements, variance notes and tickmarks. 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}/sections/{code}/lead-schedule
Name	In	Type	Description
`id`required	path	`string (uuid)`	Engagement id.
`code`required	path	`string`	Section code (W/P ref), e.g. C. One of: `A`, `B`, `C`, `D`, `E`, `F`, `G`, `H`, `I`, `J`, `K`, `L`, `M`, `T`, `X`, `Z`

Responses

200 OK, `application/json`

Body: object (LeadSchedule).

200 OK response for GET /api/v1/engagements/{id}/sections/{code}/lead-schedule
Field	Type	Description
`sectionCode`required	`string`
`sectionName`required	`string`
`thresholds`required	`object (Thresholds)`	Movements at or above both thresholds need an explanation.
`thresholds.absolutePence`required	`integer`	Integer pence (GBP).
`thresholds.percent`required	`integer`	at least 0
`lines`required	`array of LeadLine`
`lines[].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`
`lines[].label`required	`string`
`lines[].statement`required	`string (Statement)`	One of: `BS`, `PL`, `EQ`
`lines[].accounts`required	`array of LeadAccount`
`lines[].accounts[].code`required	`string`
`lines[].accounts[].name`required	`string`
`lines[].accounts[].pyPence`required	`integer`	Integer pence (GBP).
`lines[].accounts[].draftPence`required	`integer`	Integer pence (GBP). Per the imported (draft) TB.
`lines[].accounts[].adjustmentsPence`required	`integer`	Integer pence (GBP). Posted journals.
`lines[].accounts[].draftJournalsPence`required	`integer`	Integer pence (GBP). Draft journals, not in the final figure.
`lines[].accounts[].finalPence`required	`integer`	Integer pence (GBP).
`lines[].accounts[].movementPence`required	`integer`	Integer pence (GBP).
`lines[].accounts[].movementPct`required	`number`nullable	Movement as a percentage of last year, 1 dp; null when last year was nil.
`lines[].accounts[].needsExplanation`required	`boolean`
`lines[].accounts[].note`required	`object (VarianceNote)`nullable
`lines[].accounts[].note.body`required	`string`
`lines[].accounts[].note.authorId`required	`string (uuid)`nullable
`lines[].accounts[].note.updatedAt`required	`string (date-time)`
`lines[].accounts[].note.editable`required	`boolean`	The caller wrote it, so can change it.
`lines[].accounts[].lastYearNote`required	`string`nullable	Last year’s explanation, brought forward as a hint: it never counts as this year’s.
`lines[].accounts[].tickmark`required	`object (TickmarkEntry)`nullable
`lines[].accounts[].tickmark.mark`required	`string (Tickmark)`	One of: `✓`, `‹`, `^`, `✗`
`lines[].accounts[].tickmark.label`required	`string`
`lines[].accounts[].tickmark.authorId`required	`string (uuid)`nullable
`lines[].accounts[].tickmark.updatedAt`required	`string (date-time)`
`lines[].accounts[].tickmark.editable`required	`boolean`
`lines[].totals`required	`object (LeadTotals)`
`lines[].totals.pyPence`required	`integer`	Integer pence (GBP).
`lines[].totals.draftPence`required	`integer`	Integer pence (GBP).
`lines[].totals.adjustmentsPence`required	`integer`	Integer pence (GBP).
`lines[].totals.finalPence`required	`integer`	Integer pence (GBP).
`totals`required	`object (LeadTotals)`
`totals.pyPence`required	`integer`	Integer pence (GBP).
`totals.draftPence`required	`integer`	Integer pence (GBP).
`totals.adjustmentsPence`required	`integer`	Integer pence (GBP).
`totals.finalPence`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).

List a section’s reconciliations (F bank, H VAT, I payroll)

GET/api/v1/engagements/{id}/sections/{code}/reconciliations

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}/sections/{code}/reconciliations
Name	In	Type	Description
`id`required	path	`string (uuid)`	Engagement id.
`code`required	path	`string`	Section code (W/P ref), e.g. C. One of: `A`, `B`, `C`, `D`, `E`, `F`, `G`, `H`, `I`, `J`, `K`, `L`, `M`, `T`, `X`, `Z`

Responses

200 OK, `application/json`

Body: array of Reconciliation.

200 OK response for GET /api/v1/engagements/{id}/sections/{code}/reconciliations
Field	Type	Description
`[].code`required	`string`
`[].name`required	`string`
`[].sectionCode`required	`string`
`[].kind`required	`string (ReconciliationKind)`	What the account is reconciled to: bank statement, VAT return, P32, pension schedule, CIS300, DLA or current account schedule, lender statement. One of: `bank`, `vat`, `paye`, `pension`, `cis`, `dla`, `loan`
`[].title`required	`string`
`[].sourceLabel`required	`string`
`[].sourcePence`required	`integer`nullable	Integer pence (GBP). Per the source document, in its own sign (e.g. VAT payable is positive).
`[].items`required	`array of RecItem`
`[].items[].description`required	`string`	up to 200 characters
`[].items[].amountPence`required	`integer`	Integer pence (GBP).
`[].note`required	`string`
`[].tbPence`required	`integer`	Integer pence (GBP). Final TB balance in the source document’s sign.
`[].expectedPence`required	`integer`nullable	Integer pence (GBP).
`[].differencePence`required	`integer`nullable	Integer pence (GBP).
`[].agrees`required	`boolean`
`[].ok`required	`boolean`	Agrees, or the difference is explained in the note.

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

Get your next step on the engagement and each section

GET/api/v1/engagements/{id}/next-steps

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

Responses

200 OK, `application/json`

Body: object (NextSteps).

The engagement’s next step and each section’s, for the caller.

200 OK response for GET /api/v1/engagements/{id}/next-steps
Field	Type	Description
`engagement`required	`object (NextStep)`	The first outstanding item and the one action that deals with it.
`engagement.message`required	`string`
`engagement.action`required	`string (NextStepAction)`	One of: `import`, `map`, `journal`, `explain`, `reconcile`, `post_tax`, `post_deferred_tax`, `open_tax`, `fixed_assets`, `post_fixed_assets`, `checklist`, `sign`, `resign`, `answer_review_point`, `check_review_point`, `raise_review_point`, `open_section`, `submit`, `approve`, `reopen`, `wait`, `none`, `generate_file`, `start_next_year`
`engagement.label`required	`string`nullable	Button label, e.g. "Post tax journal".
`engagement.target`required	`string`nullable	Section code, journal id, account code or review point id the action is about.
`engagement.done`required	`boolean`	Nothing left for anyone to do here.
`engagement.more`required	`integer`	Further outstanding items after this one. at least 0
`sections`required	`array of SectionNextStep`
`sections[].code`required	`string`
`sections[].name`required	`string`
`sections[].status`required	`string (SectionStatus)`	One of: `todo`, `progress`, `prepared`, `reviewed`, `changed`
`sections[].nextStep`required	`object (NextStep)`	The first outstanding item and the one action that deals with it.
`sections[].nextStep.message`required	`string`
`sections[].nextStep.action`required	`string (NextStepAction)`	One of: `import`, `map`, `journal`, `explain`, `reconcile`, `post_tax`, `post_deferred_tax`, `open_tax`, `fixed_assets`, `post_fixed_assets`, `checklist`, `sign`, `resign`, `answer_review_point`, `check_review_point`, `raise_review_point`, `open_section`, `submit`, `approve`, `reopen`, `wait`, `none`, `generate_file`, `start_next_year`
`sections[].nextStep.label`required	`string`nullable	Button label, e.g. "Post tax journal".
`sections[].nextStep.target`required	`string`nullable	Section code, journal id, account code or review point id the action is about.
`sections[].nextStep.done`required	`boolean`	Nothing left for anyone to do here.
`sections[].nextStep.more`required	`integer`	Further outstanding items after this one. at least 0

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

Write or change a variance note

PUT/api/v1/engagements/{id}/accounts/{code}/note

Scopes: engagements:write and engagements:read

Only the note’s author can change it. 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}/accounts/{code}/note
Name	In	Type	Description
`id`required	path	`string (uuid)`	Engagement id.
`code`required	path	`string`	Account code.

Request body

Required. application/json: object (SetVarianceNote).

Request body for PUT /api/v1/engagements/{id}/accounts/{code}/note
Field	Type	Description
`body`required	`string`	1 to 4000 characters

Responses

200 OK, `application/json`

Body: object (LeadSchedule).

The fields are as shown above.

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

Remove your variance note

DELETE/api/v1/engagements/{id}/accounts/{code}/note

Scopes: engagements:write and engagements:read

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

Responses

200 OK, `application/json`

Body: object (LeadSchedule).

The fields are as shown above.

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

Set a tickmark

PUT/api/v1/engagements/{id}/accounts/{code}/tickmark

Scopes: engagements:write and engagements:read

Only the tickmark’s author can change it. 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}/accounts/{code}/tickmark
Name	In	Type	Description
`id`required	path	`string (uuid)`	Engagement id.
`code`required	path	`string`	Account code.

Request body

Required. application/json: object (SetTickmark).

Request body for PUT /api/v1/engagements/{id}/accounts/{code}/tickmark
Field	Type	Description
`mark`required	`string (Tickmark)`	One of: `✓`, `‹`, `^`, `✗`

Responses

200 OK, `application/json`

Body: object (LeadSchedule).

The fields are as shown above.

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

Remove your tickmark

DELETE/api/v1/engagements/{id}/accounts/{code}/tickmark

Scopes: engagements:write and engagements:read

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

Responses

200 OK, `application/json`

Body: object (LeadSchedule).

The fields are as shown above.

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

Set a reconciliation: source balance, reconciling items and note

PUT/api/v1/engagements/{id}/reconciliations/{code}

Scopes: engagements:write and engagements:read

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}/reconciliations/{code}
Name	In	Type	Description
`id`required	path	`string (uuid)`	Engagement id.
`code`required	path	`string`	Account code of a bank, VAT or payroll control account.

Request body

Required. application/json: object (SetReconciliation).

Request body for PUT /api/v1/engagements/{id}/reconciliations/{code}
Field	Type	Description
`sourcePence`required	`integer`nullable	Integer pence (GBP).
`items`required	`array of RecItem`	up to 200 items
`items[].description`required	`string`	up to 200 characters
`items[].amountPence`required	`integer`	Integer pence (GBP).
`note`	`string`	up to 4000 characters

Responses

200 OK, `application/json`

Body: object (Reconciliation).

200 OK response for PUT /api/v1/engagements/{id}/reconciliations/{code}
Field	Type	Description
`code`required	`string`
`name`required	`string`
`sectionCode`required	`string`
`kind`required	`string (ReconciliationKind)`	What the account is reconciled to: bank statement, VAT return, P32, pension schedule, CIS300, DLA or current account schedule, lender statement. One of: `bank`, `vat`, `paye`, `pension`, `cis`, `dla`, `loan`
`title`required	`string`
`sourceLabel`required	`string`
`sourcePence`required	`integer`nullable	Integer pence (GBP). Per the source document, in its own sign (e.g. VAT payable is positive).
`items`required	`array of RecItem`
`items[].description`required	`string`	up to 200 characters
`items[].amountPence`required	`integer`	Integer pence (GBP).
`note`required	`string`
`tbPence`required	`integer`	Integer pence (GBP). Final TB balance in the source document’s sign.
`expectedPence`required	`integer`nullable	Integer pence (GBP).
`differencePence`required	`integer`nullable	Integer pence (GBP).
`agrees`required	`boolean`
`ok`required	`boolean`	Agrees, or the difference is explained in the note.

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

Mark a checklist step done or N/A, or add a note

PATCH/api/v1/engagements/{id}/checklist/{itemId}

Scopes: engagements:write and engagements:read

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

Parameters

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

Request body

Required. application/json: object (UpdateChecklistItem).

Request body for PATCH /api/v1/engagements/{id}/checklist/{itemId}
Field	Type	Description
`status`	`string (ChecklistStatus)`	"" is not yet done. One of: , `done`, `na`
`note`	`string`	up to 4000 characters

Responses

200 OK, `application/json`

Body: object (SectionDetail).

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

Attach evidence

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

Scopes: engagements:write and engagements:read

Records the file and returns a short-lived presigned URL to PUT it to storage. 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}/evidence
Name	In	Type	Description
`id`required	path	`string (uuid)`	Engagement id.

Request body

Required. application/json: object (CreateEvidence).

Give a section (optionally a checklist step) or a review point. Accepted files: PDF (.pdf); images (.png, .jpg/.jpeg, .heic/.heif, .webp); Excel (.xlsx, .xls); Word (.docx, .doc); .csv; .txt; email (.eml, .msg). The extension decides the type: contentType must agree with it (or be application/octet-stream when unknown), and the upload headers returned carry the type to PUT with. The stored bytes are checked against the type when the upload is confirmed.

Request body for POST /api/v1/engagements/{id}/evidence
Field	Type	Description
`sectionCode`	`string`
`checklistItemId`	`string (uuid)`
`reviewPointId`	`string (uuid)`
`fileName`required	`string`	1 to 200 characters
`contentType`required	`string`	up to 100 characters; example "application/pdf"
`sizeBytes`required	`integer`	1 to 104857600

Responses

201 Created, `application/json`

Body: object (EvidenceUpload).

201 Created response for POST /api/v1/engagements/{id}/evidence
Field	Type	Description
`evidence`required	`object (Evidence)`
`evidence.id`required	`string (uuid)`
`evidence.sectionCode`required	`string`nullable
`evidence.checklistItemId`required	`string (uuid)`nullable
`evidence.reviewPointId`required	`string (uuid)`nullable
`evidence.reviewPointMessageId`required	`string (uuid)`nullable
`evidence.fileName`required	`string`
`evidence.contentType`required	`string`
`evidence.sizeBytes`required	`integer`	at least 0
`evidence.status`required	`string (EvidenceStatus)`	pending_upload until POST …/evidence/{evidenceId}/confirm checks the stored file; then pending_scan (malware scan) and available. Only available files can be downloaded or read by Tolvi AI. rejected: the file failed the checks or the scan found malware (see rejectedReason); it can never be downloaded. One of: `pending_upload`, `pending_scan`, `available`, `rejected`
`evidence.rejectedReason`required	`string`nullable	Why a rejected file was rejected, e.g. "malware detected"; null otherwise.
`evidence.uploadedBy`required	`string (uuid)`nullable
`evidence.createdAt`required	`string (date-time)`
`upload`required	`object (PresignedUpload)`
`upload.url`required	`string (uri)`
`upload.method`required	`string (PresignedMethod)`	One of: `PUT`, `GET`
`upload.headers`required	`object`	Headers to send with the request.
`upload.expiresAt`required	`string (date-time)`

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

Confirm an evidence upload

POST/api/v1/engagements/{id}/evidence/{evidenceId}/confirm

Scopes: engagements:write and engagements:read

Call after the presigned PUT. Checks the stored file’s size, type and contents against what was declared, records its checksum (ETag) and starts the malware scan. Only confirmed, scanned files can be downloaded or read by Tolvi AI. 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}/evidence/{evidenceId}/confirm
Name	In	Type	Description
`id`required	path	`string (uuid)`	Engagement id.
`evidenceId`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (Evidence).

200 OK response for POST /api/v1/engagements/{id}/evidence/{evidenceId}/confirm
Field	Type	Description
`id`required	`string (uuid)`
`sectionCode`required	`string`nullable
`checklistItemId`required	`string (uuid)`nullable
`reviewPointId`required	`string (uuid)`nullable
`reviewPointMessageId`required	`string (uuid)`nullable
`fileName`required	`string`
`contentType`required	`string`
`sizeBytes`required	`integer`	at least 0
`status`required	`string (EvidenceStatus)`	pending_upload until POST …/evidence/{evidenceId}/confirm checks the stored file; then pending_scan (malware scan) and available. Only available files can be downloaded or read by Tolvi AI. rejected: the file failed the checks or the scan found malware (see rejectedReason); it can never be downloaded. One of: `pending_upload`, `pending_scan`, `available`, `rejected`
`rejectedReason`required	`string`nullable	Why a rejected file was rejected, e.g. "malware detected"; null otherwise.
`uploadedBy`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).

Get an evidence file’s status

GET/api/v1/engagements/{id}/evidence/{evidenceId}

Scopes: engagements:read

For following an upload through the malware scan: pending_upload, pending_scan, available, or rejected with the reason. 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}/evidence/{evidenceId}
Name	In	Type	Description
`id`required	path	`string (uuid)`	Engagement id.
`evidenceId`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (Evidence).

The fields are as shown above.

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

Remove evidence you attached

DELETE/api/v1/engagements/{id}/evidence/{evidenceId}

Scopes: engagements:write and engagements:read

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

Presign an evidence upload again

POST/api/v1/engagements/{id}/evidence/{evidenceId}/upload

Scopes: engagements:write and engagements:read

A fresh presigned PUT for a file that is still pending_upload (the first PUT failed or its link expired), for the same size and type. Only the person who attached it; 409 once the file has been uploaded. 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}/evidence/{evidenceId}/upload
Name	In	Type	Description
`id`required	path	`string (uuid)`	Engagement id.
`evidenceId`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (EvidenceUpload).

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 a short-lived download URL for evidence

GET/api/v1/engagements/{id}/evidence/{evidenceId}/download

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

Responses

200 OK, `application/json`

Body: object (PresignedUpload).

200 OK response for GET /api/v1/engagements/{id}/evidence/{evidenceId}/download
Field	Type	Description
`url`required	`string (uri)`
`method`required	`string (PresignedMethod)`	One of: `PUT`, `GET`
`headers`required	`object`	Headers to send with the request.
`expiresAt`required	`string (date-time)`

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

Get what was brought forward from the prior year

GET/api/v1/engagements/{id}/roll-forward

Scopes: engagements:read

The year-end roll forward: the source engagement, what was brought forward (final TB as comparatives, mappings, fixed asset register, pools and losses, variance notes as hints), whether the prior year changed since (content fingerprint) and whether it can be rolled again. 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}/roll-forward
Name	In	Type	Description
`id`required	path	`string (uuid)`	Engagement id.

Responses

200 OK, `application/json`

Body: object (RollForward).

The year-end roll forward: what was brought forward from the prior year, and whether the prior year changed since.

200 OK response for GET /api/v1/engagements/{id}/roll-forward
Field	Type	Description
`rolledForward`required	`boolean`
`source`required	`object (RollForwardSource)`nullable	The engagement brought forward from.
`source.engagementId`required	`string (uuid)`nullable	Null once that engagement was deleted.
`source.periodStart`required	`string (date)`	example "2026-03-31"
`source.periodEnd`required	`string (date)`	example "2026-03-31"
`source.status`required	`string (EngagementStatus)`nullable	One of: `not_started`, `in_progress`, `submitted`, `returned`, `complete`
`rolledAt`required	`string (date-time)`nullable
`rolledBy`required	`string (uuid)`nullable
`options`required	`object (RollForwardParts)`	What was brought forward.
`options.priorYearFigures`required	`boolean`
`options.mappings`required	`boolean`
`options.fixedAssets`required	`boolean`
`options.taxBroughtForward`required	`boolean`
`options.notes`required	`boolean`
`summary`required	`object (RollForwardSummary)`	What was brought forward; null for a part that was not.
`summary.priorYearFigures`required	`object (RolledPriorYearFigures)`nullable
`summary.priorYearFigures.accounts`required	`integer`	at least 0
`summary.priorYearFigures.profitPence`required	`integer`	Integer pence (GBP). Last year’s profit after tax per its final TB (a loss negative).
`summary.mappings`required	`integer`nullable	Mappings added.
`summary.notes`required	`integer`nullable	Variance notes brought forward as hints.
`summary.fixedAssets`required	`object (RolledFixedAssets)`nullable
`summary.fixedAssets.classes`required	`integer`	at least 0
`summary.fixedAssets.assets`required	`integer`	at least 0
`summary.fixedAssets.costPence`required	`integer`	Integer pence (GBP).
`summary.fixedAssets.depreciationPence`required	`integer`	Integer pence (GBP).
`summary.fixedAssets.nbvPence`required	`integer`	Integer pence (GBP).
`summary.tax`required	`object (RolledTax)`nullable
`summary.tax.mainPoolPence`required	`integer`	Integer pence (GBP).
`summary.tax.specialRatePoolPence`required	`integer`	Integer pence (GBP).
`summary.tax.lossesPre2017Pence`required	`integer`	Integer pence (GBP).
`summary.tax.lossesPost2017Pence`required	`integer`	Integer pence (GBP).
`summary.tax.deferredTaxPence`required	`integer`nullable	Integer pence (GBP). Last year’s deferred tax provision per its computation (liability positive); null when it did not apply.
`summary.tax.selfAssessment`required	`object (RolledSelfAssessment)`nullable	Null for a company.
`summary.tax.selfAssessment.lossesPence`required	`integer`	Integer pence (GBP). Trading losses carried forward (ITA 2007 s83).
`summary.tax.selfAssessment.overlapReliefPence`required	`integer`	Integer pence (GBP). Overlap relief not yet used (nil after 2023/24, FA 2022 Sch 1).
`summary.tax.selfAssessment.transitionProfitPence`required	`integer`	Integer pence (GBP). Transition profit still being spread.
`summary.tax.selfAssessment.partners`required	`integer`	at least 0
`summary.warnings`required	`array of string`
`priorChanged`required	`boolean`	The prior year changed after it was brought forward (its content fingerprint differs): re-roll to take the change.
`changedParts`required	`array of RollForwardPart`	The parts that changed. One of: `priorYearFigures`, `mappings`, `fixedAssets`, `taxBroughtForward`, `notes`
`changes`required	`array of string`
`available`required	`object (RollForwardSource)`nullable	The engagement a (re-)roll would bring forward from now.
`available.engagementId`required	`string (uuid)`nullable	Null once that engagement was deleted.
`available.periodStart`required	`string (date)`	example "2026-03-31"
`available.periodEnd`required	`string (date)`	example "2026-03-31"
`available.status`required	`string (EngagementStatus)`nullable	One of: `not_started`, `in_progress`, `submitted`, `returned`, `complete`
`reroll`required	`object (GuardResult)`	Re-roll from prior year: only while the file is Not started or Preparing.
`reroll.allowed`required	`boolean`
`reroll.reasons`required	`array of string`
`reroll.codes`required	`array of string`	Machine-readable reason codes from @tolvi/workflow.

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

Re-roll from prior year

POST/api/v1/engagements/{id}/roll-forward

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

Brings forward again from the client’s previous engagement, replacing what an earlier roll forward brought (this year’s additions and disposals are kept). Only while the file is Not started or Preparing (409 otherwise); 422 when there is no earlier engagement. Never copies sign-offs, review points or evidence; sign-offs on changed sections go stale.

Needs the Preparer role or above. 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}/roll-forward
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

Optional. application/json: object (RollForwardOptions).

What to bring forward from the prior year. Each defaults to true.

Request body for POST /api/v1/engagements/{id}/roll-forward
Field	Type	Description
`priorYearFigures`	`boolean`	Last year’s final TB (draft + posted journals) as this year’s comparatives, kept when this year’s TB is imported.
`mappings`	`boolean`	Last year’s account mappings (codes not yet mapped here).
`fixedAssets`	`boolean`	The fixed asset register: closing cost and depreciation as opening balances, disposed assets left out.
`taxBroughtForward`	`boolean`	Main and special rate pool WDVs and trading losses carried forward.
`notes`	`boolean`	Last year’s variance notes, as hints on the lead schedules (never as this year’s explanations).

Responses

200 OK, `application/json`

Body: object (RollForward).

The year-end roll forward: what was brought forward from the prior year, and whether the prior year changed since.

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

Get where the trial balance would be pulled from

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

Scopes: engagements:read

The source a pull for this engagement reads, without reading it: an engagement keeps the source it is on (its Work queue software); a new one reads the client’s Tolvi Books when linked, else its OAuth connection. Switch an engagement’s source on the client’s Connection tab (PUT /clients/{clientId}/books-link/engagements). 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/pull
Name	In	Type	Description
`id`required	path	`string (uuid)`	Engagement id.

Responses

200 OK, `application/json`

Body: object (TbPullSource).

Which source a pull for this engagement reads: the client’s only source, or, when it has both an OAuth connection and a Tolvi Books link, the one a person chose. Until someone chooses, needsChoice is true and choices lists both: Tolvi asks rather than guessing.

200 OK response for GET /api/v1/engagements/{id}/tb/pull
Field	Type	Description
`engagementId`required	`string (uuid)`
`source`required	`string (BooksSource)`nullable	Null when the client has no connection and no Tolvi Books link. One of: `xero`, `quickbooks`, `sage`, `freeagent`, `tolvi_books`
`label`required	`string`nullable	example "Tolvi Books"
`organisationName`required	`string`nullable
`available`required	`boolean`	A pull can be made now.
`reason`required	`string`nullable	Why not, in words, when it can’t.
`needsChoice`required	`boolean`	The client has both sources and nobody has chosen which its engagements use.
`choices`required	`array of TbPullSourceChoice`	The two to choose from when needsChoice; empty otherwise.
`choices[].use`required	`string (BooksSourcePick)`	What to send as `use` to PUT /clients/{clientId}/books-link/source. One of: `tolvi_books`, `connection`
`choices[].source`required	`string (BooksSource)`	Null when the client has no connection and no Tolvi Books link. One of: `xero`, `quickbooks`, `sage`, `freeagent`, `tolvi_books`
`choices[].label`required	`string`	example "Tolvi Books"
`choices[].organisationName`required	`string`nullable

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

Pull the trial balance from the bookkeeping software

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

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

Pulls again and adds a new immutable trial balance version, exactly as a CSV import would (mappings remembered, journals on missing accounts removed only with confirmJournalRemoval). Send the preview’s hash as expectedHash to refuse (409) if the books changed in between. 409 also when the connection needs reconnecting. 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/pull
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 (TbPullRequest).

Request body for POST /api/v1/engagements/{id}/tb/pull
Field	Type	Description
`expectedHash`	`string`	The hash from the preview. If the books have changed since, nothing is imported (409) and you preview again.
`confirmJournalRemoval`	`boolean`	Confirm removing the journals the preview listed.
`reopenFile`	`boolean`	Required to pull into a file signed off at every stage: the import reopens it for re-approval (reviewer or above). See `TbImport.reopenFile`.

Responses

201 Created, `application/json`

Body: object (TbImportResult).

201 Created response for POST /api/v1/engagements/{id}/tb/pull
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).

Preview pulling the trial balance from the bookkeeping software

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

Scopes: engagements:write and engagements:read

Reads the TB at the period end (and at the prior period end for the prior year column) from the client’s connection, or from the client’s Tolvi Books through the firm’s practice link (both columns at one ledger point, already mapped by the books’ lead lines). Nothing is stored. Same shape as the CSV import preview, plus where it came from. 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/pull/preview
Name	In	Type	Description
`id`required	path	`string (uuid)`	Engagement id.

Responses

200 OK, `application/json`

Body: object (TbPullPreview).

200 OK response for POST /api/v1/engagements/{id}/tb/pull/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.
`provider`required	`string (BooksSource)`	Where the trial balance was read: an OAuth provider, or tolvi_books (the client’s Tolvi Books, through the firm’s practice link). One of: `xero`, `quickbooks`, `sage`, `freeagent`, `tolvi_books`
`sourceLabel`required	`string`	example "Tolvi Books"
`organisationName`required	`string`	The organisation (OAuth) or business (Tolvi Books) read.
`booksThroughSeq`required	`integer`nullable	Tolvi Books: the ledger point read (the last entry included). Null for other sources.
`asAt`required	`string (date)`	The period end: the current year column. example "2026-03-31"
`priorAsAt`required	`string (date)`nullable	The prior period end: the prior year column (null for a first period). example "2026-03-31"

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

Preview sending an engagement’s journals to the client’s Tolvi Books

POST/api/v1/engagements/{id}/books/post-back/preview

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

For an engagement approved at every stage whose trial balance came from the client’s Tolvi Books: the year-end adjustments the books would get (and any earlier post-back reversed because its journal changed), the books’ trial balance at the period end before and after, which must equal the final trial balance to the penny, and the year-end lock it would set. problems says what stands in the way. Nothing is posted. Session only; reviewers and above. 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}/books/post-back/preview
Name	In	Type	Description
`id`required	path	`string (uuid)`	Engagement id.

Responses

200 OK, `application/json`

Body: object (PostBackPreview).

What sending an approved engagement’s posted journals to the client’s Tolvi Books would do: the entries, the books’ trial balance at the period end before and after (which must equal the final trial balance to the penny), and the year-end lock it sets. Nothing is posted.

200 OK response for POST /api/v1/engagements/{id}/books/post-back/preview
Field	Type	Description
`engagementId`required	`string (uuid)`
`businessId`required	`string (uuid)`
`businessName`required	`string`nullable
`periodEnd`required	`string (date)`	example "2026-03-31"
`ready`required	`boolean`	Nothing stands in the way: post-back can go ahead.
`problems`required	`array of string`	What stands in the way, in words.
`entries`required	`array of PostBackEntry`
`entries[].action`required	`string (PostBackAction)`	reverse: undoes an earlier post-back of a journal that has changed or gone. One of: `post`, `reverse`
`entries[].journalRef`required	`string`nullable	example "J4"
`entries[].date`required	`string (date)`	example "2026-03-31"
`entries[].description`required	`string`
`entries[].dateProblem`required	`string`nullable	Why the books would refuse this date (a lock), or null.
`entries[].lines`required	`array of PostBackLine`
`entries[].lines[].accountCode`required	`string`
`entries[].lines[].accountName`required	`string`nullable
`entries[].lines[].amountPence`required	`integer`	Debit positive, in pence.
`unchanged`required	`integer`	Journals the books already hold exactly, from an earlier post-back. at least 0
`missingAccounts`required	`array of PostBackMissingAccount`	Accounts the journals use that the books don’t have (add them in the client’s chart first; nothing is created silently).
`missingAccounts[].code`required	`string`
`missingAccounts[].name`required	`string`
`balances`required	`array of PostBackBalance`
`balances[].code`required	`string`
`balances[].name`required	`string`
`balances[].booksBeforePence`required	`integer`	Integer pence (GBP). The books at the period end now, debit positive.
`balances[].booksAfterPence`required	`integer`	Integer pence (GBP). The books at the period end after post-back.
`balances[].finalPence`required	`integer`	Integer pence (GBP). The engagement’s final balance (draft TB plus posted journals).
`balances[].differencePence`required	`integer`	booksAfterPence less finalPence: nil on every account before post-back can go ahead.
`agrees`required	`boolean`	After post-back the books agree to the final trial balance on every account.
`lockedThrough`required	`string (date)`nullable	The year-end (accountant) lock in force now. example "2026-03-31"
`lockThrough`required	`string (date)`	Post-back locks the books to this date (the period end), unless already locked to it or later. example "2026-03-31"

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

Send an engagement’s journals to the client’s Tolvi Books and lock the year

POST/api/v1/engagements/{id}/books/post-back

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

Posts the preview’s entries to the client’s books as year-end adjustments, through the firm’s practice link (year-end or full bookkeeping access), and locks the books to the period end, in one transaction. 409 with the reasons when the preview isn’t ready (not approved, the TB didn’t come from these books, missing accounts, the books wouldn’t agree, a lock). Safe to repeat: journals the books already hold are not posted again. Never creates a trial balance version. Session only; reviewers and above; not available through the MCP server. 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}/books/post-back
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

Responses

201 Created, `application/json`

Body: object (PostBackResult).

201 Created response for POST /api/v1/engagements/{id}/books/post-back
Field	Type	Description
`engagementId`required	`string (uuid)`
`posted`required	`integer`	at least 0
`reversed`required	`integer`	at least 0
`unchanged`required	`integer`	at least 0
`entrySeqs`required	`array of number`	The ledger entries made, in order.
`lockedThrough`required	`string (date)`	example "2026-03-31"
`lockedNow`required	`boolean`	This call set the lock (false when it was already in place).

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

Engagements

Start an engagement for a client

Parameters

Request body

Responses

201 Created, application/json

Cancel an engagement

Parameters

Responses

200 OK, application/json

Get an engagement overview

Parameters

Responses

200 OK, application/json

List the engagement’s sections and their statuses

Parameters

Responses

200 OK, application/json

Get a section: checklist, issues, sign-off, review points, evidence and next step

Parameters

Responses

200 OK, application/json

Get a lead schedule

Parameters

Responses

200 OK, application/json

List a section’s reconciliations (F bank, H VAT, I payroll)

Parameters

Responses

200 OK, application/json

Get your next step on the engagement and each section

Parameters

Responses

200 OK, application/json

Write or change a variance note

Parameters

Request body

Responses

200 OK, application/json

Remove your variance note

Parameters

Responses

200 OK, application/json

Set a tickmark

Parameters

Request body

Responses

200 OK, application/json

Remove your tickmark

Parameters

Responses

200 OK, application/json

Set a reconciliation: source balance, reconciling items and note

Parameters

Request body

Responses

200 OK, application/json

Mark a checklist step done or N/A, or add a note

Parameters

Request body

Responses

200 OK, application/json

Attach evidence

Parameters

Request body

Responses

201 Created, application/json

Confirm an evidence upload

Parameters

Responses

200 OK, application/json

Get an evidence file’s status

Parameters

Responses

200 OK, application/json

Remove evidence you attached

Parameters

Responses

204 No content

Presign an evidence upload again

201 Created, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

201 Created, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

201 Created, `application/json`

200 OK, `application/json`

200 OK, `application/json`

201 Created, `application/json`