Clients

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

List a client’s links

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

Scopes: clients:read

Companies this person is connected with, or people connected with this company.

Parameters

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

Responses

200 OK, `application/json`

Body: object (ClientLinkList).

200 OK response for GET /api/v1/clients/{clientId}/links
Field	Type	Description
`items`required	`array of ClientLink`
`items[].id`required	`string (uuid)`
`items[].personClientId`required	`string (uuid)`
`items[].personName`required	`string`
`items[].companyClientId`required	`string (uuid)`
`items[].companyName`required	`string`
`items[].isDirector`required	`boolean`
`items[].isShareholder`required	`boolean`
`items[].shareholdingBps`required	`integer`nullable
`items[].nameInCompanyRecords`required	`string`nullable
`items[].createdAt`required	`string (date-time)`

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

Link a person and a company

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

Scopes: clients:write

Both are this firm’s clients; the company must be a limited company. A link only ever produces suggestions.

Parameters

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

Request body

Required. application/json: object (CreateClientLinkRequest).

A person is a director or shareholder of a company. Both are clients of the firm.

Request body for POST /api/v1/clients/{clientId}/links
Field	Type	Description
`otherClientId`required	`string (uuid)`
`thisClientIs`required	`string (ClientLinkSide)`	One of: `person`, `company`
`isDirector`	`boolean`
`isShareholder`	`boolean`
`shareholdingBps`	`integer`nullable	Share of the dividends, in basis points: 5000 is 50%.
`nameInCompanyRecords`	`string`nullable	The name on the company’s accounts and CT600A, if it isn’t the client’s.

Responses

201 Created, `application/json`

Body: object (ClientLink).

201 Created response for POST /api/v1/clients/{clientId}/links
Field	Type	Description
`id`required	`string (uuid)`
`personClientId`required	`string (uuid)`
`personName`required	`string`
`companyClientId`required	`string (uuid)`
`companyName`required	`string`
`isDirector`required	`boolean`
`isShareholder`required	`boolean`
`shareholdingBps`required	`integer`nullable
`nameInCompanyRecords`required	`string`nullable
`createdAt`required	`string (date-time)`

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

Change a link

PATCH/api/v1/clients/{clientId}/links/{linkId}

Scopes: clients:write

Parameters

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

Request body

Required. application/json: object (UpdateClientLinkRequest).

Request body for PATCH /api/v1/clients/{clientId}/links/{linkId}
Field	Type	Description
`isDirector`	`boolean`
`isShareholder`	`boolean`
`shareholdingBps`	`integer`nullable
`nameInCompanyRecords`	`string`nullable

Responses

200 OK, `application/json`

Body: object (ClientLink).

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 link

DELETE/api/v1/clients/{clientId}/links/{linkId}

Scopes: clients:write

Figures already accepted stay where they are.

Parameters

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

Responses

204 No content

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

What a linked client’s other work suggests here

GET/api/v1/cross-product-suggestions

Scopes: clients:read

Reads only, and only from products this person holds. Each comes with its source.

Parameters

Parameters for GET /api/v1/cross-product-suggestions
Name	In	Type	Description
`id`required	query	`string (uuid)`	The return or set of accounts.
`product`required	query	`string`	One of: `self_assessment`, `corporation_tax`, `accounts`

Responses

200 OK, `application/json`

Body: object (CrossProductSuggestions).

200 OK response for GET /api/v1/cross-product-suggestions
Field	Type	Description
`items`required	`array of CrossProductSuggestion`
`items[].key`required	`string`
`items[].kind`required	`string (CrossProductSuggestionKind)`	One of: `dividends`, `loan`, `partnership`, `accounts`
`items[].headline`required	`string`
`items[].source`required	`string`	Where it comes from, in words: product, client and period.
`items[].note`required	`string`	What to check first.
`items[].suggestedPence`required	`integer`nullable	The suggested figure in integer pence. Null when it can’t be worked out, such as with no shareholding on the link.
`items[].currentPence`required	`integer`nullable	What the target holds now, in integer pence.
`items[].writesFigure`required	`boolean`	Accepting writes a figure to the target. If false, accepting only records that a person has dealt with it.
`items[].target`required	`string`nullable	The box or field it would change.
`items[].fingerprint`required	`string`
`decisions`required	`array of CrossProductDecision`	What people have decided already, kept for the record.
`decisions[].key`required	`string`
`decisions[].decision`required	`string (CrossProductDecisionKind)`	One of: `accepted`, `dismissed`
`decisions[].amountPence`required	`integer`nullable	Integer pence (GBP).
`decisions[].source`required	`string`
`decisions[].decidedByName`required	`string`nullable
`decisions[].decidedAt`required	`string (date-time)`
`hiddenSources`required	`integer`	Sources this person can’t see because they don’t hold that product, so what’s from them isn’t shown.

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

Accept or dismiss a suggestion

POST/api/v1/cross-product-suggestions/decide

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

A signed-in person only, never an API key or connected assistant. Accepting writes through the target product’s own save, so an approved return goes back to draft. The decision is kept. A suggestion comes back if its source changes.

Request body

Required. application/json: object (DecideCrossProductSuggestionRequest).

Request body for POST /api/v1/cross-product-suggestions/decide
Field	Type	Description
`product`required	`string (CrossProductTarget)`	One of: `self_assessment`, `corporation_tax`, `accounts`
`id`required	`string (uuid)`
`key`required	`string`
`fingerprint`required	`string`
`decision`required	`string (CrossProductDecisionKind)`	One of: `accepted`, `dismissed`
`amountPence`	`integer`	Integer pence: what to put in, if the person changed the figure.

Responses

200 OK, `application/json`

Body: object (CrossProductSuggestions).

The fields are as shown above.

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

List or search clients

GET/api/v1/clients

Scopes: clients:read

Sorted by name. Each row has the latest engagement’s partner and manager, the bookkeeping connection and the next filing deadline.

Parameters

Parameters for GET /api/v1/clients
Name	In	Type	Description
`limit`	query	`integer`	1 to 100; default 50
`cursor`	query	`string`
`status`	query	`string (ClientStatus)`	One of: `prospect`, `active`, `former`
`connection`	query	`string (ClientConnectionState)`	One of: `connected`, `reconnect`, `error`, `not_connected`
`yearEndMonth`	query	`integer`	Year end month (the client’s own, or its latest engagement’s). 1 to 12
`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`
`software`	query	`string (Software)`	One of: `xero`, `qbo`, `sage`, `freeagent`, `tolvi_books`, `manual`
`manager`	query	`string (uuid)`
`partner`	query	`string (uuid)`	Partner on any of the client’s engagements.
`q`	query	`string`	Part of the client name or company number. up to 100 characters

Responses

200 OK, `application/json`

Body: object (ClientPage).

200 OK response for GET /api/v1/clients
Field	Type	Description
`rows`required	`array of Client`
`rows[].id`required	`string (uuid)`
`rows[].firmId`required	`string (uuid)`
`rows[].name`required	`string`	example "Hartley Joinery Ltd"
`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[].companyNumber`required	`string`nullable	Companies House number. example "01234567"
`rows[].yearEndDay`required	`integer`nullable	Financial year end day (with yearEndMonth); null when not known. 1 to 31
`rows[].yearEndMonth`required	`integer`nullable	Financial year end month (1-12). 1 to 12
`rows[].createdAt`required	`string (date-time)`
`rows[].status`	`string (ClientStatus)`	Prospect, active or former. One of: `prospect`, `active`, `former`
`rows[].latestPeriodEnd`	`string (date)`nullable	Lists only: the period end of the client’s latest engagement (null when it has none), so a year end can be shown when yearEndDay/yearEndMonth are not set. example "2026-03-31"
`rows[].partnerId`	`string (uuid)`nullable	Lists only: the partner on the client’s latest engagement.
`rows[].managerId`	`string (uuid)`nullable	Lists only: the manager on the client’s latest engagement.
`rows[].connection`	`string (ClientConnectionState)`	Lists only: connected (Tolvi can read the books), reconnect (access expired or removed), error (the last call failed) or not_connected (manual upload). One of: `connected`, `reconnect`, `error`, `not_connected`
`rows[].connectionProvider`	`string`nullable	Lists only: the client’s source: connected software (xero, quickbooks, sage or freeagent), or tolvi_books when the client’s books are in Tolvi Books and that is the source in use. example "xero"
`rows[].nextDueDate`	`string (date)`nullable	Lists only: the earliest filing deadline among engagements not yet complete. 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
`total`required	`integer`	Clients matching the search and filters (all pages).

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

Create a client

POST/api/v1/clients

Scopes: clients:write
Retries: Send an Idempotency-Key to make retries safe.

Parameters

Parameters for POST /api/v1/clients
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 (CreateClientRequest).

Request body for POST /api/v1/clients
Field	Type	Description
`name`required	`string`	1 to 200 characters
`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`	`string`nullable	Companies House number (upper-cased on save). pattern ^(?:[0-9]{8}\|[A-Z]{2}[0-9]{6})$
`yearEndDay`	`integer`nullable	Financial year end day; send with yearEndMonth. 1 to 31
`yearEndMonth`	`integer`nullable	Financial year end month. 1 to 12

Responses

201 Created, `application/json`

Body: object (Client).

201 Created response for POST /api/v1/clients
Field	Type	Description
`id`required	`string (uuid)`
`firmId`required	`string (uuid)`
`name`required	`string`	example "Hartley Joinery Ltd"
`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	Companies House number. example "01234567"
`yearEndDay`required	`integer`nullable	Financial year end day (with yearEndMonth); null when not known. 1 to 31
`yearEndMonth`required	`integer`nullable	Financial year end month (1-12). 1 to 12
`createdAt`required	`string (date-time)`
`status`	`string (ClientStatus)`	Prospect, active or former. One of: `prospect`, `active`, `former`
`latestPeriodEnd`	`string (date)`nullable	Lists only: the period end of the client’s latest engagement (null when it has none), so a year end can be shown when yearEndDay/yearEndMonth are not set. example "2026-03-31"
`partnerId`	`string (uuid)`nullable	Lists only: the partner on the client’s latest engagement.
`managerId`	`string (uuid)`nullable	Lists only: the manager on the client’s latest engagement.
`connection`	`string (ClientConnectionState)`	Lists only: connected (Tolvi can read the books), reconnect (access expired or removed), error (the last call failed) or not_connected (manual upload). One of: `connected`, `reconnect`, `error`, `not_connected`
`connectionProvider`	`string`nullable	Lists only: the client’s source: connected software (xero, quickbooks, sage or freeagent), or tolvi_books when the client’s books are in Tolvi Books and that is the source in use. example "xero"
`nextDueDate`	`string (date)`nullable	Lists only: the earliest filing deadline among engagements not yet complete. example "2026-03-31"

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

Find existing clients a new one may duplicate

GET/api/v1/clients/duplicates

Scopes: clients:read

Call before creating a client. Matches the name ignoring case, punctuation and spacing ("&" = "and", "Limited" = "Ltd"), and the Companies House number when given. Advisory: creating a client is never blocked, so show the matches and let the person open one or add anyway.

Parameters

Parameters for GET /api/v1/clients/duplicates
Name	In	Type	Description
`companyNumber`	query	`string`	The new client’s Companies House number. up to 8 characters
`name`	query	`string`	The new client’s name. up to 200 characters

Responses

200 OK, `application/json`

Body: object (DuplicateClients).

200 OK response for GET /api/v1/clients/duplicates
Field	Type	Description
`matches`required	`array of DuplicateClient`
`matches[].client`required	`object (Client)`
`matches[].client.id`required	`string (uuid)`
`matches[].client.firmId`required	`string (uuid)`
`matches[].client.name`required	`string`	example "Hartley Joinery Ltd"
`matches[].client.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`
`matches[].client.companyNumber`required	`string`nullable	Companies House number. example "01234567"
`matches[].client.yearEndDay`required	`integer`nullable	Financial year end day (with yearEndMonth); null when not known. 1 to 31
`matches[].client.yearEndMonth`required	`integer`nullable	Financial year end month (1-12). 1 to 12
`matches[].client.createdAt`required	`string (date-time)`
`matches[].client.status`	`string (ClientStatus)`	Prospect, active or former. One of: `prospect`, `active`, `former`
`matches[].client.latestPeriodEnd`	`string (date)`nullable	Lists only: the period end of the client’s latest engagement (null when it has none), so a year end can be shown when yearEndDay/yearEndMonth are not set. example "2026-03-31"
`matches[].client.partnerId`	`string (uuid)`nullable	Lists only: the partner on the client’s latest engagement.
`matches[].client.managerId`	`string (uuid)`nullable	Lists only: the manager on the client’s latest engagement.
`matches[].client.connection`	`string (ClientConnectionState)`	Lists only: connected (Tolvi can read the books), reconnect (access expired or removed), error (the last call failed) or not_connected (manual upload). One of: `connected`, `reconnect`, `error`, `not_connected`
`matches[].client.connectionProvider`	`string`nullable	Lists only: the client’s source: connected software (xero, quickbooks, sage or freeagent), or tolvi_books when the client’s books are in Tolvi Books and that is the source in use. example "xero"
`matches[].client.nextDueDate`	`string (date)`nullable	Lists only: the earliest filing deadline among engagements not yet complete. example "2026-03-31"
`matches[].matchedOn`required	`array of DuplicateClientMatch`	name: the same name ignoring case, punctuation and spacing ("&" = "and", "Limited" = "Ltd"); company_number: the same Companies House number. One of: `name`, `company_number`

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

List a client’s own checklist steps

GET/api/v1/clients/{clientId}/checklist-steps

Scopes: clients: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/clients/{clientId}/checklist-steps
Name	In	Type	Description
`clientId`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: array of ClientChecklistStep.

200 OK response for GET /api/v1/clients/{clientId}/checklist-steps
Field	Type	Description
`[].id`required	`string (uuid)`
`[].sectionCode`required	`string`
`[].text`required	`string`
`[].createdAt`required	`string (date-time)`

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

Add a checklist step for this client

POST/api/v1/clients/{clientId}/checklist-steps

Scopes: clients:write
Retries: Send an Idempotency-Key to make retries safe.

Added to the section’s checklist on each new engagement. Part of the working_papers product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/clients/{clientId}/checklist-steps
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 (CreateClientChecklistStep).

Request body for POST /api/v1/clients/{clientId}/checklist-steps
Field	Type	Description
`sectionCode`required	`string`
`text`required	`string`	1 to 500 characters

Responses

201 Created, `application/json`

Body: object (ClientChecklistStep).

201 Created response for POST /api/v1/clients/{clientId}/checklist-steps
Field	Type	Description
`id`required	`string (uuid)`
`sectionCode`required	`string`
`text`required	`string`
`createdAt`required	`string (date-time)`

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

Get a client with its settings, notes and year-end history

GET/api/v1/clients/{clientId}

Scopes: clients:read

Parameters

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

Responses

200 OK, `application/json`

Body: object (ClientDetail).

200 OK response for GET /api/v1/clients/{clientId}
Field	Type	Description
`id`required	`string (uuid)`
`firmId`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	Financial year end day; null when not known. 1 to 31
`yearEndMonth`required	`integer`nullable	1 to 12
`createdAt`required	`string (date-time)`
`partnerId`required	`string (uuid)`nullable	From the latest engagement.
`managerId`required	`string (uuid)`nullable
`preparerId`required	`string (uuid)`nullable	From the latest engagement.
`reviewerId`required	`string (uuid)`nullable	From the latest engagement.
`software`required	`string (Software)`	One of: `xero`, `qbo`, `sage`, `freeagent`, `tolvi_books`, `manual`
`syncState`required	`string (SyncState)`	One of: `in_sync`, `changed`, `expired_token`, `error`, `never_synced`, `manual`
`overrides`required	`object (ClientOverrides)`	A client’s settings that differ from the firm’s (null: use the firm default).
`overrides.risk`required	`string (RiskLevel)`nullable	One of: `standard`, `high`
`overrides.workflowTemplateId`required	`string`nullable
`overrides.thresholdAbsPence`required	`integer`nullable	Integer pence (GBP).
`overrides.thresholdPct`required	`integer`nullable
`overrides.materialityPence`required	`integer`nullable	Integer pence (GBP).
`overrides.deadlineOverride`required	`string (date)`nullable	e.g. an extension or a changed accounting reference date. example "2026-03-31"
`overrides.syncIgnoreUnderPence`required	`integer`nullable	Integer pence (GBP).
`overrides.syncExcludeCodes`	`array of string`nullable	Account codes the sign-off check leaves out for this client. Always present in responses. up to 200 items
`overrides.syncOnChange`	`string (SyncOnChange)`nullable	What the sign-off check does when this client’s books change. Always present in responses. One of: `notify`, `reopen`, `none`
`overrideCount`required	`integer`
`notes`required	`string`
`extraChecklistSteps`required	`array of ClientStepRef`
`extraChecklistSteps[].id`required	`string (uuid)`
`extraChecklistSteps[].sectionCode`required	`string`
`extraChecklistSteps[].text`required	`string`
`extraChecklistSteps[].createdAt`required	`string (date-time)`
`engagements`required	`array of ClientEngagement`	Year-end history, newest first.
`engagements[].id`required	`string (uuid)`
`engagements[].periodStart`required	`string (date)`	example "2026-03-31"
`engagements[].periodEnd`required	`string (date)`	example "2026-03-31"
`engagements[].dueDate`required	`string (date)`	example "2026-03-31"
`engagements[].status`required	`string (EngagementStatus)`	One of: `not_started`, `in_progress`, `submitted`, `returned`, `complete`
`engagements[].stageName`required	`string`
`engagements[].filedOn`required	`string (date)`nullable	example "2026-03-31"
`engagements[].preparerId`required	`string (uuid)`nullable
`engagements[].reviewerId`required	`string (uuid)`nullable
`engagements[].rounds`required	`integer`	Times sent back by a reviewer (amendment rounds). at least 0
`engagements[].openReviewPoints`required	`integer`	at least 0

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

List the client’s remembered mappings

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

Scopes: clients:read

Changing an account’s mapping in section B remembers it for the client; next year it is applied ahead of the firm rules.

Parameters

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

Responses

200 OK, `application/json`

Body: array of ClientMapping.

A remembered mapping: applied to this client’s code ahead of the firm rules.

200 OK response for GET /api/v1/clients/{clientId}/mappings
Field	Type	Description
`[].code`required	`string`
`[].name`required	`string`nullable	The account’s name on the latest trial balance that has it.
`[].lineId`required	`string (LeadLineId)`	One of: `C.cost`, `C.dep`, `D.stk`, `E.td`, `E.pre`, `F.bank`, `G.tc`, `G.acc`, `H.vat`, `I.paye`, `J.dla`, `J.loanst`, `J.loan`, `K.cap`, `K.res`, `K.div`, `L.sales`, `L.intrec`, `M.cos`, `M.adm`, `M.dis`, `M.dep`, `M.int`, `M.disp`, `T.chg`, `T.liab`, `T.dtc`, `P.dt`, `J.cap`, `J.draw`
`[].updatedAt`required	`string (date-time)`

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

Get the client’s overrides of the firm settings

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

Scopes: clients:read

Parameters

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

Responses

200 OK, `application/json`

Body: object (ClientOverrides).

A client’s settings that differ from the firm’s (null: use the firm default).

200 OK response for GET /api/v1/clients/{clientId}/settings
Field	Type	Description
`risk`required	`string (RiskLevel)`nullable	One of: `standard`, `high`
`workflowTemplateId`required	`string`nullable
`thresholdAbsPence`required	`integer`nullable	Integer pence (GBP).
`thresholdPct`required	`integer`nullable
`materialityPence`required	`integer`nullable	Integer pence (GBP).
`deadlineOverride`required	`string (date)`nullable	e.g. an extension or a changed accounting reference date. example "2026-03-31"
`syncIgnoreUnderPence`required	`integer`nullable	Integer pence (GBP).
`syncExcludeCodes`	`array of string`nullable	Account codes the sign-off check leaves out for this client. Always present in responses. up to 200 items
`syncOnChange`	`string (SyncOnChange)`nullable	What the sign-off check does when this client’s books change. Always present in responses. One of: `notify`, `reopen`, `none`

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 overrides

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

Scopes: clients:write
Role: Manager or above

Send only what changes; null goes back to the firm default. Used by engagements started from now on.

Needs the Manager role or above.

Parameters

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

Request body

Required. application/json: object (ClientOverrides).

A client’s settings that differ from the firm’s (null: use the firm default).

The fields are as shown above.

Responses

200 OK, `application/json`

Body: object (ClientOverrides).

A client’s settings that differ from the firm’s (null: use the firm default).

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 client’s permanent notes

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

Scopes: clients:read

Parameters

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

Responses

200 OK, `application/json`

Body: object (ClientNotes).

200 OK response for GET /api/v1/clients/{clientId}/notes
Field	Type	Description
`notes`required	`string`	up to 20000 characters
`updatedBy`required	`string (uuid)`nullable
`updatedAt`required	`string (date-time)`nullable

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

Replace the client’s permanent notes

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

Scopes: clients:write

Parameters

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

Request body

Required. application/json: object (SetClientNotes).

Request body for PATCH /api/v1/clients/{clientId}/notes
Field	Type	Description
`notes`required	`string`	up to 20000 characters

Responses

200 OK, `application/json`

Body: object (ClientNotes).

200 OK response for PATCH /api/v1/clients/{clientId}/notes
Field	Type	Description
`notes`required	`string`	up to 20000 characters
`updatedBy`required	`string (uuid)`nullable
`updatedAt`required	`string (date-time)`nullable

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

Preview starting a client’s books from its final trial balance

POST/api/v1/clients/{clientId}/books-link/opening/preview

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

Uses the client’s latest engagement approved at every stage, or the one named. Each final balance is placed on the books’ account by mapping, the same code on the same lead line, or the lead line’s default account; anything else is listed to map. problems says what stands in the way. Nothing is posted. Session only; reviewers and above. Part of the working_papers product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/clients/{clientId}/books-link/opening/preview
Name	In	Type	Description
`clientId`required	path	`string (uuid)`	Client id.

Request body

Optional. application/json: object (StartBooksFromFinalTbInput).

Request body for POST /api/v1/clients/{clientId}/books-link/opening/preview
Field	Type	Description
`engagementId`	`string (uuid)`	Defaults to the client’s latest engagement approved at every stage.
`mapping`	`object`	Final TB code to an account code in the books.

Responses

200 OK, `application/json`

Body: object (StartBooksFromFinalTbPreview).

The opening entry the client’s books would get from a final trial balance, mapped through the lead lines. Nothing is posted.

200 OK response for POST /api/v1/clients/{clientId}/books-link/opening/preview
Field	Type	Description
`ready`required	`boolean`
`problems`required	`array of string`	What stands in the way, in words.
`warnings`required	`array of string`
`engagementId`required	`string (uuid)`nullable
`periodEnd`required	`string (date)`nullable	example "2026-03-31"
`startDate`required	`string (date)`nullable	The day after the period end. example "2026-03-31"
`businessId`required	`string (uuid)`nullable
`businessName`required	`string`nullable
`alreadyPosted`required	`boolean`
`plan`required	`array of BooksOpeningPlanLine`
`plan[].sourceCode`required	`string`
`plan[].sourceName`required	`string`
`plan[].balancePence`required	`integer`	Integer pence (GBP).
`plan[].targetCode`required	`string`
`plan[].targetName`required	`string`
`plan[].via`required	`string (BooksOpeningPlanVia)`	One of: `mapping`, `code`, `lead_line`
`unmapped`required	`array of BooksOpeningUnmapped`
`unmapped[].code`required	`string`
`unmapped[].name`required	`string`
`unmapped[].balancePence`required	`integer`	Integer pence (GBP).
`unmapped[].leadLine`required	`string`nullable
`lines`required	`array of BooksOpeningEntryLine`
`lines[].accountId`required	`string (uuid)`
`lines[].accountCode`required	`string`
`lines[].accountName`required	`string`
`lines[].ownerName`required	`string`
`lines[].normalBalance`required	`string (BooksNormalBalance)`	One of: `debit`, `credit`
`lines[].amountPence`required	`integer`	Integer pence (GBP). Debit positive, credit negative.
`lines[].contactName`required	`string`nullable	The customer or supplier, on a control account line split by unpaid invoice or bill.
`suspensePence`required	`integer`	Integer pence (GBP).
`accounts`required	`array of BooksOpeningAccountRef`	The books’ accounts, to map an unplaced balance to.
`accounts[].code`required	`string`
`accounts[].name`required	`string`
`accounts[].ownerName`required	`string`

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

Start a client’s books from its final trial balance

POST/api/v1/clients/{clientId}/books-link/opening

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

Posts the preview’s opening entry to the client’s books, dated the period end, through the firm’s practice link (year-end or full bookkeeping access). 409 with the reasons when the preview isn’t ready. Reversible from the books until the year is locked. Session only; reviewers and above; not available through the MCP server. Part of the working_papers product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/clients/{clientId}/books-link/opening
Name	In	Type	Description
`clientId`required	path	`string (uuid)`	Client id.
`Idempotency-Key`	header	`string`	A unique key (1-255 visible characters) to make retries safe. Replayed for 24 hours. 1 to 255 characters

Request body

Optional. application/json: object (StartBooksFromFinalTbInput).

Request body for POST /api/v1/clients/{clientId}/books-link/opening
Field	Type	Description
`engagementId`	`string (uuid)`	Defaults to the client’s latest engagement approved at every stage.
`mapping`	`object`	Final TB code to an account code in the books.

Responses

201 Created, `application/json`

Body: object (StartBooksFromFinalTbResult).

201 Created response for POST /api/v1/clients/{clientId}/books-link/opening
Field	Type	Description
`entryId`required	`string (uuid)`
`seq`required	`integer`
`startDate`required	`string (date)`	example "2026-03-31"
`suspensePence`required	`integer`	Integer pence (GBP).
`status`required	`string (StartBooksFromFinalTbStatus)`	One of: `posted`

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

Clients

List a client’s links

Parameters

Responses

200 OK, application/json

Link a person and a company

Parameters

Request body

Responses

201 Created, application/json

Change a link

Parameters

Request body

Responses

200 OK, application/json

Remove a link

Parameters

Responses

204 No content

What a linked client’s other work suggests here

Parameters

Responses

200 OK, application/json

Accept or dismiss a suggestion

Request body

Responses

200 OK, application/json

List or search clients

Parameters

Responses

200 OK, application/json

Create a client

Parameters

Request body

Responses

201 Created, application/json

Find existing clients a new one may duplicate

Parameters

Responses

200 OK, application/json

List a client’s own checklist steps

Parameters

Responses

200 OK, application/json

Add a checklist step for this client

Parameters

Request body

Responses

201 Created, application/json

Get a client with its settings, notes and year-end history

Parameters

Responses

200 OK, application/json

List the client’s remembered mappings

Parameters

Responses

200 OK, application/json

Get the client’s overrides of the firm settings

Parameters

Responses

200 OK, application/json

Change the client’s overrides

Parameters

Request body

Responses

200 OK, application/json

Get the client’s permanent notes

Parameters

Responses

200 OK, application/json

Replace the client’s permanent notes

Parameters

Request body

Responses

200 OK, application/json

Preview starting a client’s books from its final trial balance

Parameters

Request body

Responses

200 OK, application/json

200 OK, `application/json`

201 Created, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

201 Created, `application/json`

200 OK, `application/json`

200 OK, `application/json`

201 Created, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

201 Created, `application/json`