Suite

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

Search clients, engagements, sections, meetings and people

GET/api/v1/search

Scopes: clients:read

Matches part of a name (or a Companies House number for clients and engagements), a few per group, best matches first. A group is searched only when you may read it: engagements need engagements:read and Working Papers; sections need an engagementId as well; meetings need meetings:read and Meetings; people need settings:read. Read-only, and limited like every other read.

Parameters

Parameters for GET /api/v1/search
Name	In	Type	Description
`limit`	query	`integer`	Most results per group. 1 to 20; default 5
`engagementId`	query	`string (uuid)`	Also search the sections of this engagement.
`q`required	query	`string`	What to look for. 1 to 100 characters

Responses

200 OK, `application/json`

Body: object (SearchResults).

Matches grouped by kind. Each group is searched only when you may read it: engagements and sections need engagements:read and Working Papers, meetings need meetings:read and Meetings, people need settings:read. searched lists the groups that were.

200 OK response for GET /api/v1/search
Field	Type	Description
`query`required	`string`
`searched`required	`array of SearchGroup`	The groups searched for this caller. One of: `clients`, `engagements`, `sections`, `meetings`, `people`, `taxReturns`, `companyTaxReturns`, `accountsSets`
`clients`required	`array of SearchClient`
`clients[].id`required	`string (uuid)`
`clients[].name`required	`string`
`clients[].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`
`clients[].companyNumber`required	`string`nullable
`engagements`required	`array of SearchEngagement`
`engagements[].id`required	`string (uuid)`
`engagements[].clientId`required	`string (uuid)`
`engagements[].clientName`required	`string`
`engagements[].periodEnd`required	`string (date)`	example "2026-03-31"
`engagements[].stageName`required	`string`	The current workflow stage, e.g. "Preparation".
`engagements[].status`required	`string (EngagementStatus)`	One of: `not_started`, `in_progress`, `submitted`, `returned`, `complete`
`sections`required	`array of SearchSection`
`sections[].engagementId`required	`string (uuid)`
`sections[].code`required	`string`	example "F"
`sections[].name`required	`string`	example "Bank & cash"
`meetings`required	`array of SearchMeeting`
`meetings[].id`required	`string (uuid)`
`meetings[].title`required	`string`
`meetings[].clientName`required	`string`nullable
`meetings[].joinAt`required	`string (date-time)`
`meetings[].status`required	`string (MeetingStatus)`	One of: `scheduling`, `scheduled`, `joining`, `waiting_room`, `in_call`, `recording`, `processing`, `ready`, `failed`, `cancelled`
`people`required	`array of SearchPerson`
`people[].id`required	`string (uuid)`
`people[].name`required	`string`
`people[].email`required	`string`
`people[].staffRole`required	`string (StaffRole)`nullable	One of: `partner`, `manager`, `reviewer`, `preparer`, `admin`
`taxReturns`	`array of SearchWorkItem`	Needs self_assessment:read and Self Assessment.
`taxReturns[].id`required	`string (uuid)`
`taxReturns[].clientId`required	`string (uuid)`
`taxReturns[].clientName`required	`string`
`taxReturns[].periodLabel`required	`string`	example "2025/26"
`taxReturns[].status`required	`string`	The product’s own status.
`taxReturns[].stageLabel`required	`string`	example "In review"
`taxReturns[].dueDate`required	`string (date)`	example "2026-03-31"
`companyTaxReturns`	`array of SearchWorkItem`	Needs corporation_tax:read and Corporation Tax.
`companyTaxReturns[].id`required	`string (uuid)`
`companyTaxReturns[].clientId`required	`string (uuid)`
`companyTaxReturns[].clientName`required	`string`
`companyTaxReturns[].periodLabel`required	`string`	example "2025/26"
`companyTaxReturns[].status`required	`string`	The product’s own status.
`companyTaxReturns[].stageLabel`required	`string`	example "In review"
`companyTaxReturns[].dueDate`required	`string (date)`	example "2026-03-31"
`accountsSets`	`array of SearchWorkItem`	Needs accounts:read and Accounts.
`accountsSets[].id`required	`string (uuid)`
`accountsSets[].clientId`required	`string (uuid)`
`accountsSets[].clientName`required	`string`
`accountsSets[].periodLabel`required	`string`	example "2025/26"
`accountsSets[].status`required	`string`	The product’s own status.
`accountsSets[].stageLabel`required	`string`	example "In review"
`accountsSets[].dueDate`required	`string (date)`	example "2026-03-31"

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

List the products in the Tolvi suite

GET/api/v1/products

Scopes: work:read

The catalogue, whether or not your firm has each one.

Responses

200 OK, `application/json`

Body: array of Product.

A product in the Tolvi suite.

200 OK response for GET /api/v1/products
Field	Type	Description
`[].key`required	`string`	Stable id, e.g. working_papers or meetings. pattern ^[a-z][a-z0-9_]{1,39}$; example "meetings"
`[].name`required	`string`	example "Meetings"
`[].description`required	`string`
`[].path`required	`string`	Where the product opens in the web app. example "/meetings"
`[].icon`required	`string`	A lucide icon name. example "lucideVideo"
`[].status`required	`string (ProductStatus)`	beta: available, still changing. retired: no longer offered. One of: `available`, `beta`, `retired`
`[].selfServeTrial`required	`boolean`	A firm admin can start a trial without asking Tolvi.
`[].trialDays`required	`integer`	Length of a self-serve trial. at least 0

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

List the products you can open in this firm

GET/api/v1/me/products

Scopes: work:read

What the app switcher shows. A product the firm has only for people given access is listed only if you have been.

Responses

200 OK, `application/json`

Body: array of MyProduct.

A product you can open in this firm.

200 OK response for GET /api/v1/me/products
Field	Type	Description
`[].key`required	`string`	Stable id, e.g. working_papers or meetings. pattern ^[a-z][a-z0-9_]{1,39}$; example "meetings"
`[].name`required	`string`	example "Meetings"
`[].description`required	`string`
`[].path`required	`string`	Where the product opens in the web app. example "/meetings"
`[].icon`required	`string`	A lucide icon name. example "lucideVideo"
`[].status`required	`string (ProductStatus)`	beta: available, still changing. retired: no longer offered. One of: `available`, `beta`, `retired`
`[].selfServeTrial`required	`boolean`	A firm admin can start a trial without asking Tolvi.
`[].trialDays`required	`integer`	Length of a self-serve trial. at least 0
`[].firmStatus`required	`string (FirmProductStatus)`	The firm’s hold on it. suspended: read-only until billing is sorted out. One of: `active`, `trial`, `suspended`
`[].use`required	`string (ProductUse)`	read_only while the product is suspended. One of: `full`, `read_only`
`[].trialEndsAt`required	`string (date-time)`nullable

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

List the products your firm has

GET/api/v1/firm/products

Scopes: work:read

With status, access mode, trial end and how many people can use each.

Responses

200 OK, `application/json`

Body: array of FirmProduct.

A product the firm has, and who can use it.

200 OK response for GET /api/v1/firm/products
Field	Type	Description
`[].key`required	`string`	pattern ^[a-z][a-z0-9_]{1,39}$; example "meetings"
`[].name`required	`string`
`[].path`required	`string`
`[].icon`required	`string`
`[].productStatus`required	`string (ProductStatus)`	beta: available, still changing. retired: no longer offered. One of: `available`, `beta`, `retired`
`[].status`required	`string (FirmProductStatus)`	Null: the firm doesn’t have Meetings. One of: `active`, `trial`, `suspended`
`[].accessMode`required	`string (ProductAccessMode)`	everyone: every member of the firm. assigned: only people given access. One of: `everyone`, `assigned`
`[].source`required	`string (FirmProductSource)`	included: part of every firm. trial, subscription, or manual (set by Tolvi). One of: `included`, `trial`, `subscription`, `manual`
`[].startedAt`required	`string (date-time)`
`[].trialEndsAt`required	`string (date-time)`nullable
`[].peopleWithAccess`required	`integer`	at least 0

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

Start a trial of a product

POST/api/v1/firm/products/{key}

Scopes: settings:admin and work:read
Role: Firm admin
Access: A signed-in Tolvi session only, never an API token.
Retries: Send an Idempotency-Key to make retries safe.

Only for products the catalogue marks self-serve. You are given access to it straight away.

Parameters

Parameters for POST /api/v1/firm/products/{key}
Name	In	Type	Description
`key`required	path	`string`	pattern ^[a-z][a-z0-9_]{1,39}$
`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 (FirmProduct).

A product the firm has, and who can use it.

201 Created response for POST /api/v1/firm/products/{key}
Field	Type	Description
`key`required	`string`	pattern ^[a-z][a-z0-9_]{1,39}$; example "meetings"
`name`required	`string`
`path`required	`string`
`icon`required	`string`
`productStatus`required	`string (ProductStatus)`	beta: available, still changing. retired: no longer offered. One of: `available`, `beta`, `retired`
`status`required	`string (FirmProductStatus)`	Null: the firm doesn’t have Meetings. One of: `active`, `trial`, `suspended`
`accessMode`required	`string (ProductAccessMode)`	everyone: every member of the firm. assigned: only people given access. One of: `everyone`, `assigned`
`source`required	`string (FirmProductSource)`	included: part of every firm. trial, subscription, or manual (set by Tolvi). One of: `included`, `trial`, `subscription`, `manual`
`startedAt`required	`string (date-time)`
`trialEndsAt`required	`string (date-time)`nullable
`peopleWithAccess`required	`integer`	at least 0

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 who can use a product

PATCH/api/v1/firm/products/{key}

Scopes: settings:admin and work:read
Role: Firm admin
Access: A signed-in Tolvi session only, never an API token.

everyone: every member of the firm. assigned: only people given access (their grants are kept either way).

Parameters

Parameters for PATCH /api/v1/firm/products/{key}
Name	In	Type	Description
`key`required	path	`string`	pattern ^[a-z][a-z0-9_]{1,39}$

Request body

Required. application/json: object (FirmProductPatch).

Request body for PATCH /api/v1/firm/products/{key}
Field	Type	Description
`accessMode`required	`string (ProductAccessMode)`	everyone: every member of the firm. assigned: only people given access. One of: `everyone`, `assigned`

Responses

200 OK, `application/json`

Body: object (FirmProduct).

A product the firm has, and who can 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 people × products view

GET/api/v1/product-access

Scopes: settings:admin
Role: Firm admin

The firm’s products, and for each person which they can use and which they have been given.

Responses

200 OK, `application/json`

Body: object (ProductAccessMatrix).

The firm’s products and, for each person, which they can use.

200 OK response for GET /api/v1/product-access
Field	Type	Description
`products`required	`array of FirmProduct`
`products[].key`required	`string`	pattern ^[a-z][a-z0-9_]{1,39}$; example "meetings"
`products[].name`required	`string`
`products[].path`required	`string`
`products[].icon`required	`string`
`products[].productStatus`required	`string (ProductStatus)`	beta: available, still changing. retired: no longer offered. One of: `available`, `beta`, `retired`
`products[].status`required	`string (FirmProductStatus)`	Null: the firm doesn’t have Meetings. One of: `active`, `trial`, `suspended`
`products[].accessMode`required	`string (ProductAccessMode)`	everyone: every member of the firm. assigned: only people given access. One of: `everyone`, `assigned`
`products[].source`required	`string (FirmProductSource)`	included: part of every firm. trial, subscription, or manual (set by Tolvi). One of: `included`, `trial`, `subscription`, `manual`
`products[].startedAt`required	`string (date-time)`
`products[].trialEndsAt`required	`string (date-time)`nullable
`products[].peopleWithAccess`required	`integer`	at least 0
`members`required	`array of ProductAccessMember`
`members[].userId`required	`string (uuid)`
`members[].name`required	`string`
`members[].email`required	`string (email)`
`members[].initials`required	`string`	example "GL"
`members[].role`required	`string (MembershipRole)`	One of: `owner`, `admin`, `staff`
`members[].staffRole`required	`string (StaffRole)`nullable	One of: `partner`, `manager`, `reviewer`, `preparer`, `admin`
`members[].isAdmin`required	`boolean`
`members[].products`required	`array of string`	Product keys they can open now.
`members[].assigned`required	`array of string`	Product keys they have been given, whatever the access mode.

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

Give someone access to a product

PUT/api/v1/product-access/{key}/members/{userId}

Scopes: settings:admin and settings:admin
Role: Firm admin
Access: A signed-in Tolvi session only, never an API token.

Idempotent. Takes effect at once.

Parameters

Parameters for PUT /api/v1/product-access/{key}/members/{userId}
Name	In	Type	Description
`key`required	path	`string`	pattern ^[a-z][a-z0-9_]{1,39}$
`userId`required	path	`string (uuid)`

Responses

204 No content

They have access.

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

Take away someone’s access to a product

DELETE/api/v1/product-access/{key}/members/{userId}

Scopes: settings:admin and settings:admin
Role: Firm admin
Access: A signed-in Tolvi session only, never an API token.

Idempotent. In everyone mode they keep using it until the mode is assigned.

Parameters

Parameters for DELETE /api/v1/product-access/{key}/members/{userId}
Name	In	Type	Description
`key`required	path	`string`	pattern ^[a-z][a-z0-9_]{1,39}$
`userId`required	path	`string (uuid)`

Responses

204 No content

They no longer have it.

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

Suite

Search clients, engagements, sections, meetings and people

Parameters

Responses

200 OK, application/json

List the products in the Tolvi suite

Responses

200 OK, application/json

List the products you can open in this firm

Responses

200 OK, application/json

List the products your firm has

Responses

200 OK, application/json

Start a trial of a product

Parameters

Responses

201 Created, application/json

Change who can use a product

Parameters

Request body

Responses

200 OK, application/json

Get the people × products view

Responses

200 OK, application/json

Give someone access to a product

Parameters

Responses

204 No content

Take away someone’s access to a product

Parameters

Responses

204 No content

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`