Work

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

List the work queue

GET/api/v1/work

Scopes: work:read

Saved views are relative to the caller ("mine" = engagements where you act next). Needs a person, not an API client. Part of the working_papers product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/work
Name	In	Type	Description
`limit`	query	`integer`	1 to 100; default 50
`cursor`	query	`string`
`q`	query	`string`	Part of the client name. up to 100 characters
`partner`	query	`string (uuid)`
`manager`	query	`string (uuid)`
`actor`	query	`string (uuid)`	Whose turn it is: the person assigned to the current stage.
`entityType`	query	`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`
`yearEndMonth`	query	`integer`	1 to 12
`stage`	query	`string (EngagementStatus)`	One of: `not_started`, `in_progress`, `submitted`, `returned`, `complete`
`software`	query	`string (Software)`	One of: `xero`, `qbo`, `sage`, `freeagent`, `tolvi_books`, `manual`
`dueFrom`	query	`string (date)`	Deadline on or after this date.
`dueTo`	query	`string (date)`	Deadline on or before this date.
`scope`	query	`string (WorkScope)`	mine: engagements where you are preparer, reviewer, manager or partner. Default everyone. One of: `everyone`, `mine`
`sort`	query	`string (WorkSort)`	Default: due. One of: `due`, `client`, `ye`, `rounds`
`view`	query	`string (WorkView)`	Default: mine. todo/later: your turn, due within 120 days / after; stuck: in review over 14 days; at_risk: not yet overdue but likely to miss the deadline at its current stage (Due within 45 days and not started, 30 days preparing, 21 days returned or 14 days in review.); unassigned: open, no preparer (use scope=everyone); changed: open work only. One of: `mine`, `review`, `returned`, `due30`, `overdue`, `changed`, `open`, `all`, `todo`, `later`, `stuck`, `at_risk`, `unassigned`

Responses

200 OK, `application/json`

Body: object (WorkPage).

200 OK response for GET /api/v1/work
Field	Type	Description
`rows`required	`array of WorkRow`
`rows[].id`required	`string (uuid)`	Engagement id.
`rows[].clientId`required	`string (uuid)`
`rows[].clientName`required	`string`
`rows[].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`
`rows[].periodStart`required	`string (date)`	example "2026-03-31"
`rows[].periodEnd`required	`string (date)`	example "2026-03-31"
`rows[].dueDate`required	`string (date)`	Filing deadline. example "2026-03-31"
`rows[].daysLeft`required	`integer`	Days from today (Europe/London) to the deadline; negative when overdue.
`rows[].provisional`required	`boolean`	The deadline is for a tax year and the return may need provisional figures.
`rows[].status`required	`string (EngagementStatus)`	One of: `not_started`, `in_progress`, `submitted`, `returned`, `complete`
`rows[].stageIndex`required	`integer`	at least 0
`rows[].stageName`required	`string`
`rows[].stageCount`required	`integer`	at least 1
`rows[].workflowName`required	`string`
`rows[].currentActorId`required	`string (uuid)`nullable	Who acts next.
`rows[].preparerId`required	`string (uuid)`nullable
`rows[].reviewerId`required	`string (uuid)`nullable
`rows[].managerId`required	`string (uuid)`nullable
`rows[].partnerId`required	`string (uuid)`nullable
`rows[].rounds`required	`integer`	Review rounds (returns to the preparer). at least 0
`rows[].openPoints`required	`integer`	Open review points. at least 0
`rows[].syncState`required	`string (SyncState)`	One of: `in_sync`, `changed`, `expired_token`, `error`, `never_synced`, `manual`
`rows[].software`required	`string (Software)`	One of: `xero`, `qbo`, `sage`, `freeagent`, `tolvi_books`, `manual`
`rows[].lastSyncedAt`required	`string (date-time)`nullable
`rows[].risk`required	`string (RiskLevel)`	One of: `standard`, `high`
`rows[].filedOn`required	`string (date)`nullable	When the accounts were filed (recorded by a person). example "2026-03-31"
`nextCursor`required	`string`nullable	Opaque cursor for the next page (pass as `cursor`); null on the last page.
`pageSize`required	`integer`	The page size that was used. 1 to 100

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

Count each saved view, with the KPI cards

GET/api/v1/work/counts

Scopes: work: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/work/counts
Name	In	Type	Description
`q`	query	`string`	Part of the client name. up to 100 characters
`partner`	query	`string (uuid)`
`manager`	query	`string (uuid)`
`actor`	query	`string (uuid)`	Whose turn it is: the person assigned to the current stage.
`entityType`	query	`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`
`yearEndMonth`	query	`integer`	1 to 12
`stage`	query	`string (EngagementStatus)`	One of: `not_started`, `in_progress`, `submitted`, `returned`, `complete`
`software`	query	`string (Software)`	One of: `xero`, `qbo`, `sage`, `freeagent`, `tolvi_books`, `manual`
`dueFrom`	query	`string (date)`	Deadline on or after this date.
`dueTo`	query	`string (date)`	Deadline on or before this date.
`scope`	query	`string (WorkScope)`	mine: engagements where you are preparer, reviewer, manager or partner. Default everyone. One of: `everyone`, `mine`

Responses

200 OK, `application/json`

Body: object (WorkCounts).

200 OK response for GET /api/v1/work/counts
Field	Type	Description
`views`required	`object (WorkViewCounts)`	Engagements in each saved view.
`views.mine`required	`integer`
`views.review`required	`integer`
`views.returned`required	`integer`
`views.due30`required	`integer`
`views.overdue`required	`integer`
`views.changed`required	`integer`
`views.open`required	`integer`
`views.all`required	`integer`
`views.todo`required	`integer`	Your turn, due within 120 days.
`views.later`required	`integer`	Your turn, due in more than 120 days.
`views.stuck`required	`integer`	In review for more than 14 days.
`views.at_risk`required	`integer`	At risk: not yet overdue, but likely to miss the deadline at its current stage. Due within 45 days and not started, 30 days preparing, 21 days returned or 14 days in review.
`views.unassigned`required	`integer`	Open engagements with no preparer (nobody’s To do until assigned).
`kpis`required	`object (WorkKpis)`
`kpis.due30`required	`integer`
`kpis.overdue`required	`integer`
`kpis.awaitingReview`required	`integer`
`kpis.awaitingMyReview`required	`integer`
`kpis.changed`required	`integer`
`kpis.avgRounds`required	`number`	Average review rounds on complete engagements, to 2 dp.
`kpis.firstTimeRightPct`required	`integer`	0 to 100
`total`required	`integer`	All engagements in the firm, ignoring filters.

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

Count a view grouped by status, deadline day or whose turn it is

GET/api/v1/work/groups

Scopes: work:read

For the Board, Calendar and Workload. Same view, scope and filters as the list. Part of the working_papers product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/work/groups
Name	In	Type	Description
`q`	query	`string`	Part of the client name. up to 100 characters
`partner`	query	`string (uuid)`
`manager`	query	`string (uuid)`
`actor`	query	`string (uuid)`	Whose turn it is: the person assigned to the current stage.
`entityType`	query	`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`
`yearEndMonth`	query	`integer`	1 to 12
`stage`	query	`string (EngagementStatus)`	One of: `not_started`, `in_progress`, `submitted`, `returned`, `complete`
`software`	query	`string (Software)`	One of: `xero`, `qbo`, `sage`, `freeagent`, `tolvi_books`, `manual`
`dueFrom`	query	`string (date)`	Deadline on or after this date.
`dueTo`	query	`string (date)`	Deadline on or before this date.
`scope`	query	`string (WorkScope)`	mine: engagements where you are preparer, reviewer, manager or partner. Default everyone. One of: `everyone`, `mine`
`view`	query	`string (WorkView)`	One of: `mine`, `review`, `returned`, `due30`, `overdue`, `changed`, `open`, `all`, `todo`, `later`, `stuck`, `at_risk`, `unassigned`
`groupBy`required	query	`string (WorkGroupBy)`	One of: `status`, `due`, `actor`

Responses

200 OK, `application/json`

Body: object (WorkGroups).

200 OK response for GET /api/v1/work/groups
Field	Type	Description
`groupBy`required	`string (WorkGroupBy)`	One of: `status`, `due`, `actor`
`groups`required	`array of WorkGroup`
`groups[].key`required	`string`nullable	A status, a deadline (YYYY-MM-DD) or a person id (null: nobody).
`groups[].count`required	`integer`
`total`required	`integer`

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

Start engagements (one or in bulk)

POST/api/v1/work/start

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

Each start is billable (engagement.started, source web/api/mcp, or bulk for several). AI tokens come from the plan’s monthly allowance, not from each start. 402 when billing blocks starting (trial over without billing, or an invoice unpaid for 14 days).

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/work/start
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 (StartEngagements).

Request body for POST /api/v1/work/start
Field	Type	Description
`engagementIds`required	`array of string (uuid)`	1 to 500 items
`workflowId`	`string`	Workflow template id; default: the client’s, else the firm default for the entity type.
`preparerId`	`string (uuid)`
`reviewerId`	`string (uuid)`
`managerId`	`string (uuid)`
`partnerId`	`string (uuid)`
`pullTrialBalance`	`boolean`	Pull each started engagement’s TB from its client’s bookkeeping connection (reported back in tbPulls).
`bringForward`	`object (BringForward)`	What to carry over from the client’s previous engagement (the year-end roll forward). Each defaults to true.
`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, applied when the trial balance is imported.
`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).
`bringForward.clientSteps`	`boolean`	The client’s own checklist steps, added to the firm’s checklists.

Responses

200 OK, `application/json`

Body: object (StartResult).

200 OK response for POST /api/v1/work/start
Field	Type	Description
`started`required	`integer`
`alreadyStarted`required	`array of string (uuid)`
`notFound`required	`array of string (uuid)`
`blocked`required	`string`nullable	Why the rest of a bulk start stopped (billing).
`trialBalancePulled`required	`boolean`	pullTrialBalance was asked for and every started engagement with a connection was pulled (or queued) without failure.
`tbPulls`required	`array of TbPullOutcome`	Per started engagement, when pullTrialBalance was asked for.
`tbPulls[].engagementId`required	`string (uuid)`
`tbPulls[].outcome`required	`string (TbPullOutcomeKind)`	pulled: a new TB version from the books; queued: being pulled in the background (large batches); not_connected: no usable connection; failed: see message. One of: `pulled`, `queued`, `not_connected`, `failed`
`tbPulls[].message`required	`string`nullable
`broughtForward`required	`object (BroughtForward)`	What was carried over, totalled across the engagements started.
`broughtForward.mappings`required	`integer`
`broughtForward.notes`required	`integer`	Variance notes brought forward as hints.
`broughtForward.clientSteps`required	`integer`
`broughtForward.priorYearAccounts`required	`integer`	Accounts in last year’s final TB brought forward as comparatives.
`broughtForward.fixedAssets`required	`integer`	Fixed assets brought forward with their closing balances.
`broughtForward.taxBroughtForward`required	`integer`	Engagements whose pools and losses carried forward were brought forward.
`notified`required	`integer`	Team members told in-app that they were added (the person starting is never told).

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

Record the dates accounts were filed

POST/api/v1/work/filed

Scopes: engagements:write and work:read

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

Request body

Required. application/json: object (MarkFiled).

Request body for POST /api/v1/work/filed
Field	Type	Description
`filed`required	`array of FiledEntry`	1 to 500 items
`filed[].engagementId`required	`string (uuid)`
`filed[].filedOn`required	`string (date)`	example "2026-03-31"

Responses

200 OK, `application/json`

Body: object (MarkFiledResult).

200 OK response for POST /api/v1/work/filed
Field	Type	Description
`updated`required	`integer`

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

List the firm’s people, for filters and assignment

GET/api/v1/work/people

Scopes: work:read

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

Responses

200 OK, `application/json`

Body: array of Person.

200 OK response for GET /api/v1/work/people
Field	Type	Description
`[].id`required	`string (uuid)`
`[].name`required	`string`
`[].initials`required	`string`	example "SP"
`[].role`required	`string (StaffRole)`nullable	One of: `partner`, `manager`, `reviewer`, `preparer`, `admin`
`[].openInRole`	`integer`nullable	Open engagements this person holds in their own role (as preparer, reviewer, manager or partner). Null for practice admin staff. at least 0
`[].capacity`	`integer`nullable	Their role’s capacity (open jobs at once, from the firm’s settings); null for no limit. at least 0

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

Assign engagements in bulk

POST/api/v1/work/assign

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

All or nothing: if any engagement id is not found in this firm, nothing is changed and the response is a 404 problem listing those ids.

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/work/assign
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 (AssignRequest).

Give at least one of preparerId, reviewerId, managerId or partnerId.

Request body for POST /api/v1/work/assign
Field	Type	Description
`engagementIds`required	`array of string (uuid)`	1 to 500 items
`preparerId`	`string (uuid)`
`reviewerId`	`string (uuid)`
`managerId`	`string (uuid)`
`partnerId`	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (AssignResult).

200 OK response for POST /api/v1/work/assign
Field	Type	Description
`updated`required	`integer`	Engagements updated (ids from other firms are ignored).

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

Get one engagement with its workflow timeline

GET/api/v1/work/{id}

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

Responses

200 OK, `application/json`

Body: object (WorkDetail).

200 OK response for GET /api/v1/work/{id}
Field	Type	Description
`id`required	`string (uuid)`	Engagement id.
`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"
`dueDate`required	`string (date)`	Filing deadline. example "2026-03-31"
`daysLeft`required	`integer`	Days from today (Europe/London) to the deadline; negative when overdue.
`provisional`required	`boolean`	The deadline is for a tax year and the return may need provisional figures.
`status`required	`string (EngagementStatus)`	One of: `not_started`, `in_progress`, `submitted`, `returned`, `complete`
`stageIndex`required	`integer`	at least 0
`stageName`required	`string`
`stageCount`required	`integer`	at least 1
`workflowName`required	`string`
`currentActorId`required	`string (uuid)`nullable	Who acts next.
`preparerId`required	`string (uuid)`nullable
`reviewerId`required	`string (uuid)`nullable
`managerId`required	`string (uuid)`nullable
`partnerId`required	`string (uuid)`nullable
`rounds`required	`integer`	Review rounds (returns to the preparer). at least 0
`openPoints`required	`integer`	Open review points. at least 0
`syncState`required	`string (SyncState)`	One of: `in_sync`, `changed`, `expired_token`, `error`, `never_synced`, `manual`
`software`required	`string (Software)`	One of: `xero`, `qbo`, `sage`, `freeagent`, `tolvi_books`, `manual`
`lastSyncedAt`required	`string (date-time)`nullable
`risk`required	`string (RiskLevel)`	One of: `standard`, `high`
`filedOn`required	`string (date)`nullable	When the accounts were filed (recorded by a person). example "2026-03-31"
`workflowTemplateId`required	`string`
`timeline`required	`array of WorkTimelineStep`
`timeline[].name`required	`string`
`timeline[].role`required	`string (StaffRole)`	One of: `partner`, `manager`, `reviewer`, `preparer`, `admin`
`timeline[].assigneeId`required	`string (uuid)`nullable
`timeline[].state`required	`string (TimelineStepState)`	One of: `done`, `now`, `todo`
`timeline[].mustDiffer`required	`boolean`	The assignee must differ from the previous stage’s.

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

Work

List the work queue

Parameters

Responses

200 OK, application/json

Count each saved view, with the KPI cards

Parameters

Responses

200 OK, application/json

Count a view grouped by status, deadline day or whose turn it is

Parameters

Responses

200 OK, application/json

Start engagements (one or in bulk)

Parameters

Request body

Responses

200 OK, application/json

Record the dates accounts were filed

Request body

Responses

200 OK, application/json

List the firm’s people, for filters and assignment

Responses

200 OK, application/json

Assign engagements in bulk

Parameters

Request body

Responses

200 OK, application/json

Get one engagement with its workflow timeline

Parameters

Responses

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`