Tolvi Hub

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

Get the home page

GET/api/v1/hub/home

Scopes: clients:read

How many clients the firm has, your work and your meetings today, in one read. A product’s part is null when you can’t use it or the credential has no scope for it. Part of the hub product: the firm must have it and you must have access to it.

Responses

200 OK, `application/json`

Body: object (HubHome).

The accountant’s home page in one read. A product’s part is null when this person can’t use it.

200 OK response for GET /api/v1/hub/home
Field	Type	Description
`clients`required	`object (HubClientCounts)`
`clients.active`required	`integer`
`clients.prospect`required	`integer`
`clients.former`required	`integer`
`work`required	`object (HubWork)`nullable	Engagements where you are on the team, from Working Papers.
`work.yourTurn`required	`integer`	Your turn, due soon: the Work queue’s to-do view.
`work.toReview`required	`integer`	Waiting for your review.
`work.overdue`required	`integer`
`work.dueIn30Days`required	`integer`
`work.nextDeadlines`required	`array of HubDeadline`	The next five filing deadlines.
`work.nextDeadlines[].engagementId`required	`string (uuid)`
`work.nextDeadlines[].clientId`required	`string (uuid)`
`work.nextDeadlines[].clientName`required	`string`
`work.nextDeadlines[].periodEnd`required	`string (date)`	example "2026-03-31"
`work.nextDeadlines[].dueDate`required	`string (date)`	example "2026-03-31"
`work.nextDeadlines[].daysLeft`required	`integer`	Days from today to the deadline; negative when overdue.
`work.nextDeadlines[].stageName`required	`string`
`suite`	`object (HubSuite)`	Your work across every product you can use. Counts are of work you answer for.
`suite.products`required	`array of WorkItemProduct`	The products counted: those you can use. One of: `working_papers`, `self_assessment`, `accounts`, `corporation_tax`
`suite.yourTurn`required	`integer`	You act next.
`suite.toReview`required	`integer`	Waiting for your review.
`suite.overdue`required	`integer`
`suite.dueIn30Days`required	`integer`
`suite.nextDeadlines`required	`array of SuiteDeadline`	The next five deadlines, each with its product.
`suite.nextDeadlines[].product`required	`string (WorkItemProduct)`	The products counted: those you can use. One of: `working_papers`, `self_assessment`, `accounts`, `corporation_tax`
`suite.nextDeadlines[].itemId`required	`string (uuid)`
`suite.nextDeadlines[].clientId`required	`string (uuid)`
`suite.nextDeadlines[].clientName`required	`string`
`suite.nextDeadlines[].periodLabel`required	`string`	example "2025/26"
`suite.nextDeadlines[].stageLabel`required	`string`
`suite.nextDeadlines[].kind`required	`string (WorkDeadlineKind)`	One of: `companies_house`, `charity_regulator`, `self_assessment`, `ct600`, `ct_payment`
`suite.nextDeadlines[].label`required	`string`
`suite.nextDeadlines[].dueDate`required	`string (date)`	example "2026-03-31"
`suite.nextDeadlines[].daysLeft`required	`integer`	Days from today; negative when overdue.
`meetingsToday`required	`array of HubMeeting`nullable	Note-takers you sent to meetings today (UK time). Null without Meetings.
`meetingsToday[].id`required	`string (uuid)`
`meetingsToday[].title`required	`string`
`meetingsToday[].clientId`required	`string (uuid)`nullable
`meetingsToday[].clientName`required	`string`nullable
`meetingsToday[].joinAt`required	`string (date-time)`
`meetingsToday[].status`required	`string`

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

List work across the products

GET/api/v1/hub/work-items

Scopes: clients:read

Engagements, self assessment returns, accounts and Company Tax Returns in one list, soonest deadline first. Only products you can use and your credential has a scope for are looked in. Complete work is left out unless you ask for it. Accounts count as complete once approved, because filing at Companies House isn’t recorded. Part of the hub product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/hub/work-items
Name	In	Type	Description
`limit`	query	`integer`	1 to 500; default 50
`cursor`	query	`string`
`updatedFrom`	query	`string (date)`	Last changed on or after this date.
`openPoints`	query	`string`	true: has open review points. One of: `true`, `false`
`atRisk`	query	`string`	true: due within 30 days and not yet in review. One of: `true`, `false`
`ownerId`	query	`string`	Who acts next: a person’s id, or none for work nobody holds yet.
`includeCompleted`	query	`string`	One of: `true`, `false`
`overdue`	query	`string`	One of: `true`, `false`
`dueTo`	query	`string (date)`	Any of its deadlines on or before this date.
`dueFrom`	query	`string (date)`	Any of its deadlines on or after this date.
`clientId`	query	`string (uuid)`
`q`	query	`string`	Part of the client name. up to 100 characters
`stage`	query	`string (WorkItemStage)`	One of: `not_started`, `preparing`, `returned`, `in_review`, `ready_to_file`, `filing`, `complete`
`product`	query	`string (WorkItemProduct)`	One of: `working_papers`, `self_assessment`, `accounts`, `corporation_tax`
`scope`	query	`string`	mine: work you prepare or review, or whose client you answer for. turn: you act next. review: waiting for your review. Left out: all. One of: `mine`, `turn`, `review`, `all`

Responses

200 OK, `application/json`

Body: object (WorkItemPage).

Work across the products you can use, soonest deadline first.

200 OK response for GET /api/v1/hub/work-items
Field	Type	Description
`rows`required	`array of WorkItem`
`rows[].product`required	`string (WorkItemProduct)`	The products counted: those you can use. One of: `working_papers`, `self_assessment`, `accounts`, `corporation_tax`
`rows[].id`required	`string (uuid)`	The engagement, return or set of accounts.
`rows[].clientId`required	`string (uuid)`
`rows[].clientName`required	`string`
`rows[].periodLabel`required	`string`	example "YE 31 Mar 2026"
`rows[].periodEnd`required	`string (date)`	example "2026-03-31"
`rows[].dueDate`required	`string (date)`	The filing date, by the rule the product uses. example "2026-03-31"
`rows[].daysLeft`required	`integer`	Days from today; negative when overdue.
`rows[].deadlines`required	`array of WorkDeadline`	Corporation tax has a payment date as well as a filing date.
`rows[].deadlines[].kind`required	`string (WorkDeadlineKind)`	One of: `companies_house`, `charity_regulator`, `self_assessment`, `ct600`, `ct_payment`
`rows[].deadlines[].label`required	`string`	example "CT600 filing"
`rows[].deadlines[].date`required	`string (date)`	example "2026-03-31"
`rows[].status`required	`string`	The product’s own status.
`rows[].stage`required	`string (WorkItemStage)`	One of: `not_started`, `preparing`, `returned`, `in_review`, `ready_to_file`, `filing`, `complete`
`rows[].stageLabel`required	`string`	example "In review"
`rows[].ownerId`required	`string (uuid)`nullable	Who acts next. Null when that is any partner, or nobody yet.
`rows[].ownerName`required	`string`nullable
`rows[].openReviewPoints`required	`integer`
`rows[].updatedAt`required	`string (date-time)`
`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
`totals`required	`object (WorkItemTotals)`
`totals.total`required	`integer`	Every row this filter matches, before paging.
`totals.overdue`required	`integer`
`totals.dueIn30Days`required	`integer`
`totals.workingPapers`required	`integer`
`totals.selfAssessment`required	`integer`
`totals.accounts`required	`integer`
`totals.corporationTax`required	`integer`
`products`required	`array of WorkItemProduct`	The products looked in: those you can use. One of: `working_papers`, `self_assessment`, `accounts`, `corporation_tax`

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

List the dashboard widgets you can see

GET/api/v1/hub/widgets

Scopes: clients:read

The catalogue: each widget’s purpose, where its figures come from, its usual size and who can see it. Widgets for apps you can’t use are left out. Part of the hub product: the firm must have it and you must have access to it.

Responses

200 OK, `application/json`

Body: object (HubWidgetCatalogue).

200 OK response for GET /api/v1/hub/widgets
Field	Type	Description
`widgets`required	`array of HubWidgetDefinition`	Only widgets you can see.
`widgets[].key`required	`string (HubWidgetKey)`	One of: `my_deadlines`, `team_workload`, `deadlines_by_week`, `overdue_at_risk`, `awaiting_review`, `open_review_points`, `work_by_status`, `completed_this_month`, `recent_notifications`, `meetings_today`, `recently_opened`, `changed_source_files`, `ai_tokens`, `imports_in_progress`
`widgets[].title`required	`string`
`widgets[].purpose`required	`string`
`widgets[].dataSource`required	`string`
`widgets[].audience`required	`string`	Who can see it.
`widgets[].w`required	`integer`	Its usual width, in columns of twelve.
`widgets[].h`required	`integer`	Its usual height, in rows.
`widgets[].scopes`required	`array of string`	Whose work it can count; the first is the default. Empty when that doesn’t apply. One of: `mine`, `all`
`widgets[].byProduct`required	`boolean`	Whether it can be narrowed to one app.
`products`required	`array of string`	The apps whose work you can read. One of: `working_papers`, `self_assessment`, `accounts`, `corporation_tax`

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

GET/api/v1/hub/widgets/{key}

Scopes: clients:read

Read from the product that holds them when you ask, so nothing can go stale. Money is in integer pence. Each number says which query on GET /hub/work-items shows the work behind it. Refused with 403 when the widget needs an app or a scope you don’t have. Part of the hub product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/hub/widgets/{key}
Name	In	Type	Description
`key`required	path	`string`	One of: `my_deadlines`, `team_workload`, `deadlines_by_week`, `overdue_at_risk`, `awaiting_review`, `open_review_points`, `work_by_status`, `completed_this_month`, `recent_notifications`, `meetings_today`, `recently_opened`, `changed_source_files`, `ai_tokens`, `imports_in_progress`
`product`	query	`string (WorkItemProduct)`	Only this app’s work. Refused where the widget doesn’t offer it. One of: `working_papers`, `self_assessment`, `accounts`, `corporation_tax`
`scope`	query	`string (HubWidgetScope)`	mine: work you answer for. all: everyone’s. Refused where the widget doesn’t offer it. One of: `mine`, `all`

Responses

200 OK, `application/json`

Body: object (HubWidgetData).

What one widget shows, read from the product that holds it when you ask. Nothing is stored.

200 OK response for GET /api/v1/hub/widgets/{key}
Field	Type	Description
`key`required	`string (HubWidgetKey)`	One of: `my_deadlines`, `team_workload`, `deadlines_by_week`, `overdue_at_risk`, `awaiting_review`, `open_review_points`, `work_by_status`, `completed_this_month`, `recent_notifications`, `meetings_today`, `recently_opened`, `changed_source_files`, `ai_tokens`, `imports_in_progress`
`asOf`required	`string (date)`	example "2026-03-31"
`summary`required	`string`	One sentence saying what it shows: the text alternative for a chart.
`figure`required	`object (HubWidgetFigure)`nullable
`figure.value`required	`integer`	In integer pence when the unit is pence.
`figure.unit`required	`string (HubWidgetFigureUnit)`	One of: `count`, `pence`, `tokens`
`figure.label`required	`string`
`figure.tone`required	`string (HubWidgetFigureTone)`	One of: `neutral`, `warning`, `danger`
`chart`required	`string (HubWidgetChart)`	One of: `none`, `bars`, `stacked_bars`, `columns`
`bars`required	`array of HubWidgetBar`
`bars[].key`required	`string`
`bars[].label`required	`string`
`bars[].value`required	`integer`
`bars[].filter`required	`object (HubWidgetWorkFilter)`nullable	The query on GET /hub/work-items that shows the work behind a number.
`bars[].filter.scope`	`string (HubWidgetWorkFilterScope)`	One of: `mine`, `review`, `all`
`bars[].filter.product`	`string (WorkItemProduct)`	The products counted: those you can use. One of: `working_papers`, `self_assessment`, `accounts`, `corporation_tax`
`bars[].filter.stage`	`string (WorkItemStage)`	One of: `not_started`, `preparing`, `returned`, `in_review`, `ready_to_file`, `filing`, `complete`
`bars[].filter.ownerId`	`string`	A person’s id, or none for work nobody holds.
`bars[].filter.dueFrom`	`string (date)`	example "2026-03-31"
`bars[].filter.dueTo`	`string (date)`	example "2026-03-31"
`bars[].filter.overdue`	`boolean`
`bars[].filter.atRisk`	`boolean`
`bars[].filter.openPoints`	`boolean`
`bars[].filter.includeCompleted`	`boolean`
`bars[].filter.updatedFrom`	`string (date)`	example "2026-03-31"
`bars[].segments`required	`array of HubWidgetSegment`
`bars[].segments[].key`required	`string`
`bars[].segments[].label`required	`string`
`bars[].segments[].value`required	`integer`
`bars[].segments[].filter`required	`object (HubWidgetWorkFilter)`nullable	The query on GET /hub/work-items that shows the work behind a number.
`bars[].segments[].filter.scope`	`string (HubWidgetWorkFilterScope)`	One of: `mine`, `review`, `all`
`bars[].segments[].filter.product`	`string (WorkItemProduct)`	The products counted: those you can use. One of: `working_papers`, `self_assessment`, `accounts`, `corporation_tax`
`bars[].segments[].filter.stage`	`string (WorkItemStage)`	One of: `not_started`, `preparing`, `returned`, `in_review`, `ready_to_file`, `filing`, `complete`
`bars[].segments[].filter.ownerId`	`string`	A person’s id, or none for work nobody holds.
`bars[].segments[].filter.dueFrom`	`string (date)`	example "2026-03-31"
`bars[].segments[].filter.dueTo`	`string (date)`	example "2026-03-31"
`bars[].segments[].filter.overdue`	`boolean`
`bars[].segments[].filter.atRisk`	`boolean`
`bars[].segments[].filter.openPoints`	`boolean`
`bars[].segments[].filter.includeCompleted`	`boolean`
`bars[].segments[].filter.updatedFrom`	`string (date)`	example "2026-03-31"
`legend`required	`array of HubWidgetLegendEntry`
`legend[].key`required	`string`
`legend[].label`required	`string`
`rows`required	`array of HubWidgetRow`	At most twelve. total says how many there are.
`rows[].id`required	`string`
`rows[].title`required	`string`
`rows[].detail`required	`string`
`rows[].date`required	`string (date)`nullable	example "2026-03-31"
`rows[].daysLeft`required	`integer`nullable
`rows[].amountPence`required	`integer`nullable	Integer pence.
`rows[].count`required	`integer`nullable
`rows[].link`required	`object (HubWidgetLink)`nullable	What a row or widget opens.
`rows[].link.kind`required	`string (HubWidgetLinkKind)`	One of: `work_item`, `meeting`, `imports`, `ai_settings`, `notifications`
`rows[].link.product`	`string (WorkItemProduct)`	The products counted: those you can use. One of: `working_papers`, `self_assessment`, `accounts`, `corporation_tax`
`rows[].link.id`	`string (uuid)`
`total`required	`integer`
`filter`required	`object (HubWidgetWorkFilter)`nullable	The work behind the whole widget; null when it isn’t work.
`filter.scope`	`string (HubWidgetWorkFilterScope)`	One of: `mine`, `review`, `all`
`filter.product`	`string (WorkItemProduct)`	The products counted: those you can use. One of: `working_papers`, `self_assessment`, `accounts`, `corporation_tax`
`filter.stage`	`string (WorkItemStage)`	One of: `not_started`, `preparing`, `returned`, `in_review`, `ready_to_file`, `filing`, `complete`
`filter.ownerId`	`string`	A person’s id, or none for work nobody holds.
`filter.dueFrom`	`string (date)`	example "2026-03-31"
`filter.dueTo`	`string (date)`	example "2026-03-31"
`filter.overdue`	`boolean`
`filter.atRisk`	`boolean`
`filter.openPoints`	`boolean`
`filter.includeCompleted`	`boolean`
`filter.updatedFrom`	`string (date)`	example "2026-03-31"
`link`required	`object (HubWidgetLink)`nullable	Where to go for more when it isn’t work.
`link.kind`required	`string (HubWidgetLinkKind)`	One of: `work_item`, `meeting`, `imports`, `ai_settings`, `notifications`
`link.product`	`string (WorkItemProduct)`	The products counted: those you can use. One of: `working_papers`, `self_assessment`, `accounts`, `corporation_tax`
`link.id`	`string (uuid)`
`note`required	`string`nullable	Something the reader should know, such as what’s left out.

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

List dashboards

GET/api/v1/hub/dashboards

Scopes: clients:read

The presets for the apps you can use, your own and those shared with the firm, with which to open first. A preset’s layout leaves out widgets you can’t see. Part of the hub product: the firm must have it and you must have access to it.

Responses

200 OK, `application/json`

Body: object (HubDashboardList).

200 OK response for GET /api/v1/hub/dashboards
Field	Type	Description
`dashboards`required	`array of HubDashboard`	Presets for the apps you can use, then your own and those shared with the firm, by name.
`dashboards[].id`required	`string`	preset:<key> for a preset, otherwise the dashboard’s id. example "preset:my_work"
`dashboards[].name`required	`string`
`dashboards[].description`required	`string`nullable
`dashboards[].kind`required	`string (HubDashboardKind)`	preset: read only, can be duplicated. private: only its creator sees it. firm: everyone in the firm sees it. One of: `preset`, `private`, `firm`
`dashboards[].canEdit`required	`boolean`	Whether you may change or delete it: its creator, or for a shared one a manager and above.
`dashboards[].mine`required	`boolean`
`dashboards[].createdByName`required	`string`nullable	Who made it; null for a preset or someone who has left.
`dashboards[].layout`required	`array of HubLayoutItem`
`dashboards[].layout[].widget`required	`string (HubWidgetKey)`	One of: `my_deadlines`, `team_workload`, `deadlines_by_week`, `overdue_at_risk`, `awaiting_review`, `open_review_points`, `work_by_status`, `completed_this_month`, `recent_notifications`, `meetings_today`, `recently_opened`, `changed_source_files`, `ai_tokens`, `imports_in_progress`
`dashboards[].layout[].w`required	`integer`	Columns of twelve. A phone shows one column. One of: `3`, `4`, `6`, `8`, `12`
`dashboards[].layout[].h`required	`integer`	Rows of the grid. One of: `1`, `2`, `3`
`dashboards[].layout[].scope`	`string (HubWidgetScope)`	mine: work you answer for. all: everyone’s. Left out: the widget’s default. One of: `mine`, `all`
`dashboards[].layout[].product`	`string (WorkItemProduct)`	Only this app’s work. One of: `working_papers`, `self_assessment`, `accounts`, `corporation_tax`
`dashboards[].updatedAt`required	`string (date-time)`nullable
`defaultId`required	`string`	Which to open: your choice while it’s still there, otherwise the preset for your role.

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

Save a new dashboard

POST/api/v1/hub/dashboards

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

Anyone in the firm can make a dashboard, private or shared with the firm. To duplicate one, send its layout under a new name. Signed-in people only. Part of the hub product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/hub/dashboards
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 (CreateHubDashboard).

Request body for POST /api/v1/hub/dashboards
Field	Type	Description
`name`required	`string`	up to 60 characters
`visibility`	`string (HubDashboardVisibility)`	Left out: private. One of: `private`, `firm`
`layout`required	`array of HubLayoutItem`
`layout[].widget`required	`string (HubWidgetKey)`	One of: `my_deadlines`, `team_workload`, `deadlines_by_week`, `overdue_at_risk`, `awaiting_review`, `open_review_points`, `work_by_status`, `completed_this_month`, `recent_notifications`, `meetings_today`, `recently_opened`, `changed_source_files`, `ai_tokens`, `imports_in_progress`
`layout[].w`required	`integer`	Columns of twelve. A phone shows one column. One of: `3`, `4`, `6`, `8`, `12`
`layout[].h`required	`integer`	Rows of the grid. One of: `1`, `2`, `3`
`layout[].scope`	`string (HubWidgetScope)`	mine: work you answer for. all: everyone’s. Left out: the widget’s default. One of: `mine`, `all`
`layout[].product`	`string (WorkItemProduct)`	Only this app’s work. One of: `working_papers`, `self_assessment`, `accounts`, `corporation_tax`

Responses

201 Created, `application/json`

Body: object (HubDashboard).

A preset, or a dashboard someone saved.

201 Created response for POST /api/v1/hub/dashboards
Field	Type	Description
`id`required	`string`	preset:<key> for a preset, otherwise the dashboard’s id. example "preset:my_work"
`name`required	`string`
`description`required	`string`nullable
`kind`required	`string (HubDashboardKind)`	preset: read only, can be duplicated. private: only its creator sees it. firm: everyone in the firm sees it. One of: `preset`, `private`, `firm`
`canEdit`required	`boolean`	Whether you may change or delete it: its creator, or for a shared one a manager and above.
`mine`required	`boolean`
`createdByName`required	`string`nullable	Who made it; null for a preset or someone who has left.
`layout`required	`array of HubLayoutItem`
`layout[].widget`required	`string (HubWidgetKey)`	One of: `my_deadlines`, `team_workload`, `deadlines_by_week`, `overdue_at_risk`, `awaiting_review`, `open_review_points`, `work_by_status`, `completed_this_month`, `recent_notifications`, `meetings_today`, `recently_opened`, `changed_source_files`, `ai_tokens`, `imports_in_progress`
`layout[].w`required	`integer`	Columns of twelve. A phone shows one column. One of: `3`, `4`, `6`, `8`, `12`
`layout[].h`required	`integer`	Rows of the grid. One of: `1`, `2`, `3`
`layout[].scope`	`string (HubWidgetScope)`	mine: work you answer for. all: everyone’s. Left out: the widget’s default. One of: `mine`, `all`
`layout[].product`	`string (WorkItemProduct)`	Only this app’s work. One of: `working_papers`, `self_assessment`, `accounts`, `corporation_tax`
`updatedAt`required	`string (date-time)`nullable

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

Choose your default dashboard

PUT/api/v1/hub/dashboards/default

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

A preset or a dashboard you can see. If it later goes, Home opens the preset for your role. Signed-in people only. Part of the hub product: the firm must have it and you must have access to it.

Request body

Required. application/json: object (SetHubDefaultDashboard).

Request body for PUT /api/v1/hub/dashboards/default
Field	Type	Description
`dashboard`required	`string`	preset:<key> or a dashboard’s id. example "preset:deadlines"

Responses

200 OK, `application/json`

Body: object (SetHubDefaultDashboard).

200 OK response for PUT /api/v1/hub/dashboards/default
Field	Type	Description
`dashboard`required	`string`	preset:<key> or a dashboard’s id. example "preset:deadlines"

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

Change a dashboard

PATCH/api/v1/hub/dashboards/{id}

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

Name, layout or who sees it. Its creator, or for a shared dashboard a manager and above. Others can duplicate it and change their copy. Only its creator can make a shared one private. Signed-in people only. Part of the hub product: the firm must have it and you must have access to it.

Parameters

Parameters for PATCH /api/v1/hub/dashboards/{id}
Name	In	Type	Description
`id`required	path	`string (uuid)`

Request body

Required. application/json: object (UpdateHubDashboard).

Only the fields sent are changed.

Request body for PATCH /api/v1/hub/dashboards/{id}
Field	Type	Description
`name`	`string`	up to 60 characters
`visibility`	`string (HubDashboardVisibility)`	Left out: private. One of: `private`, `firm`
`layout`	`array of HubLayoutItem`
`layout[].widget`required	`string (HubWidgetKey)`	One of: `my_deadlines`, `team_workload`, `deadlines_by_week`, `overdue_at_risk`, `awaiting_review`, `open_review_points`, `work_by_status`, `completed_this_month`, `recent_notifications`, `meetings_today`, `recently_opened`, `changed_source_files`, `ai_tokens`, `imports_in_progress`
`layout[].w`required	`integer`	Columns of twelve. A phone shows one column. One of: `3`, `4`, `6`, `8`, `12`
`layout[].h`required	`integer`	Rows of the grid. One of: `1`, `2`, `3`
`layout[].scope`	`string (HubWidgetScope)`	mine: work you answer for. all: everyone’s. Left out: the widget’s default. One of: `mine`, `all`
`layout[].product`	`string (WorkItemProduct)`	Only this app’s work. One of: `working_papers`, `self_assessment`, `accounts`, `corporation_tax`

Responses

200 OK, `application/json`

Body: object (HubDashboard).

A preset, or a dashboard someone saved.

The fields are as shown above.

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

Delete a dashboard

DELETE/api/v1/hub/dashboards/{id}

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

Its creator, or for a shared dashboard a manager and above. Others can duplicate it and change their copy. Signed-in people only. Part of the hub product: the firm must have it and you must have access to it.

Parameters

Parameters for DELETE /api/v1/hub/dashboards/{id}
Name	In	Type	Description
`id`required	path	`string (uuid)`

Responses

204 No content

Gone.

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

Get one client across the suite

GET/api/v1/clients/{clientId}/overview

Scopes: clients:read

The record, and what each product holds about the client: status, next deadline, latest figures, tax due, review points. Each part comes from its own product, and is null when you can’t use that product or your credential has no scope for it; unavailable names those. Part of the hub product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/clients/{clientId}/overview
Name	In	Type	Description
`clientId`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (ClientOverview).

200 OK response for GET /api/v1/clients/{clientId}/overview
Field	Type	Description
`clientId`required	`string (uuid)`
`today`required	`string (date)`	example "2026-03-31"
`createdAt`required	`string (date-time)`
`record`required	`object (ClientRecord)`	One client’s central record: what the firm holds, and what each product holds about them. A product’s part is null when this person or credential can’t use it.
`record.clientId`required	`string (uuid)`
`record.name`required	`string`
`record.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`
`record.companyNumber`required	`string`nullable
`record.yearEndDay`required	`integer`nullable	1 to 31
`record.yearEndMonth`required	`integer`nullable	1 to 12
`record.status`required	`string (ClientStatus)`	One of: `prospect`, `active`, `former`
`record.services`required	`array of ClientService`	One of: `accounts`, `corporation_tax`, `self_assessment`, `vat`, `payroll`, `bookkeeping`
`record.utr`required	`string`nullable	Unique Taxpayer Reference, ten digits.
`record.vatNumber`required	`string`nullable	example "GB123456789"
`record.payeReference`required	`string`nullable	Employer PAYE reference. example "123/AB456"
`record.registeredAddress`required	`string`nullable
`record.principalActivity`	`string`nullable	Accounts and Corporation Tax default from this.
`record.signatoryName`	`string`nullable	Who usually signs the company’s accounts and returns. Accounts and Corporation Tax default from this.
`record.responsiblePartnerId`required	`string (uuid)`nullable	Set on the record; null when not set.
`record.clientManagerId`required	`string (uuid)`nullable	Set on the record; null when not set.
`record.responsiblePartner`required	`object (ClientRecordPerson)`nullable	Who to show: the record’s, else the latest engagement’s.
`record.responsiblePartner.id`required	`string (uuid)`
`record.responsiblePartner.name`required	`string`
`record.responsiblePartner.source`required	`string (ClientRecordPersonSource)`	client: set on the record. latest_engagement: not set, so taken from the latest engagement’s team. One of: `client`, `latest_engagement`
`record.clientManager`required	`object (ClientRecordPerson)`nullable	Who to show: the record’s, else the latest engagement’s.
`record.clientManager.id`required	`string (uuid)`
`record.clientManager.name`required	`string`
`record.clientManager.source`required	`string (ClientRecordPersonSource)`	client: set on the record. latest_engagement: not set, so taken from the latest engagement’s team. One of: `client`, `latest_engagement`
`record.contacts`required	`array of ClientContact`	Primary first, then by name.
`record.contacts[].id`required	`string (uuid)`
`record.contacts[].name`required	`string`	example "Jo Hartley"
`record.contacts[].role`required	`string`nullable	example "Director"
`record.contacts[].email`required	`string`nullable
`record.contacts[].phone`required	`string`nullable
`record.contacts[].isPrimary`required	`boolean`	The person to contact first. At most one per client.
`record.contacts[].appointedOn`	`string (date)`nullable	For a director: appointed during the year. Blank means throughout. example "2026-03-31"
`record.contacts[].resignedOn`	`string (date)`nullable	For a director: resigned during the year. example "2026-03-31"
`record.notes`required	`string`	The client’s permanent notes.
`record.work`required	`object (ClientRecordWork)`nullable	From Working Papers.
`record.work.current`required	`object (ClientRecordEngagement)`nullable	The latest year end.
`record.work.current.id`required	`string (uuid)`
`record.work.current.periodEnd`required	`string (date)`	example "2026-03-31"
`record.work.current.dueDate`required	`string (date)`	example "2026-03-31"
`record.work.current.status`required	`string`	example "in_progress"
`record.work.current.stageName`required	`string`
`record.work.yearEnds`required	`integer`
`record.work.open`required	`integer`	Engagements not yet complete.
`record.work.nextDueDate`required	`string (date)`nullable	The earliest filing deadline among engagements not yet complete. example "2026-03-31"
`record.meetings`required	`object (ClientRecordMeetings)`nullable	From Meetings.
`record.meetings.total`required	`integer`
`record.meetings.openNextSteps`required	`integer`	Next steps not yet sorted, across this client’s meetings.
`record.meetings.latest`required	`object (ClientRecordMeeting)`nullable
`record.meetings.latest.id`required	`string (uuid)`
`record.meetings.latest.title`required	`string`
`record.meetings.latest.joinAt`required	`string (date-time)`
`record.meetings.latest.status`required	`string`
`record.books`required	`object (ClientRecordBooks)`	Where the client’s books are, from its connection and its Tolvi Books link.
`record.books.connectionLabel`required	`string`nullable	The connected software, if any. example "Xero"
`record.books.connectionStatus`required	`string`nullable	The connection’s state: active, expired, revoked or error.
`record.books.booksLinked`required	`boolean`	The client is linked to a business in Tolvi Books.
`record.books.booksLive`required	`boolean`	The link is live, so the firm can read those books.
`record.selfAssessment`	`object (ClientRecordProductWork)`nullable	From Self Assessment.
`record.selfAssessment.total`required	`integer`
`record.selfAssessment.open`required	`integer`	Not yet filed, or for accounts not yet approved.
`record.selfAssessment.nextDueDate`required	`string (date)`nullable	The earliest filing deadline among those still open. example "2026-03-31"
`record.selfAssessment.latest`required	`object (ClientRecordProductPeriod)`nullable	The latest return or set of accounts.
`record.selfAssessment.latest.id`required	`string (uuid)`
`record.selfAssessment.latest.periodLabel`required	`string`	example "2025/26"
`record.selfAssessment.latest.periodEnd`required	`string (date)`	example "2026-03-31"
`record.selfAssessment.latest.status`required	`string`	The product’s own status.
`record.selfAssessment.latest.stageLabel`required	`string`	example "In review"
`record.selfAssessment.latest.dueDate`required	`string (date)`	example "2026-03-31"
`record.accounts`	`object (ClientRecordProductWork)`nullable	From Accounts.
`record.accounts.total`required	`integer`
`record.accounts.open`required	`integer`	Not yet filed, or for accounts not yet approved.
`record.accounts.nextDueDate`required	`string (date)`nullable	The earliest filing deadline among those still open. example "2026-03-31"
`record.accounts.latest`required	`object (ClientRecordProductPeriod)`nullable	The latest return or set of accounts.
`record.accounts.latest.id`required	`string (uuid)`
`record.accounts.latest.periodLabel`required	`string`	example "2025/26"
`record.accounts.latest.periodEnd`required	`string (date)`	example "2026-03-31"
`record.accounts.latest.status`required	`string`	The product’s own status.
`record.accounts.latest.stageLabel`required	`string`	example "In review"
`record.accounts.latest.dueDate`required	`string (date)`	example "2026-03-31"
`record.corporationTax`	`object (ClientRecordProductWork)`nullable	From Corporation Tax.
`record.corporationTax.total`required	`integer`
`record.corporationTax.open`required	`integer`	Not yet filed, or for accounts not yet approved.
`record.corporationTax.nextDueDate`required	`string (date)`nullable	The earliest filing deadline among those still open. example "2026-03-31"
`record.corporationTax.latest`required	`object (ClientRecordProductPeriod)`nullable	The latest return or set of accounts.
`record.corporationTax.latest.id`required	`string (uuid)`
`record.corporationTax.latest.periodLabel`required	`string`	example "2025/26"
`record.corporationTax.latest.periodEnd`required	`string (date)`	example "2026-03-31"
`record.corporationTax.latest.status`required	`string`	The product’s own status.
`record.corporationTax.latest.stageLabel`required	`string`	example "In review"
`record.corporationTax.latest.dueDate`required	`string (date)`	example "2026-03-31"
`deadlines`required	`array of ClientOverviewDeadline`	Open work’s next deadlines across the products you can use, soonest first.
`deadlines[].product`required	`string`
`deadlines[].itemId`required	`string (uuid)`
`deadlines[].kind`required	`string`
`deadlines[].label`required	`string`
`deadlines[].periodLabel`required	`string`
`deadlines[].dueDate`required	`string (date)`	example "2026-03-31"
`deadlines[].daysLeft`required	`integer`
`unavailable`required	`array of ClientOverviewUnavailable`	Products you can’t use, so their parts are null.
`unavailable[].key`required	`string`
`unavailable[].label`required	`string`
`workingPapers`required	`object (ClientOverviewWorkingPapers)`nullable
`workingPapers.total`required	`integer`
`workingPapers.open`required	`integer`
`workingPapers.nextDueDate`required	`string (date)`nullable	example "2026-03-31"
`workingPapers.latest`required	`object (ClientOverviewLatest)`nullable
`workingPapers.latest.id`required	`string (uuid)`
`workingPapers.latest.periodLabel`required	`string`
`workingPapers.latest.periodEnd`required	`string (date)`	example "2026-03-31"
`workingPapers.latest.status`required	`string`
`workingPapers.latest.stageLabel`required	`string`
`workingPapers.latest.dueDate`required	`string (date)`	example "2026-03-31"
`workingPapers.openReviewPoints`required	`integer`
`workingPapers.periods`required	`array of ClientOverviewPeriod`	The latest six, newest first.
`workingPapers.periods[].id`required	`string (uuid)`
`workingPapers.periods[].label`required	`string`
`workingPapers.periods[].periodEnd`required	`string (date)`	example "2026-03-31"
`workingPapers.periods[].status`required	`string`
`workingPapers.periods[].stageLabel`required	`string`
`workingPapers.periods[].dueDate`required	`string (date)`	example "2026-03-31"
`workingPapers.periods[].daysLeft`required	`integer`
`workingPapers.periods[].openReviewPoints`required	`integer`
`workingPapers.periods[].ownerName`required	`string`nullable
`workingPapers.software`required	`string`nullable
`workingPapers.syncState`required	`string`nullable
`workingPapers.lastSyncedAt`required	`string (date-time)`nullable
`workingPapers.filedOn`required	`string (date)`nullable	example "2026-03-31"
`workingPapers.openPoints`required	`integer`
`accounts`required	`object (ClientOverviewAccounts)`nullable
`accounts.total`required	`integer`
`accounts.open`required	`integer`
`accounts.nextDueDate`required	`string (date)`nullable	example "2026-03-31"
`accounts.latest`required	`object (ClientOverviewLatest)`nullable
`accounts.latest.id`required	`string (uuid)`
`accounts.latest.periodLabel`required	`string`
`accounts.latest.periodEnd`required	`string (date)`	example "2026-03-31"
`accounts.latest.status`required	`string`
`accounts.latest.stageLabel`required	`string`
`accounts.latest.dueDate`required	`string (date)`	example "2026-03-31"
`accounts.openReviewPoints`required	`integer`
`accounts.periods`required	`array of ClientOverviewPeriod`	The latest six, newest first.
`accounts.periods[].id`required	`string (uuid)`
`accounts.periods[].label`required	`string`
`accounts.periods[].periodEnd`required	`string (date)`	example "2026-03-31"
`accounts.periods[].status`required	`string`
`accounts.periods[].stageLabel`required	`string`
`accounts.periods[].dueDate`required	`string (date)`	example "2026-03-31"
`accounts.periods[].daysLeft`required	`integer`
`accounts.periods[].openReviewPoints`required	`integer`
`accounts.periods[].ownerName`required	`string`nullable
`accounts.framework`required	`string`nullable
`accounts.approvedOn`required	`string (date)`nullable	example "2026-03-31"
`accounts.signatoryName`required	`string`nullable
`accounts.figures`required	`object (ClientOverviewAccountsFigures)`nullable
`accounts.figures.turnoverPence`required	`integer`nullable	Pence.
`accounts.figures.profitPence`required	`integer`nullable	Pence. Negative for a loss.
`accounts.figures.netAssetsPence`required	`integer`nullable	Pence.
`accounts.figures.nextStep`required	`string`nullable
`corporationTax`required	`object (ClientOverviewCorporationTax)`nullable
`corporationTax.total`required	`integer`
`corporationTax.open`required	`integer`
`corporationTax.nextDueDate`required	`string (date)`nullable	example "2026-03-31"
`corporationTax.latest`required	`object (ClientOverviewLatest)`nullable
`corporationTax.latest.id`required	`string (uuid)`
`corporationTax.latest.periodLabel`required	`string`
`corporationTax.latest.periodEnd`required	`string (date)`	example "2026-03-31"
`corporationTax.latest.status`required	`string`
`corporationTax.latest.stageLabel`required	`string`
`corporationTax.latest.dueDate`required	`string (date)`	example "2026-03-31"
`corporationTax.openReviewPoints`required	`integer`
`corporationTax.periods`required	`array of ClientOverviewPeriod`	The latest six, newest first.
`corporationTax.periods[].id`required	`string (uuid)`
`corporationTax.periods[].label`required	`string`
`corporationTax.periods[].periodEnd`required	`string (date)`	example "2026-03-31"
`corporationTax.periods[].status`required	`string`
`corporationTax.periods[].stageLabel`required	`string`
`corporationTax.periods[].dueDate`required	`string (date)`	example "2026-03-31"
`corporationTax.periods[].daysLeft`required	`integer`
`corporationTax.periods[].openReviewPoints`required	`integer`
`corporationTax.periods[].ownerName`required	`string`nullable
`corporationTax.taxDuePence`required	`integer`nullable	On the latest return, pence. Negative when overpaid.
`corporationTax.paymentDue`required	`string (date)`nullable	example "2026-03-31"
`corporationTax.filedElsewhereOn`required	`string (date)`nullable	The latest date a person recorded a return as filed outside Tolvi. Not HMRC’s word. example "2026-03-31"
`selfAssessment`required	`object (ClientOverviewSelfAssessment)`nullable
`selfAssessment.total`required	`integer`
`selfAssessment.open`required	`integer`
`selfAssessment.nextDueDate`required	`string (date)`nullable	example "2026-03-31"
`selfAssessment.latest`required	`object (ClientOverviewLatest)`nullable
`selfAssessment.latest.id`required	`string (uuid)`
`selfAssessment.latest.periodLabel`required	`string`
`selfAssessment.latest.periodEnd`required	`string (date)`	example "2026-03-31"
`selfAssessment.latest.status`required	`string`
`selfAssessment.latest.stageLabel`required	`string`
`selfAssessment.latest.dueDate`required	`string (date)`	example "2026-03-31"
`selfAssessment.openReviewPoints`required	`integer`
`selfAssessment.periods`required	`array of ClientOverviewPeriod`	The latest six, newest first.
`selfAssessment.periods[].id`required	`string (uuid)`
`selfAssessment.periods[].label`required	`string`
`selfAssessment.periods[].periodEnd`required	`string (date)`	example "2026-03-31"
`selfAssessment.periods[].status`required	`string`
`selfAssessment.periods[].stageLabel`required	`string`
`selfAssessment.periods[].dueDate`required	`string (date)`	example "2026-03-31"
`selfAssessment.periods[].daysLeft`required	`integer`
`selfAssessment.periods[].openReviewPoints`required	`integer`
`selfAssessment.periods[].ownerName`required	`string`nullable
`selfAssessment.taxDuePence`required	`integer`nullable	On the latest return, pence. Negative when overpaid.
`selfAssessment.returnType`required	`string`nullable
`vat`required	`object (ClientOverviewVat)`nullable
`vat.total`required	`integer`
`vat.vatNumber`required	`string`nullable	On the record.
`vat.latest`required	`object (ClientOverviewVatLatest)`nullable
`vat.latest.id`required	`string (uuid)`
`vat.latest.periodKey`required	`string`
`vat.latest.periodStart`required	`string (date)`	example "2026-03-31"
`vat.latest.periodEnd`required	`string (date)`	example "2026-03-31"
`vat.latest.status`required	`string`
`vat.latest.netDuePence`required	`integer`nullable	Box 5, pence. Negative when reclaimed.
`vat.latest.vrn`required	`string`	The number this return was prepared under.
`books`required	`object (ClientRecordBooks)`nullable	Where the client’s books are, from its connection and its Tolvi Books link.
`books.connectionLabel`required	`string`nullable	The connected software, if any. example "Xero"
`books.connectionStatus`required	`string`nullable	The connection’s state: active, expired, revoked or error.
`books.booksLinked`required	`boolean`	The client is linked to a business in Tolvi Books.
`books.booksLive`required	`boolean`	The link is live, so the firm can read those books.
`meetings`required	`object (ClientRecordMeetings)`nullable	From Meetings.
`meetings.total`required	`integer`
`meetings.openNextSteps`required	`integer`	Next steps not yet sorted, across this client’s meetings.
`meetings.latest`required	`object (ClientRecordMeeting)`nullable
`meetings.latest.id`required	`string (uuid)`
`meetings.latest.title`required	`string`
`meetings.latest.joinAt`required	`string (date-time)`
`meetings.latest.status`required	`string`

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

Get one year end across the products

GET/api/v1/clients/{clientId}/period-chain

Scopes: clients:read

Books, year-end file, accounts, CT return and filing for one year end, each with its status and the id to open. Only products you can use have a step, and only those the client’s type can have. Filing from Tolvi is marked as coming; a date a person recorded is shown as recorded. Part of the hub product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/clients/{clientId}/period-chain
Name	In	Type	Description
`clientId`required	path	`string (uuid)`
`periodEnd`	query	`string (date)`	The year end. Defaults to the latest with work.

Responses

200 OK, `application/json`

Body: object (PeriodChain).

200 OK response for GET /api/v1/clients/{clientId}/period-chain
Field	Type	Description
`clientId`required	`string (uuid)`
`periodEnd`required	`string (date)`nullable	The year end shown. Null when the client has no work yet. example "2026-03-31"
`periods`required	`array of string`	Year ends with work, newest first, the latest six.
`steps`required	`array of PeriodChainStep`	In order. Only products you can use, and only those the client’s type can have.
`steps[].key`required	`string (PeriodChainStepKey)`	One of: `books`, `file`, `accounts`, `corporation_tax`, `filing`
`steps[].label`required	`string`
`steps[].itemId`required	`string (uuid)`nullable	The file, set or return for this year end. Null for books and filing, and when none has been started.
`steps[].stage`required	`string`nullable	not_started, preparing, returned, in_review, ready_to_file, filing or complete. Null when nothing has been started.
`steps[].statusLabel`required	`string`	The status words the product itself shows.
`steps[].dueDate`required	`string (date)`nullable	When the work is due or, on filing, the date a person recorded it as filed outside Tolvi. example "2026-03-31"
`steps[].openReviewPoints`required	`integer`
`steps[].coming`required	`boolean`	Not open in Tolvi yet.

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

Get the client’s central record

GET/api/v1/clients/{clientId}/record

Scopes: clients:read

Details, identifiers, status, services, people and contacts, with what Working Papers, Meetings and the books hold about the client. A product’s part is null when you can’t use it or the credential has no scope for it. Part of the hub product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/clients/{clientId}/record
Name	In	Type	Description
`clientId`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (ClientRecord).

One client’s central record: what the firm holds, and what each product holds about them. A product’s part is null when this person or credential can’t use it.

200 OK response for GET /api/v1/clients/{clientId}/record
Field	Type	Description
`clientId`required	`string (uuid)`
`name`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`
`companyNumber`required	`string`nullable
`yearEndDay`required	`integer`nullable	1 to 31
`yearEndMonth`required	`integer`nullable	1 to 12
`status`required	`string (ClientStatus)`	One of: `prospect`, `active`, `former`
`services`required	`array of ClientService`	One of: `accounts`, `corporation_tax`, `self_assessment`, `vat`, `payroll`, `bookkeeping`
`utr`required	`string`nullable	Unique Taxpayer Reference, ten digits.
`vatNumber`required	`string`nullable	example "GB123456789"
`payeReference`required	`string`nullable	Employer PAYE reference. example "123/AB456"
`registeredAddress`required	`string`nullable
`principalActivity`	`string`nullable	Accounts and Corporation Tax default from this.
`signatoryName`	`string`nullable	Who usually signs the company’s accounts and returns. Accounts and Corporation Tax default from this.
`responsiblePartnerId`required	`string (uuid)`nullable	Set on the record; null when not set.
`clientManagerId`required	`string (uuid)`nullable	Set on the record; null when not set.
`responsiblePartner`required	`object (ClientRecordPerson)`nullable	Who to show: the record’s, else the latest engagement’s.
`responsiblePartner.id`required	`string (uuid)`
`responsiblePartner.name`required	`string`
`responsiblePartner.source`required	`string (ClientRecordPersonSource)`	client: set on the record. latest_engagement: not set, so taken from the latest engagement’s team. One of: `client`, `latest_engagement`
`clientManager`required	`object (ClientRecordPerson)`nullable	Who to show: the record’s, else the latest engagement’s.
`clientManager.id`required	`string (uuid)`
`clientManager.name`required	`string`
`clientManager.source`required	`string (ClientRecordPersonSource)`	client: set on the record. latest_engagement: not set, so taken from the latest engagement’s team. One of: `client`, `latest_engagement`
`contacts`required	`array of ClientContact`	Primary first, then by name.
`contacts[].id`required	`string (uuid)`
`contacts[].name`required	`string`	example "Jo Hartley"
`contacts[].role`required	`string`nullable	example "Director"
`contacts[].email`required	`string`nullable
`contacts[].phone`required	`string`nullable
`contacts[].isPrimary`required	`boolean`	The person to contact first. At most one per client.
`contacts[].appointedOn`	`string (date)`nullable	For a director: appointed during the year. Blank means throughout. example "2026-03-31"
`contacts[].resignedOn`	`string (date)`nullable	For a director: resigned during the year. example "2026-03-31"
`notes`required	`string`	The client’s permanent notes.
`work`required	`object (ClientRecordWork)`nullable	From Working Papers.
`work.current`required	`object (ClientRecordEngagement)`nullable	The latest year end.
`work.current.id`required	`string (uuid)`
`work.current.periodEnd`required	`string (date)`	example "2026-03-31"
`work.current.dueDate`required	`string (date)`	example "2026-03-31"
`work.current.status`required	`string`	example "in_progress"
`work.current.stageName`required	`string`
`work.yearEnds`required	`integer`
`work.open`required	`integer`	Engagements not yet complete.
`work.nextDueDate`required	`string (date)`nullable	The earliest filing deadline among engagements not yet complete. example "2026-03-31"
`meetings`required	`object (ClientRecordMeetings)`nullable	From Meetings.
`meetings.total`required	`integer`
`meetings.openNextSteps`required	`integer`	Next steps not yet sorted, across this client’s meetings.
`meetings.latest`required	`object (ClientRecordMeeting)`nullable
`meetings.latest.id`required	`string (uuid)`
`meetings.latest.title`required	`string`
`meetings.latest.joinAt`required	`string (date-time)`
`meetings.latest.status`required	`string`
`books`required	`object (ClientRecordBooks)`	Where the client’s books are, from its connection and its Tolvi Books link.
`books.connectionLabel`required	`string`nullable	The connected software, if any. example "Xero"
`books.connectionStatus`required	`string`nullable	The connection’s state: active, expired, revoked or error.
`books.booksLinked`required	`boolean`	The client is linked to a business in Tolvi Books.
`books.booksLive`required	`boolean`	The link is live, so the firm can read those books.
`selfAssessment`	`object (ClientRecordProductWork)`nullable	From Self Assessment.
`selfAssessment.total`required	`integer`
`selfAssessment.open`required	`integer`	Not yet filed, or for accounts not yet approved.
`selfAssessment.nextDueDate`required	`string (date)`nullable	The earliest filing deadline among those still open. example "2026-03-31"
`selfAssessment.latest`required	`object (ClientRecordProductPeriod)`nullable	The latest return or set of accounts.
`selfAssessment.latest.id`required	`string (uuid)`
`selfAssessment.latest.periodLabel`required	`string`	example "2025/26"
`selfAssessment.latest.periodEnd`required	`string (date)`	example "2026-03-31"
`selfAssessment.latest.status`required	`string`	The product’s own status.
`selfAssessment.latest.stageLabel`required	`string`	example "In review"
`selfAssessment.latest.dueDate`required	`string (date)`	example "2026-03-31"
`accounts`	`object (ClientRecordProductWork)`nullable	From Accounts.
`accounts.total`required	`integer`
`accounts.open`required	`integer`	Not yet filed, or for accounts not yet approved.
`accounts.nextDueDate`required	`string (date)`nullable	The earliest filing deadline among those still open. example "2026-03-31"
`accounts.latest`required	`object (ClientRecordProductPeriod)`nullable	The latest return or set of accounts.
`accounts.latest.id`required	`string (uuid)`
`accounts.latest.periodLabel`required	`string`	example "2025/26"
`accounts.latest.periodEnd`required	`string (date)`	example "2026-03-31"
`accounts.latest.status`required	`string`	The product’s own status.
`accounts.latest.stageLabel`required	`string`	example "In review"
`accounts.latest.dueDate`required	`string (date)`	example "2026-03-31"
`corporationTax`	`object (ClientRecordProductWork)`nullable	From Corporation Tax.
`corporationTax.total`required	`integer`
`corporationTax.open`required	`integer`	Not yet filed, or for accounts not yet approved.
`corporationTax.nextDueDate`required	`string (date)`nullable	The earliest filing deadline among those still open. example "2026-03-31"
`corporationTax.latest`required	`object (ClientRecordProductPeriod)`nullable	The latest return or set of accounts.
`corporationTax.latest.id`required	`string (uuid)`
`corporationTax.latest.periodLabel`required	`string`	example "2025/26"
`corporationTax.latest.periodEnd`required	`string (date)`	example "2026-03-31"
`corporationTax.latest.status`required	`string`	The product’s own status.
`corporationTax.latest.stageLabel`required	`string`	example "In review"
`corporationTax.latest.dueDate`required	`string (date)`	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).

Change the client’s central record

PATCH/api/v1/clients/{clientId}/record

Scopes: clients:write
Role: Preparer or above

Preparers and above. Refused when an identifier isn’t in the right form, or the responsible partner or client manager doesn’t hold that role in this firm. Doesn’t change who is assigned to any engagement.

Needs the Preparer role or above. Part of the hub product: the firm must have it and you must have access to it.

Parameters

Parameters for PATCH /api/v1/clients/{clientId}/record
Name	In	Type	Description
`clientId`required	path	`string (uuid)`

Request body

Required. application/json: object (UpdateClientRecordRequest).

Send only what changes; null or blank clears a field.

Request body for PATCH /api/v1/clients/{clientId}/record
Field	Type	Description
`name`	`string`	The client’s name. Work in progress reads it from here; an approved return or accounts keep the name they were approved under. up to 200 characters
`entityType`	`string (EntityType)`	What the client is. Decides what new work can start; work already started keeps what it started with. One of: `LTD_FRS102_1A`, `LTD_FRS105_MICRO`, `LLP`, `SOLE_TRADER`, `INDIVIDUAL`, `PARTNERSHIP`, `TRUST`, `ESTATE`, `CHARITY_UNINCORPORATED`, `CHARITY_TRUST`, `CIO`, `SCIO`, `CHARITABLE_COMPANY`
`companyNumber`	`string`nullable	Companies House number.
`yearEndDay`	`integer`nullable	Year end day, sent with yearEndMonth. 1 to 31
`yearEndMonth`	`integer`nullable	Year end month, sent with yearEndDay. 1 to 12
`status`	`string (ClientStatus)`	One of: `prospect`, `active`, `former`
`services`	`array of ClientService`	One of: `accounts`, `corporation_tax`, `self_assessment`, `vat`, `payroll`, `bookkeeping`
`utr`	`string`nullable
`vatNumber`	`string`nullable
`payeReference`	`string`nullable
`registeredAddress`	`string`nullable	up to 500 characters
`principalActivity`	`string`nullable	up to 1000 characters
`signatoryName`	`string`nullable	Who usually signs the company’s accounts and returns. up to 200 characters
`responsiblePartnerId`	`string (uuid)`nullable	Must be a partner in the firm.
`clientManagerId`	`string (uuid)`nullable	Must be a manager or partner in the firm.

Responses

200 OK, `application/json`

Body: object (ClientRecord).

One client’s central record: what the firm holds, and what each product holds about them. A product’s part is null when this person or credential can’t use it.

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 the company facts on the record

GET/api/v1/clients/{clientId}/company-facts

Scopes: clients:read

Registered office, principal activity, signatory and directors, as Accounts and Corporation Tax read them. Part of the hub product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/clients/{clientId}/company-facts
Name	In	Type	Description
`clientId`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (CompanyFacts).

What the client’s record says about the company. Accounts and Corporation Tax start from this; a person chooses to save a change back.

200 OK response for GET /api/v1/clients/{clientId}/company-facts
Field	Type	Description
`name`required	`string`nullable	The client’s name on the record.
`companyNumber`required	`string`nullable	Companies House number on the record.
`registeredOffice`required	`string`nullable
`principalActivity`required	`string`nullable
`signatoryName`required	`string`nullable	The record’s, or the only serving director.
`directors`required	`array of RecordDirector`	Contacts whose role says director.
`directors[].name`required	`string`
`directors[].appointedOn`	`string (date)`	example "2026-03-31"
`directors[].resignedOn`	`string (date)`	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).

Save directors to the record

PUT/api/v1/clients/{clientId}/directors

Scopes: clients:write
Role: Preparer or above

Preparers and above. Adds each person as a contact with the role Director, or updates their dates. Nobody is removed: take someone off in Contacts.

Needs the Preparer role or above. Part of the hub product: the firm must have it and you must have access to it.

Parameters

Parameters for PUT /api/v1/clients/{clientId}/directors
Name	In	Type	Description
`clientId`required	path	`string (uuid)`

Request body

Required. application/json: object (SaveDirectorsRequest).

Adds these people as contacts with the role Director, or updates their dates. Nobody is removed.

Request body for PUT /api/v1/clients/{clientId}/directors
Field	Type	Description
`directors`required	`array of RecordDirector`
`directors[].name`required	`string`
`directors[].appointedOn`	`string (date)`	example "2026-03-31"
`directors[].resignedOn`	`string (date)`	example "2026-03-31"

Responses

200 OK, `application/json`

Body: object (CompanyFacts).

What the client’s record says about the company. Accounts and Corporation Tax start from this; a person chooses to save a change back.

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

Add a contact

POST/api/v1/clients/{clientId}/contacts

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

Preparers and above. The client’s first contact becomes its primary contact.

Needs the Preparer role or above. Part of the hub product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/clients/{clientId}/contacts
Name	In	Type	Description
`clientId`required	path	`string (uuid)`
`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 (CreateClientContactRequest).

Request body for POST /api/v1/clients/{clientId}/contacts
Field	Type	Description
`name`required	`string`	1 to 200 characters
`role`	`string`nullable	up to 100 characters
`email`	`string (email)`nullable
`phone`	`string`nullable	up to 40 characters
`isPrimary`	`boolean`	The client’s first contact is primary anyway. Setting this moves it from whoever had it.
`appointedOn`	`string (date)`nullable	example "2026-03-31"
`resignedOn`	`string (date)`nullable	example "2026-03-31"

Responses

201 Created, `application/json`

Body: object (ClientContact).

A person at a client.

201 Created response for POST /api/v1/clients/{clientId}/contacts
Field	Type	Description
`id`required	`string (uuid)`
`name`required	`string`	example "Jo Hartley"
`role`required	`string`nullable	example "Director"
`email`required	`string`nullable
`phone`required	`string`nullable
`isPrimary`required	`boolean`	The person to contact first. At most one per client.
`appointedOn`	`string (date)`nullable	For a director: appointed during the year. Blank means throughout. example "2026-03-31"
`resignedOn`	`string (date)`nullable	For a director: resigned during the year. example "2026-03-31"

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

Change a contact

PATCH/api/v1/clients/{clientId}/contacts/{contactId}

Scopes: clients:write
Role: Preparer or above

Preparers and above.

Needs the Preparer role or above. Part of the hub product: the firm must have it and you must have access to it.

Parameters

Parameters for PATCH /api/v1/clients/{clientId}/contacts/{contactId}
Name	In	Type	Description
`clientId`required	path	`string (uuid)`
`contactId`required	path	`string (uuid)`

Request body

Required. application/json: object (UpdateClientContactRequest).

Send only what changes.

Request body for PATCH /api/v1/clients/{clientId}/contacts/{contactId}
Field	Type	Description
`name`	`string`	1 to 200 characters
`role`	`string`nullable	up to 100 characters
`email`	`string (email)`nullable
`phone`	`string`nullable	up to 40 characters
`isPrimary`	`boolean`	Setting this moves it from whoever had it.
`appointedOn`	`string (date)`nullable	example "2026-03-31"
`resignedOn`	`string (date)`nullable	example "2026-03-31"

Responses

200 OK, `application/json`

Body: object (ClientContact).

A person at a client.

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 a contact

DELETE/api/v1/clients/{clientId}/contacts/{contactId}

Scopes: clients:write
Role: Preparer or above

Preparers and above. If it was the primary contact, the next by name takes over.

Needs the Preparer role or above. Part of the hub product: the firm must have it and you must have access to it.

Parameters

Parameters for DELETE /api/v1/clients/{clientId}/contacts/{contactId}
Name	In	Type	Description
`clientId`required	path	`string (uuid)`
`contactId`required	path	`string (uuid)`

Responses

204 No content

Removed.

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

Tolvi Hub

Get the home page

Responses

200 OK, application/json

List work across the products

Parameters

Responses

200 OK, application/json

List the dashboard widgets you can see

Responses

200 OK, application/json

Get one widget’s figures

Parameters

Responses

200 OK, application/json

List dashboards

Responses

200 OK, application/json

Save a new dashboard

Parameters

Request body

Responses

201 Created, application/json

Choose your default dashboard

Request body

Responses

200 OK, application/json

Change a dashboard

Parameters

Request body

Responses

200 OK, application/json

Delete a dashboard

Parameters

Responses

204 No content

Get one client across the suite

Parameters

Responses

200 OK, application/json

Get one year end across the products

Parameters

Responses

200 OK, application/json

Get the client’s central record

Parameters

Responses

200 OK, application/json

Change the client’s central record

Parameters

Request body

Responses

200 OK, application/json

Get the company facts on the record

Parameters

Responses

200 OK, application/json

Save directors to the record

Parameters

Request body

Responses

200 OK, application/json

Add a contact

Parameters

Request body

Responses

201 Created, application/json

Change a contact

Parameters

Request body

Responses

200 OK, application/json

Remove a contact

Parameters

Responses

204 No content

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`

200 OK, `application/json`

201 Created, `application/json`

200 OK, `application/json`