Books

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

Sign a business up to Tolvi Books

POST/api/v1/books/signup

Access: No authentication.

Creates the business and emails a single-use link to the address given. Following it confirms the address, has the person choose a password in the Tolvi Books app and makes them the business’s owner. No token needed.

Request body

Required. application/json: object (BooksSignUp).

A business signing up to Tolvi Books on its own.

Request body for POST /api/v1/books/signup
Field	Type	Description
`businessName`required	`string`	up to 200 characters; example "Abbey Bakery 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`
`email`required	`string (email)`	up to 254 characters

Responses

202 Accepted, `application/json`

Body: object (SignUpResult).

202 Accepted response for POST /api/v1/books/signup
Field	Type	Description
`email`required	`string (email)`	Where the link to finish signing up was sent.

403 Forbidden

Sign-up is closed: people join by invitation (TOLVI_SIGNUP_OPEN is off).

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

Get the business’s profile

GET/api/v1/books/business

Scopes: books:read

Anyone who can read the books, including a linked accountant. Part of the books product: the firm must have it and you must have access to it.

Responses

200 OK, `application/json`

Body: object (Business).

A business’s profile in Tolvi Books: who it is, its VAT registration and its year end.

200 OK response for GET /api/v1/books/business
Field	Type	Description
`id`required	`string (uuid)`	The business’s tenant id (send it as x-business-id to work in its books as its accountant).
`legalName`required	`string`	example "Abbey Bakery Ltd"
`tradingName`required	`string`nullable
`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	example "01234567"
`vatRegistered`required	`boolean`
`vatNumber`required	`string`nullable	9 digits (12 for a group branch), without GB. example "123456789"
`vatScheme`required	`string (VatScheme)`nullable	One of: `standard`, `cash_accounting`, `flat_rate`, `annual_accounting`
`vatRegisteredFrom`required	`string (date)`nullable	example "2026-03-31"
`yearEndDay`required	`integer`nullable	1 to 31
`yearEndMonth`required	`integer`nullable	1 to 12
`booksStartDate`required	`string (date)`nullable	The first day the books cover. example "2026-03-31"
`baseCurrency`required	`string (BooksCurrency)`	One of: `GBP`
`custodianFirmId`required	`string (uuid)`nullable	The accountancy practice that set the business up, until an owner claims it.
`createdAt`required	`string (date-time)`
`updatedAt`required	`string (date-time)`

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

Change the business’s details

PATCH/api/v1/books/business

Scopes: books:write

The business’s owners and admins (books:admin). A practice that set the business up can too, through its link, until the owner joins. Changing VAT details needs a signed-in person. Part of the books product: the firm must have it and you must have access to it.

Request body

Required. application/json: object (UpdateBusiness).

Only the fields sent change. VAT details need a signed-in person.

Request body for PATCH /api/v1/books/business
Field	Type	Description
`legalName`	`string`	up to 200 characters
`tradingName`	`string`nullable	up to 200 characters
`entityType`	`string (EntityType)`	One of: `LTD_FRS102_1A`, `LTD_FRS105_MICRO`, `LLP`, `SOLE_TRADER`, `INDIVIDUAL`, `PARTNERSHIP`, `TRUST`, `ESTATE`, `CHARITY_UNINCORPORATED`, `CHARITY_TRUST`, `CIO`, `SCIO`, `CHARITABLE_COMPANY`
`companyNumber`	`string`nullable	pattern ^[A-Za-z0-9 ]{8,10}$
`vatRegistered`	`boolean`
`vatNumber`	`string`nullable
`vatScheme`	`string (VatScheme)`nullable	One of: `standard`, `cash_accounting`, `flat_rate`, `annual_accounting`
`vatRegisteredFrom`	`string (date)`nullable	example "2026-03-31"
`yearEndDay`	`integer`nullable	1 to 31
`yearEndMonth`	`integer`nullable	1 to 12
`booksStartDate`	`string (date)`nullable	example "2026-03-31"

Responses

200 OK, `application/json`

Body: object (Business).

A business’s profile in Tolvi Books: who it is, its VAT registration and its year end.

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 the business’s accountants

GET/api/v1/books/accountants

Scopes: books:read

Every practice link, live or ended. A linked accountant sees only their own firm’s link. Part of the books product: the firm must have it and you must have access to it.

Responses

200 OK, `application/json`

Body: array of PracticeLink.

An accountancy practice’s access to a business’s books, as either side sees it.

200 OK response for GET /api/v1/books/accountants
Field	Type	Description
`[].id`required	`string (uuid)`
`[].status`required	`string (PracticeLinkStatus)`	invited_by_business: waiting for the practice to accept. requested_by_firm: waiting for the business to approve. active: the practice can work in the books. ended: never active again. One of: `invited_by_business`, `requested_by_firm`, `active`, `ended`
`[].access`required	`string (PracticeAccess)`	read_only: see the books, export, pull the TB. year_end: also post year-end adjustments. full_bookkeeping: also keep the books. One of: `read_only`, `year_end`, `full_bookkeeping`
`[].vatAgent`required	`boolean`	The practice may prepare (and, once built, submit) VAT returns. At most one practice at a time.
`[].billedBy`required	`string (LinkBilledBy)`	Who the business said should pay, on its link. One of: `business`, `firm`
`[].consentBasis`required	`string (LinkConsentBasis)`	One of: `owner_consent`, `practice_provisioned`
`[].businessId`required	`string (uuid)`nullable
`[].businessName`required	`string`nullable
`[].firmId`required	`string (uuid)`nullable
`[].firmName`required	`string`nullable
`[].invitedEmail`required	`string`nullable
`[].requestedEmail`required	`string`nullable
`[].expiresAt`required	`string (date-time)`nullable
`[].createdAt`required	`string (date-time)`
`[].activatedAt`required	`string (date-time)`nullable
`[].endedAt`required	`string (date-time)`nullable
`[].endedBySide`required	`string (LinkSide)`nullable	One of: `business`, `firm`

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

Invite an accountant

POST/api/v1/books/accountants/invitations

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

Emails a single-use link to the accountant, who accepts while signed in to their practice. Signed-in owners and admins only. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/accountants/invitations
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 (InviteAccountant).

Request body for POST /api/v1/books/accountants/invitations
Field	Type	Description
`email`required	`string (email)`	The accountant who will accept, signed in to their practice in Tolvi. up to 254 characters
`access`required	`string (PracticeAccess)`	read_only: see the books, export, pull the TB. year_end: also post year-end adjustments. full_bookkeeping: also keep the books. One of: `read_only`, `year_end`, `full_bookkeeping`
`vatAgent`	`boolean`

Responses

201 Created, `application/json`

Body: object (PracticeLink).

An accountancy practice’s access to a business’s books, as either side sees it.

201 Created response for POST /api/v1/books/accountants/invitations
Field	Type	Description
`id`required	`string (uuid)`
`status`required	`string (PracticeLinkStatus)`	invited_by_business: waiting for the practice to accept. requested_by_firm: waiting for the business to approve. active: the practice can work in the books. ended: never active again. One of: `invited_by_business`, `requested_by_firm`, `active`, `ended`
`access`required	`string (PracticeAccess)`	read_only: see the books, export, pull the TB. year_end: also post year-end adjustments. full_bookkeeping: also keep the books. One of: `read_only`, `year_end`, `full_bookkeeping`
`vatAgent`required	`boolean`	The practice may prepare (and, once built, submit) VAT returns. At most one practice at a time.
`billedBy`required	`string (LinkBilledBy)`	Who the business said should pay, on its link. One of: `business`, `firm`
`consentBasis`required	`string (LinkConsentBasis)`	One of: `owner_consent`, `practice_provisioned`
`businessId`required	`string (uuid)`nullable
`businessName`required	`string`nullable
`firmId`required	`string (uuid)`nullable
`firmName`required	`string`nullable
`invitedEmail`required	`string`nullable
`requestedEmail`required	`string`nullable
`expiresAt`required	`string (date-time)`nullable
`createdAt`required	`string (date-time)`
`activatedAt`required	`string (date-time)`nullable
`endedAt`required	`string (date-time)`nullable
`endedBySide`required	`string (LinkSide)`nullable	One of: `business`, `firm`

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

Change an accountant’s access

PATCH/api/v1/books/accountants/{linkId}

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

Access level, VAT agent (one practice at a time) and who pays. Part of the books product: the firm must have it and you must have access to it.

Parameters

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

Request body

Required. application/json: object (ChangePracticeLink).

Only the fields sent change.

Request body for PATCH /api/v1/books/accountants/{linkId}
Field	Type	Description
`access`	`string (PracticeAccess)`	read_only: see the books, export, pull the TB. year_end: also post year-end adjustments. full_bookkeeping: also keep the books. One of: `read_only`, `year_end`, `full_bookkeeping`
`vatAgent`	`boolean`
`billedBy`	`string (LinkBilledBy)`	Who the business said should pay, on its link. One of: `business`, `firm`

Responses

200 OK, `application/json`

Body: object (PracticeLink).

An accountancy practice’s access to a business’s books, as either side sees 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).

End an accountant’s access

POST/api/v1/books/accountants/{linkId}/end

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

Takes effect from their next request, in the database itself. Also withdraws an invitation. An ended link is never active again. Allowed even while Tolvi Books is suspended. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/accountants/{linkId}/end
Name	In	Type	Description
`linkId`required	path	`string (uuid)`

Request body

Optional. application/json: object (EndPracticeLink).

Request body for POST /api/v1/books/accountants/{linkId}/end
Field	Type	Description
`reason`	`string`	up to 500 characters

Responses

200 OK, `application/json`

Body: object (PracticeLink).

An accountancy practice’s access to a business’s books, as either side sees 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).

List practices’ requests for access

GET/api/v1/books/accountants/requests

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

Requests sent to your verified email address, waiting for an answer. Part of the books product: the firm must have it and you must have access to it.

Responses

200 OK, `application/json`

Body: array of PracticeLink.

An accountancy practice’s access to a business’s books, as either side sees it.

The fields are as shown above.

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

Approve a practice’s request

POST/api/v1/books/accountants/requests/{linkId}/approve

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

Links the practice to this business with the access you choose. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/accountants/requests/{linkId}/approve
Name	In	Type	Description
`linkId`required	path	`string (uuid)`

Request body

Optional. application/json: object (ApprovePracticeLinkRequest).

Request body for POST /api/v1/books/accountants/requests/{linkId}/approve
Field	Type	Description
`access`	`string (PracticeAccess)`	Defaults to what the practice asked for. One of: `read_only`, `year_end`, `full_bookkeeping`
`vatAgent`	`boolean`

Responses

200 OK, `application/json`

Body: object (PracticeLink).

An accountancy practice’s access to a business’s books, as either side sees 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).

Decline a practice’s request

POST/api/v1/books/accountants/requests/{linkId}/decline

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

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

Parameters

Parameters for POST /api/v1/books/accountants/requests/{linkId}/decline
Name	In	Type	Description
`linkId`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (PracticeLink).

An accountancy practice’s access to a business’s books, as either side sees 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).

List the firm’s links to businesses’ books

GET/api/v1/practice/books/links

Scopes: client_books:read

Requests, accepted invitations, live and ended links.

Responses

200 OK, `application/json`

Body: array of PracticeLink.

An accountancy practice’s access to a business’s books, as either side sees it.

The fields are as shown above.

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

Ask a business for access to its books

POST/api/v1/practice/books/requests

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

Emails the owner, who approves or declines in Tolvi Books.

Parameters

Parameters for POST /api/v1/practice/books/requests
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 (RequestBooksAccess).

Request body for POST /api/v1/practice/books/requests
Field	Type	Description
`email`required	`string (email)`	The business owner’s email: they approve in Tolvi Books. up to 254 characters
`access`required	`string (PracticeAccess)`	read_only: see the books, export, pull the TB. year_end: also post year-end adjustments. full_bookkeeping: also keep the books. One of: `read_only`, `year_end`, `full_bookkeeping`

Responses

201 Created, `application/json`

Body: object (PracticeLink).

An accountancy practice’s access to a business’s books, as either side sees it.

The fields are as shown above.

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

See what a business’s invitation offers

POST/api/v1/practice/books/link-invitations/preview

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

The token from the email, in the body (never the URL).

Request body

Required. application/json: object (PracticeLinkToken).

The token from the invitation email.

Request body for POST /api/v1/practice/books/link-invitations/preview
Field	Type	Description
`token`required	`string`	20 to 200 characters

Responses

200 OK, `application/json`

Body: object (PracticeLinkInvitationPreview).

200 OK response for POST /api/v1/practice/books/link-invitations/preview
Field	Type	Description
`businessName`required	`string`nullable
`access`required	`string (PracticeAccess)`	read_only: see the books, export, pull the TB. year_end: also post year-end adjustments. full_bookkeeping: also keep the books. One of: `read_only`, `year_end`, `full_bookkeeping`
`vatAgent`required	`boolean`
`expiresAt`required	`string (date-time)`nullable
`expired`required	`boolean`

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

Accept a business’s invitation

POST/api/v1/practice/books/link-invitations/accept

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

The person it was emailed to accepts, signed in to their practice. Single use.

Request body

Required. application/json: object (PracticeLinkToken).

The token from the invitation email.

Request body for POST /api/v1/practice/books/link-invitations/accept
Field	Type	Description
`token`required	`string`	20 to 200 characters

Responses

200 OK, `application/json`

Body: object (PracticeLink).

An accountancy practice’s access to a business’s books, as either side sees it.

The fields are as shown above.

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

End the firm’s access to a business’s books

POST/api/v1/practice/books/links/{linkId}/end

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

Also withdraws a request. An ended link is never active again.

Parameters

Parameters for POST /api/v1/practice/books/links/{linkId}/end
Name	In	Type	Description
`linkId`required	path	`string (uuid)`

Request body

Optional. application/json: object (EndPracticeLink).

Request body for POST /api/v1/practice/books/links/{linkId}/end
Field	Type	Description
`reason`	`string`	up to 500 characters

Responses

200 OK, `application/json`

Body: object (PracticeLink).

An accountancy practice’s access to a business’s books, as either side sees 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).

Set Tolvi Books up for a client

POST/api/v1/practice/books/businesses

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

Creates the business with the firm as its accountant (full bookkeeping) under the firm’s engagement letter. The firm looks after it until the owner joins.

Parameters

Parameters for POST /api/v1/practice/books/businesses
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 (ProvisionBusiness).

A practice setting Tolvi Books up for a client. The practice looks after it until the owner joins.

Request body for POST /api/v1/practice/books/businesses
Field	Type	Description
`legalName`required	`string`	up to 200 characters
`tradingName`	`string`nullable	up 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
`yearEndDay`	`integer`nullable	1 to 31
`yearEndMonth`	`integer`nullable	1 to 12
`booksStartDate`	`string (date)`nullable	example "2026-03-31"
`billedBy`	`string (LinkBilledBy)`	Who pays for Tolvi Books. Defaults to the practice. One of: `business`, `firm`
`ownerEmail`	`string (email)`	Invite the owner now (they can also be invited later).

Responses

201 Created, `application/json`

Body: object (ProvisionedBusiness).

The business a practice set up, and the practice’s link to it.

201 Created response for POST /api/v1/practice/books/businesses
Field	Type	Description
`business`required	`object (Business)`	A business’s profile in Tolvi Books: who it is, its VAT registration and its year end.
`business.id`required	`string (uuid)`	The business’s tenant id (send it as x-business-id to work in its books as its accountant).
`business.legalName`required	`string`	example "Abbey Bakery Ltd"
`business.tradingName`required	`string`nullable
`business.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`
`business.companyNumber`required	`string`nullable	example "01234567"
`business.vatRegistered`required	`boolean`
`business.vatNumber`required	`string`nullable	9 digits (12 for a group branch), without GB. example "123456789"
`business.vatScheme`required	`string (VatScheme)`nullable	One of: `standard`, `cash_accounting`, `flat_rate`, `annual_accounting`
`business.vatRegisteredFrom`required	`string (date)`nullable	example "2026-03-31"
`business.yearEndDay`required	`integer`nullable	1 to 31
`business.yearEndMonth`required	`integer`nullable	1 to 12
`business.booksStartDate`required	`string (date)`nullable	The first day the books cover. example "2026-03-31"
`business.baseCurrency`required	`string (BooksCurrency)`	One of: `GBP`
`business.custodianFirmId`required	`string (uuid)`nullable	The accountancy practice that set the business up, until an owner claims it.
`business.createdAt`required	`string (date-time)`
`business.updatedAt`required	`string (date-time)`
`link`required	`object (PracticeLink)`	An accountancy practice’s access to a business’s books, as either side sees it.
`link.id`required	`string (uuid)`
`link.status`required	`string (PracticeLinkStatus)`	invited_by_business: waiting for the practice to accept. requested_by_firm: waiting for the business to approve. active: the practice can work in the books. ended: never active again. One of: `invited_by_business`, `requested_by_firm`, `active`, `ended`
`link.access`required	`string (PracticeAccess)`	read_only: see the books, export, pull the TB. year_end: also post year-end adjustments. full_bookkeeping: also keep the books. One of: `read_only`, `year_end`, `full_bookkeeping`
`link.vatAgent`required	`boolean`	The practice may prepare (and, once built, submit) VAT returns. At most one practice at a time.
`link.billedBy`required	`string (LinkBilledBy)`	Who the business said should pay, on its link. One of: `business`, `firm`
`link.consentBasis`required	`string (LinkConsentBasis)`	One of: `owner_consent`, `practice_provisioned`
`link.businessId`required	`string (uuid)`nullable
`link.businessName`required	`string`nullable
`link.firmId`required	`string (uuid)`nullable
`link.firmName`required	`string`nullable
`link.invitedEmail`required	`string`nullable
`link.requestedEmail`required	`string`nullable
`link.expiresAt`required	`string (date-time)`nullable
`link.createdAt`required	`string (date-time)`
`link.activatedAt`required	`string (date-time)`nullable
`link.endedAt`required	`string (date-time)`nullable
`link.endedBySide`required	`string (LinkSide)`nullable	One of: `business`, `firm`

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

Invite the owner of a business the firm set up

POST/api/v1/practice/books/businesses/{businessId}/owner-invitation

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

Only while the firm still looks after it (before an owner has joined).

Parameters

Parameters for POST /api/v1/practice/books/businesses/{businessId}/owner-invitation
Name	In	Type	Description
`businessId`required	path	`string (uuid)`

Request body

Required. application/json: object (OwnerInvitation).

Request body for POST /api/v1/practice/books/businesses/{businessId}/owner-invitation
Field	Type	Description
`email`required	`string (email)`	up to 254 characters

Responses

200 OK, `application/json`

Body: object (OwnerInvitation).

200 OK response for POST /api/v1/practice/books/businesses/{businessId}/owner-invitation
Field	Type	Description
`email`required	`string (email)`	up to 254 characters

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

List clients’ books

GET/api/v1/practice/books/clients

Scopes: client_books:read

Every business whose Tolvi Books the firm reaches (live and ended links), the client it is linked to, and for live links the books at a glance: entries posted, when last posted, receipts to review, VAT registration (bank lines to explain and VAT due appear once those are available).

Responses

200 OK, `application/json`

Body: object (ClientsBooksList).

200 OK response for GET /api/v1/practice/books/clients
Field	Type	Description
`rows`required	`array of ClientsBooksRow`
`rows[].practiceLinkId`required	`string (uuid)`
`rows[].businessId`required	`string (uuid)`
`rows[].businessName`required	`string`nullable
`rows[].linkStatus`required	`string (PracticeLinkStatus)`	invited_by_business: waiting for the practice to accept. requested_by_firm: waiting for the business to approve. active: the practice can work in the books. ended: never active again. One of: `invited_by_business`, `requested_by_firm`, `active`, `ended`
`rows[].access`required	`string (PracticeAccess)`	read_only: see the books, export, pull the TB. year_end: also post year-end adjustments. full_bookkeeping: also keep the books. One of: `read_only`, `year_end`, `full_bookkeeping`
`rows[].consentBasis`required	`string (LinkConsentBasis)`	One of: `owner_consent`, `practice_provisioned`
`rows[].clientId`required	`string (uuid)`nullable	The firm’s client these books are, once linked.
`rows[].clientName`required	`string`nullable
`rows[].health`required	`object (BooksHealth)`nullable	Null when the link has ended.
`rows[].health.entries`required	`integer`	Ledger entries posted. at least 0
`rows[].health.lastPostedAt`required	`string (date-time)`nullable
`rows[].health.lastEntryDate`required	`string (date)`nullable	The latest date any entry is dated. example "2026-03-31"
`rows[].health.receiptsToReview`required	`integer`	Receipts read and waiting to be confirmed. at least 0
`rows[].health.unexplainedBankLines`required	`integer`nullable	Bank lines not yet explained. Null until bank feeds are available. at least 0
`rows[].health.vatRegistered`required	`boolean`
`rows[].health.vatScheme`required	`string`nullable	example "standard"
`rows[].health.nextVatDue`required	`string (date)`nullable	The next VAT return due. Null until MTD VAT returns are available. example "2026-03-31"

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

Get the chart of accounts

GET/api/v1/books/accounts

Scopes: books:read

Every account, with its balance now and whether it has been used. Set up from the template for the business’s entity type when the business joined. Part of the books product: the firm must have it and you must have access to it.

Responses

200 OK, `application/json`

Body: object (BooksChartOfAccounts).

The business’s chart of accounts, and the template version it started from.

200 OK response for GET /api/v1/books/accounts
Field	Type	Description
`templateId`required	`string`	example "ltd_frs102_1a"
`templateVersion`required	`string`	example "2026-11"
`entityType`required	`string`	example "LTD_FRS102_1A"
`accounts`required	`array of BooksAccount`
`accounts[].id`required	`string (uuid)`
`accounts[].code`required	`string`	Unique in the business; never changes. example "6110"
`accounts[].name`required	`string`	The accountant’s name. example "Light, heat and power"
`accounts[].ownerName`required	`string`	What owners see. example "Gas and electricity"
`accounts[].ownerCategory`required	`string (BooksOwnerCategory)`	One of: `sales`, `other_income`, `direct_costs`, `staff`, `premises`, `travel`, `office`, `marketing`, `professional`, `finance_costs`, `other_costs`, `write_offs`, `tax`, `bank_and_cash`, `owed_to_you`, `you_owe`, `equipment`, `stock`, `owner`, `behind_the_scenes`
`accounts[].ownerCategoryLabel`required	`string`	example "Premises"
`accounts[].hint`required	`string`nullable	One sentence for owners on what goes here.
`accounts[].class`required	`string (BooksAccountClass)`	One of: `asset`, `liability`, `equity`, `income`, `expense`
`accounts[].normalBalance`required	`string (BooksNormalBalance)`	One of: `debit`, `credit`
`accounts[].subtype`required	`string`	example "overhead"
`accounts[].leadLine`required	`string`nullable	The Working Papers lead schedule line the account maps to. example "M.adm"
`accounts[].sa103`required	`string`nullable	The SA103 line (sole traders).
`accounts[].systemRole`required	`string`nullable	Set for accounts Tolvi keeps (control accounts, suspense, retained earnings or capital): they can’t be archived or take a manual journal.
`accounts[].defaultVatCodeId`required	`string`nullable	The VAT code suggested for new lines. example "S20"
`accounts[].fromTemplate`required	`boolean`	Created from the chart template when the business signed up.
`accounts[].archived`required	`boolean`
`accounts[].archivedAt`required	`string (date-time)`nullable
`accounts[].used`required	`boolean`	Posted to at least once: it can then be archived, never deleted.
`accounts[].balancePence`required	`integer`	The balance now, in pence (debit positive, credit negative).
`accounts[].createdAt`required	`string (date-time)`
`accounts[].updatedAt`required	`string (date-time)`

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

Add an account

POST/api/v1/books/accounts

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

The business’s owners and admins (books:admin), or a linked practice whose access lets it post (year-end or full bookkeeping). Give a name and a category: Tolvi picks a free code and copies the mapping from a similar account. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/accounts
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 (BooksCreateAccount).

Add an account. Give a name and a category; Tolvi picks a free code and copies the mapping from a similar account unless you say otherwise.

Request body for POST /api/v1/books/accounts
Field	Type	Description
`name`required	`string`	up to 120 characters; example "Software subscriptions"
`ownerName`	`string`	What owners see; defaults to the name. up to 120 characters
`ownerCategory`required	`string (BooksOwnerCategory)`	One of: `sales`, `other_income`, `direct_costs`, `staff`, `premises`, `travel`, `office`, `marketing`, `professional`, `finance_costs`, `other_costs`, `write_offs`, `tax`, `bank_and_cash`, `owed_to_you`, `you_owe`, `equipment`, `stock`, `owner`, `behind_the_scenes`
`class`	`string (BooksAccountClass)`	Needed only where a category spans classes (bank and cash, tax, you and the business). One of: `asset`, `liability`, `equity`, `income`, `expense`
`code`	`string`	Defaults to the next free code in the category’s range. up to 20 characters
`leadLine`	`string`	Working Papers lead schedule line (accountants).
`sa103`	`string`	SA103 line (accountants, sole traders).
`subtype`	`string`
`hint`	`string`nullable	up to 300 characters
`defaultVatCodeId`	`string`nullable	example "S20"
`likeAccountId`	`string (uuid)`	Copy the mapping from this account.

Responses

201 Created, `application/json`

Body: object (BooksAccount).

An account in the business’s chart of accounts. Owners see ownerName under ownerCategoryLabel; accountants see the code, name and class.

201 Created response for POST /api/v1/books/accounts
Field	Type	Description
`id`required	`string (uuid)`
`code`required	`string`	Unique in the business; never changes. example "6110"
`name`required	`string`	The accountant’s name. example "Light, heat and power"
`ownerName`required	`string`	What owners see. example "Gas and electricity"
`ownerCategory`required	`string (BooksOwnerCategory)`	One of: `sales`, `other_income`, `direct_costs`, `staff`, `premises`, `travel`, `office`, `marketing`, `professional`, `finance_costs`, `other_costs`, `write_offs`, `tax`, `bank_and_cash`, `owed_to_you`, `you_owe`, `equipment`, `stock`, `owner`, `behind_the_scenes`
`ownerCategoryLabel`required	`string`	example "Premises"
`hint`required	`string`nullable	One sentence for owners on what goes here.
`class`required	`string (BooksAccountClass)`	One of: `asset`, `liability`, `equity`, `income`, `expense`
`normalBalance`required	`string (BooksNormalBalance)`	One of: `debit`, `credit`
`subtype`required	`string`	example "overhead"
`leadLine`required	`string`nullable	The Working Papers lead schedule line the account maps to. example "M.adm"
`sa103`required	`string`nullable	The SA103 line (sole traders).
`systemRole`required	`string`nullable	Set for accounts Tolvi keeps (control accounts, suspense, retained earnings or capital): they can’t be archived or take a manual journal.
`defaultVatCodeId`required	`string`nullable	The VAT code suggested for new lines. example "S20"
`fromTemplate`required	`boolean`	Created from the chart template when the business signed up.
`archived`required	`boolean`
`archivedAt`required	`string (date-time)`nullable
`used`required	`boolean`	Posted to at least once: it can then be archived, never deleted.
`balancePence`required	`integer`	The balance now, in pence (debit positive, credit negative).
`createdAt`required	`string (date-time)`
`updatedAt`required	`string (date-time)`

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

Rename or recategorise an account

PATCH/api/v1/books/accounts/{accountId}

Scopes: books:write

The business’s owners and admins (books:admin), or a linked practice whose access lets it post (year-end or full bookkeeping). Codes and classes never change. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for PATCH /api/v1/books/accounts/{accountId}
Name	In	Type	Description
`accountId`required	path	`string (uuid)`

Request body

Required. application/json: object (BooksUpdateAccount).

Rename or recategorise an account. Codes and classes never change.

Request body for PATCH /api/v1/books/accounts/{accountId}
Field	Type	Description
`name`	`string`	up to 120 characters
`ownerName`	`string`	up to 120 characters
`ownerCategory`	`string (BooksOwnerCategory)`	One of: `sales`, `other_income`, `direct_costs`, `staff`, `premises`, `travel`, `office`, `marketing`, `professional`, `finance_costs`, `other_costs`, `write_offs`, `tax`, `bank_and_cash`, `owed_to_you`, `you_owe`, `equipment`, `stock`, `owner`, `behind_the_scenes`
`hint`	`string`nullable	up to 300 characters
`defaultVatCodeId`	`string`nullable

Responses

200 OK, `application/json`

Body: object (BooksAccount).

An account in the business’s chart of accounts. Owners see ownerName under ownerCategoryLabel; accountants see the code, name and class.

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 an unused account

DELETE/api/v1/books/accounts/{accountId}

Scopes: books:write

The business’s owners and admins (books:admin), or a linked practice whose access lets it post (year-end or full bookkeeping). Only an account nothing has ever been posted to; once used, archive it instead (409). Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for DELETE /api/v1/books/accounts/{accountId}
Name	In	Type	Description
`accountId`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).

Archive an account

POST/api/v1/books/accounts/{accountId}/archive

Scopes: books:write

The business’s owners and admins (books:admin), or a linked practice whose access lets it post (year-end or full bookkeeping). Its history stays; it is no longer offered for new entries. Refused for accounts Tolvi keeps and for accounts with a balance. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/accounts/{accountId}/archive
Name	In	Type	Description
`accountId`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (BooksAccount).

An account in the business’s chart of accounts. Owners see ownerName under ownerCategoryLabel; accountants see the code, name and class.

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

Restore an archived account

POST/api/v1/books/accounts/{accountId}/restore

Scopes: books:write

The business’s owners and admins (books:admin), or a linked practice whose access lets it post (year-end or full bookkeeping). Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/accounts/{accountId}/restore
Name	In	Type	Description
`accountId`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (BooksAccount).

An account in the business’s chart of accounts. Owners see ownerName under ownerCategoryLabel; accountants see the code, name and class.

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 one account’s ledger

GET/api/v1/books/accounts/{accountId}/ledger

Scopes: books:read

Postings between two dates with the balance brought forward and a running balance (debit positive). Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/books/accounts/{accountId}/ledger
Name	In	Type	Description
`accountId`required	path	`string (uuid)`
`to`	query	`string (date)`	Last day (inclusive). Defaults to today.
`from`	query	`string (date)`	First day (inclusive). Defaults to the start of the financial year containing `to`.

Responses

200 OK, `application/json`

Body: object (BooksAccountLedger).

One account’s postings between two dates, with the balance brought forward and a running balance.

200 OK response for GET /api/v1/books/accounts/{accountId}/ledger
Field	Type	Description
`account`required	`object (BooksAccount)`	An account in the business’s chart of accounts. Owners see `ownerName` under `ownerCategoryLabel`; accountants see the code, name and class.
`account.id`required	`string (uuid)`
`account.code`required	`string`	Unique in the business; never changes. example "6110"
`account.name`required	`string`	The accountant’s name. example "Light, heat and power"
`account.ownerName`required	`string`	What owners see. example "Gas and electricity"
`account.ownerCategory`required	`string (BooksOwnerCategory)`	One of: `sales`, `other_income`, `direct_costs`, `staff`, `premises`, `travel`, `office`, `marketing`, `professional`, `finance_costs`, `other_costs`, `write_offs`, `tax`, `bank_and_cash`, `owed_to_you`, `you_owe`, `equipment`, `stock`, `owner`, `behind_the_scenes`
`account.ownerCategoryLabel`required	`string`	example "Premises"
`account.hint`required	`string`nullable	One sentence for owners on what goes here.
`account.class`required	`string (BooksAccountClass)`	One of: `asset`, `liability`, `equity`, `income`, `expense`
`account.normalBalance`required	`string (BooksNormalBalance)`	One of: `debit`, `credit`
`account.subtype`required	`string`	example "overhead"
`account.leadLine`required	`string`nullable	The Working Papers lead schedule line the account maps to. example "M.adm"
`account.sa103`required	`string`nullable	The SA103 line (sole traders).
`account.systemRole`required	`string`nullable	Set for accounts Tolvi keeps (control accounts, suspense, retained earnings or capital): they can’t be archived or take a manual journal.
`account.defaultVatCodeId`required	`string`nullable	The VAT code suggested for new lines. example "S20"
`account.fromTemplate`required	`boolean`	Created from the chart template when the business signed up.
`account.archived`required	`boolean`
`account.archivedAt`required	`string (date-time)`nullable
`account.used`required	`boolean`	Posted to at least once: it can then be archived, never deleted.
`account.balancePence`required	`integer`	The balance now, in pence (debit positive, credit negative).
`account.createdAt`required	`string (date-time)`
`account.updatedAt`required	`string (date-time)`
`from`required	`string (date)`	example "2026-03-31"
`to`required	`string (date)`	example "2026-03-31"
`openingPence`required	`integer`	Integer pence (GBP).
`closingPence`required	`integer`	Integer pence (GBP).
`lines`required	`array of BooksAccountLedgerLine`
`lines[].entryId`required	`string (uuid)`
`lines[].seq`required	`integer`
`lines[].lineIndex`required	`integer`
`lines[].date`required	`string (date)`	example "2026-03-31"
`lines[].kind`required	`string (BooksEntryKind)`	One of: `bank`, `invoice`, `credit_note`, `bill`, `bill_credit`, `receipt`, `expense_claim`, `journal`, `opening`, `reversal`, `year_end_adjustment`, `vat_settlement`, `fx_revaluation`
`lines[].description`required	`string`
`lines[].amountPence`required	`integer`	Integer pence (GBP). Debit positive, credit negative.
`lines[].runningBalancePence`required	`integer`	Integer pence (GBP).
`lines[].via`required	`string (BooksPostedVia)`	One of: `web`, `api`, `mcp`, `bank_rule`, `ai_accepted`, `import`, `system`

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

List posted entries

GET/api/v1/books/entries

Scopes: books:read

Newest first, with their lines. Posted entries never change. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/books/entries
Name	In	Type	Description
`limit`	query	`integer`	1 to 100; default 50
`beforeSeq`	query	`integer`	The page before this entry number (from nextBeforeSeq). at least 1
`accountId`	query	`string (uuid)`	Only entries with a line on this account.
`kind`	query	`string`	One of: `bank`, `invoice`, `credit_note`, `bill`, `bill_credit`, `receipt`, `expense_claim`, `journal`, `opening`, `reversal`, `year_end_adjustment`, `vat_settlement`, `fx_revaluation`
`to`	query	`string (date)`	Entries dated on or before.
`from`	query	`string (date)`	Entries dated on or after.

Responses

200 OK, `application/json`

Body: object (BooksEntryPage).

200 OK response for GET /api/v1/books/entries
Field	Type	Description
`items`required	`array of BooksEntry`
`items[].id`required	`string (uuid)`
`items[].seq`required	`integer`	Numbered from 1 per business, without gaps.
`items[].kind`required	`string (BooksEntryKind)`	One of: `bank`, `invoice`, `credit_note`, `bill`, `bill_credit`, `receipt`, `expense_claim`, `journal`, `opening`, `reversal`, `year_end_adjustment`, `vat_settlement`, `fx_revaluation`
`items[].date`required	`string (date)`	example "2026-03-31"
`items[].taxPoint`required	`string (date)`nullable	example "2026-03-31"
`items[].description`required	`string`
`items[].source`required	`object (BooksEntrySource)`nullable
`items[].source.type`required	`string`	example "journal"
`items[].source.id`required	`string`
`items[].source.key`required	`string`nullable
`items[].reversesSeq`required	`integer`nullable
`items[].reversedBySeq`required	`integer`nullable	The entry that reversed this one.
`items[].postedAt`required	`string (date-time)`
`items[].postedBy`required	`object (BooksActor)`
`items[].postedBy.kind`required	`string (BooksActorKind)`	One of: `person`, `rule`, `link`, `system`
`items[].postedBy.id`required	`string`
`items[].postedBy.version`required	`integer`nullable
`items[].via`required	`string (BooksPostedVia)`	One of: `web`, `api`, `mcp`, `bank_rule`, `ai_accepted`, `import`, `system`
`items[].actingFirmId`required	`string (uuid)`nullable	The practice that posted it through its link.
`items[].practiceLinkId`required	`string (uuid)`nullable
`items[].prevHash`required	`string`nullable
`items[].hash`required	`string`	example "sha256:…"
`items[].journalId`required	`string (uuid)`nullable	The manual journal it posted from.
`items[].lines`required	`array of BooksEntryLine`
`items[].lines[].lineIndex`required	`integer`
`items[].lines[].accountId`required	`string (uuid)`
`items[].lines[].accountCode`required	`string`
`items[].lines[].accountName`required	`string`
`items[].lines[].accountOwnerName`required	`string`
`items[].lines[].amountPence`required	`integer`	Integer pence (GBP). Debit positive, credit negative.
`items[].lines[].description`required	`string`nullable
`items[].lines[].contactId`required	`string (uuid)`nullable
`items[].lines[].vat`required	`object (BooksLineVat)`nullable	VAT on a posted line, worked once at posting and never recomputed.
`items[].lines[].vat.vatCodeId`required	`string`	example "S20"
`items[].lines[].vat.side`required	`string (BooksVatSide)`nullable	One of: `sale`, `purchase`
`items[].lines[].vat.netPence`required	`integer`	Integer pence (GBP).
`items[].lines[].vat.vatPence`required	`integer`	Integer pence (GBP).
`items[].lines[].vat.rateVersion`required	`string`nullable	example "S20@2011-01-04"
`items[].lines[].vat.taxPoint`required	`string (date)`nullable	When it differs from the entry’s. example "2026-03-31"
`items[].lines[].vat.cashBasisDate`required	`string (date)`nullable	example "2026-03-31"
`items[].lines[].vat.boxes`required	`array of BooksVatBoxContribution`
`items[].lines[].vat.boxes[].box`required	`integer`	example 1
`items[].lines[].vat.boxes[].amountPence`required	`integer`	Integer pence (GBP).
`items[].lines[].vat.capitalGoods`required	`boolean`nullable
`items[].lines[].vat.frsRelevantGoods`required	`boolean`nullable
`items[].lines[].vat.frsOutsideScheme`required	`boolean`nullable
`nextBeforeSeq`required	`integer`nullable	Pass as beforeSeq for the next (older) page; null on the last page.

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

Get a posted entry

GET/api/v1/books/entries/{entryId}

Scopes: books:read

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

Parameters

Parameters for GET /api/v1/books/entries/{entryId}
Name	In	Type	Description
`entryId`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (BooksEntry).

A posted entry. Posted entries never change: a correction is a reversal and a new entry. hash chains each entry to the one before.

200 OK response for GET /api/v1/books/entries/{entryId}
Field	Type	Description
`id`required	`string (uuid)`
`seq`required	`integer`	Numbered from 1 per business, without gaps.
`kind`required	`string (BooksEntryKind)`	One of: `bank`, `invoice`, `credit_note`, `bill`, `bill_credit`, `receipt`, `expense_claim`, `journal`, `opening`, `reversal`, `year_end_adjustment`, `vat_settlement`, `fx_revaluation`
`date`required	`string (date)`	example "2026-03-31"
`taxPoint`required	`string (date)`nullable	example "2026-03-31"
`description`required	`string`
`source`required	`object (BooksEntrySource)`nullable
`source.type`required	`string`	example "journal"
`source.id`required	`string`
`source.key`required	`string`nullable
`reversesSeq`required	`integer`nullable
`reversedBySeq`required	`integer`nullable	The entry that reversed this one.
`postedAt`required	`string (date-time)`
`postedBy`required	`object (BooksActor)`
`postedBy.kind`required	`string (BooksActorKind)`	One of: `person`, `rule`, `link`, `system`
`postedBy.id`required	`string`
`postedBy.version`required	`integer`nullable
`via`required	`string (BooksPostedVia)`	One of: `web`, `api`, `mcp`, `bank_rule`, `ai_accepted`, `import`, `system`
`actingFirmId`required	`string (uuid)`nullable	The practice that posted it through its link.
`practiceLinkId`required	`string (uuid)`nullable
`prevHash`required	`string`nullable
`hash`required	`string`	example "sha256:…"
`journalId`required	`string (uuid)`nullable	The manual journal it posted from.
`lines`required	`array of BooksEntryLine`
`lines[].lineIndex`required	`integer`
`lines[].accountId`required	`string (uuid)`
`lines[].accountCode`required	`string`
`lines[].accountName`required	`string`
`lines[].accountOwnerName`required	`string`
`lines[].amountPence`required	`integer`	Integer pence (GBP). Debit positive, credit negative.
`lines[].description`required	`string`nullable
`lines[].contactId`required	`string (uuid)`nullable
`lines[].vat`required	`object (BooksLineVat)`nullable	VAT on a posted line, worked once at posting and never recomputed.
`lines[].vat.vatCodeId`required	`string`	example "S20"
`lines[].vat.side`required	`string (BooksVatSide)`nullable	One of: `sale`, `purchase`
`lines[].vat.netPence`required	`integer`	Integer pence (GBP).
`lines[].vat.vatPence`required	`integer`	Integer pence (GBP).
`lines[].vat.rateVersion`required	`string`nullable	example "S20@2011-01-04"
`lines[].vat.taxPoint`required	`string (date)`nullable	When it differs from the entry’s. example "2026-03-31"
`lines[].vat.cashBasisDate`required	`string (date)`nullable	example "2026-03-31"
`lines[].vat.boxes`required	`array of BooksVatBoxContribution`
`lines[].vat.boxes[].box`required	`integer`	example 1
`lines[].vat.boxes[].amountPence`required	`integer`	Integer pence (GBP).
`lines[].vat.capitalGoods`required	`boolean`nullable
`lines[].vat.frsRelevantGoods`required	`boolean`nullable
`lines[].vat.frsOutsideScheme`required	`boolean`nullable

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

Reverse an entry

POST/api/v1/books/entries/{entryId}/reverse

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

Anyone who can write in the books (books:write), including a linked practice with year-end or full bookkeeping access; a read-only link can’t. For opening balances and adjustments posted without a journal: every line is negated, dated on the original’s date or the first open day after it. Void or amend a journal instead; change a bank line or invoice where it came from (409). Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/entries/{entryId}/reverse
Name	In	Type	Description
`entryId`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

Optional. application/json: object (BooksReverseEntry).

Reverse an opening balances entry or an adjustment that isn’t a journal’s (void a journal instead).

Request body for POST /api/v1/books/entries/{entryId}/reverse
Field	Type	Description
`date`	`string (date)`	Defaults to the original’s date, or the first open day after it. example "2026-03-31"
`description`	`string`	up to 500 characters

Responses

201 Created, `application/json`

Body: object (BooksEntry).

A posted entry. Posted entries never change: a correction is a reversal and a new entry. hash chains each entry to the one before.

The fields are as shown above.

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

List journals

GET/api/v1/books/journals

Scopes: books:read

Newest first. Drafts carry the problems that stop them being posted. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/books/journals
Name	In	Type	Description
`status`	query	`string`	One of: `draft`, `posted`, `voided`

Responses

200 OK, `application/json`

Body: array of BooksJournal.

A manual journal. A draft can be edited, discarded or posted; once posted it is changed only by amending it (a reversal and a new entry) or voiding it (a reversal). VAT on lines is posted to the VAT account by Tolvi.

200 OK response for GET /api/v1/books/journals
Field	Type	Description
`[].id`required	`string (uuid)`
`[].status`required	`string (BooksJournalStatus)`	One of: `draft`, `posted`, `voided`
`[].kind`required	`string (BooksJournalKind)`	One of: `journal`, `year_end_adjustment`
`[].date`required	`string (date)`	example "2026-03-31"
`[].description`required	`string`
`[].reference`required	`string`nullable
`[].lines`required	`array of BooksJournalLine`
`[].lines[].accountId`required	`string (uuid)`
`[].lines[].amountPence`required	`integer`	Integer pence (GBP). Debit positive, credit negative. With VAT, the net.
`[].lines[].description`	`string`nullable	up to 200 characters
`[].lines[].vat`	`object (BooksJournalLineVat)`nullable
`[].lines[].vat.vatCodeId`required	`string`	example "S20"
`[].lines[].vat.side`	`string (BooksVatSide)`nullable	One of: `sale`, `purchase`
`[].lines[].vat.netPence`	`integer`nullable	Integer pence (GBP). Defaults to the line’s amount.
`[].lines[].vat.vatPence`	`integer`nullable	Integer pence (GBP). Worked from the rate when left out.
`[].lines[].vat.taxPoint`	`string (date)`nullable	example "2026-03-31"
`[].lines[].vat.capitalGoods`	`boolean`nullable
`[].lines[].vat.frsRelevantGoods`	`boolean`nullable
`[].lines[].vat.frsOutsideScheme`	`boolean`nullable
`[].lines[].vat.workedVatPence`	`integer`nullable	Integer pence (GBP). Read only: the VAT as posting would work it.
`[].debitsPence`required	`integer`	Integer pence (GBP).
`[].creditsPence`required	`integer`	Integer pence (GBP). Positive: the sum of the credit lines.
`[].vatControlPence`required	`integer`	Integer pence (GBP). What Tolvi will post to the VAT account for VAT on the lines (debit positive).
`[].differencePence`required	`integer`	Integer pence (GBP). Debits less credits, including the VAT line: nil when it balances.
`[].problems`required	`array of BooksLedgerProblem`	Why it can’t be posted yet (drafts only).
`[].problems[].code`required	`string`	example "unbalanced"
`[].problems[].message`required	`string`
`[].problems[].line`required	`integer`nullable	Zero-based index of the line it is about.
`[].entryId`required	`string (uuid)`nullable
`[].entrySeq`required	`integer`nullable
`[].voidEntryId`required	`string (uuid)`nullable
`[].createdBy`required	`string (uuid)`nullable
`[].createdAt`required	`string (date-time)`
`[].updatedAt`required	`string (date-time)`
`[].postedAt`required	`string (date-time)`nullable
`[].voidedAt`required	`string (date-time)`nullable

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

Start a journal

POST/api/v1/books/journals

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

Anyone who can write in the books (books:write), including a linked practice with year-end or full bookkeeping access; a read-only link can’t. A draft touches nothing until it is posted. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/journals
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 (BooksCreateJournal).

Request body for POST /api/v1/books/journals
Field	Type	Description
`date`required	`string (date)`	example "2026-03-31"
`description`	`string`	up to 500 characters
`reference`	`string`nullable	up to 60 characters
`kind`	`string (BooksJournalKind)`	journal (default) or year_end_adjustment. One of: `journal`, `year_end_adjustment`
`lines`	`array of BooksJournalLine`
`lines[].accountId`required	`string (uuid)`
`lines[].amountPence`required	`integer`	Integer pence (GBP). Debit positive, credit negative. With VAT, the net.
`lines[].description`	`string`nullable	up to 200 characters
`lines[].vat`	`object (BooksJournalLineVat)`nullable
`lines[].vat.vatCodeId`required	`string`	example "S20"
`lines[].vat.side`	`string (BooksVatSide)`nullable	One of: `sale`, `purchase`
`lines[].vat.netPence`	`integer`nullable	Integer pence (GBP). Defaults to the line’s amount.
`lines[].vat.vatPence`	`integer`nullable	Integer pence (GBP). Worked from the rate when left out.
`lines[].vat.taxPoint`	`string (date)`nullable	example "2026-03-31"
`lines[].vat.capitalGoods`	`boolean`nullable
`lines[].vat.frsRelevantGoods`	`boolean`nullable
`lines[].vat.frsOutsideScheme`	`boolean`nullable
`lines[].vat.workedVatPence`	`integer`nullable	Integer pence (GBP). Read only: the VAT as posting would work it.

Responses

201 Created, `application/json`

Body: object (BooksJournal).

201 Created response for POST /api/v1/books/journals
Field	Type	Description
`id`required	`string (uuid)`
`status`required	`string (BooksJournalStatus)`	One of: `draft`, `posted`, `voided`
`kind`required	`string (BooksJournalKind)`	One of: `journal`, `year_end_adjustment`
`date`required	`string (date)`	example "2026-03-31"
`description`required	`string`
`reference`required	`string`nullable
`lines`required	`array of BooksJournalLine`
`lines[].accountId`required	`string (uuid)`
`lines[].amountPence`required	`integer`	Integer pence (GBP). Debit positive, credit negative. With VAT, the net.
`lines[].description`	`string`nullable	up to 200 characters
`lines[].vat`	`object (BooksJournalLineVat)`nullable
`lines[].vat.vatCodeId`required	`string`	example "S20"
`lines[].vat.side`	`string (BooksVatSide)`nullable	One of: `sale`, `purchase`
`lines[].vat.netPence`	`integer`nullable	Integer pence (GBP). Defaults to the line’s amount.
`lines[].vat.vatPence`	`integer`nullable	Integer pence (GBP). Worked from the rate when left out.
`lines[].vat.taxPoint`	`string (date)`nullable	example "2026-03-31"
`lines[].vat.capitalGoods`	`boolean`nullable
`lines[].vat.frsRelevantGoods`	`boolean`nullable
`lines[].vat.frsOutsideScheme`	`boolean`nullable
`lines[].vat.workedVatPence`	`integer`nullable	Integer pence (GBP). Read only: the VAT as posting would work it.
`debitsPence`required	`integer`	Integer pence (GBP).
`creditsPence`required	`integer`	Integer pence (GBP). Positive: the sum of the credit lines.
`vatControlPence`required	`integer`	Integer pence (GBP). What Tolvi will post to the VAT account for VAT on the lines (debit positive).
`differencePence`required	`integer`	Integer pence (GBP). Debits less credits, including the VAT line: nil when it balances.
`problems`required	`array of BooksLedgerProblem`	Why it can’t be posted yet (drafts only).
`problems[].code`required	`string`	example "unbalanced"
`problems[].message`required	`string`
`problems[].line`required	`integer`nullable	Zero-based index of the line it is about.
`entryId`required	`string (uuid)`nullable
`entrySeq`required	`integer`nullable
`voidEntryId`required	`string (uuid)`nullable
`createdBy`required	`string (uuid)`nullable
`createdAt`required	`string (date-time)`
`updatedAt`required	`string (date-time)`
`postedAt`required	`string (date-time)`nullable
`voidedAt`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).

Get a journal

GET/api/v1/books/journals/{journalId}

Scopes: books:read

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

Parameters

Parameters for GET /api/v1/books/journals/{journalId}
Name	In	Type	Description
`journalId`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (BooksJournal).

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

Change a draft journal

PATCH/api/v1/books/journals/{journalId}

Scopes: books:write

Anyone who can write in the books (books:write), including a linked practice with year-end or full bookkeeping access; a read-only link can’t. Posted journals are amended instead (409). Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for PATCH /api/v1/books/journals/{journalId}
Name	In	Type	Description
`journalId`required	path	`string (uuid)`

Request body

Required. application/json: object (BooksUpdateJournal).

Change a draft. Only the fields sent change; lines replaces every line.

Request body for PATCH /api/v1/books/journals/{journalId}
Field	Type	Description
`date`	`string (date)`	example "2026-03-31"
`description`	`string`	up to 500 characters
`reference`	`string`nullable	up to 60 characters
`kind`	`string (BooksJournalKind)`	One of: `journal`, `year_end_adjustment`
`lines`	`array of BooksJournalLine`
`lines[].accountId`required	`string (uuid)`
`lines[].amountPence`required	`integer`	Integer pence (GBP). Debit positive, credit negative. With VAT, the net.
`lines[].description`	`string`nullable	up to 200 characters
`lines[].vat`	`object (BooksJournalLineVat)`nullable
`lines[].vat.vatCodeId`required	`string`	example "S20"
`lines[].vat.side`	`string (BooksVatSide)`nullable	One of: `sale`, `purchase`
`lines[].vat.netPence`	`integer`nullable	Integer pence (GBP). Defaults to the line’s amount.
`lines[].vat.vatPence`	`integer`nullable	Integer pence (GBP). Worked from the rate when left out.
`lines[].vat.taxPoint`	`string (date)`nullable	example "2026-03-31"
`lines[].vat.capitalGoods`	`boolean`nullable
`lines[].vat.frsRelevantGoods`	`boolean`nullable
`lines[].vat.frsOutsideScheme`	`boolean`nullable
`lines[].vat.workedVatPence`	`integer`nullable	Integer pence (GBP). Read only: the VAT as posting would work it.

Responses

200 OK, `application/json`

Body: object (BooksJournal).

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

Discard a draft journal

DELETE/api/v1/books/journals/{journalId}

Scopes: books:write

Anyone who can write in the books (books:write), including a linked practice with year-end or full bookkeeping access; a read-only link can’t. A posted journal is never deleted: void it (409). Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for DELETE /api/v1/books/journals/{journalId}
Name	In	Type	Description
`journalId`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).

Post a journal

POST/api/v1/books/journals/{journalId}/post

Scopes: books:write

Anyone who can write in the books (books:write), including a linked practice with year-end or full bookkeeping access; a read-only link can’t. It must balance to the penny, use open accounts and be dated after any lock (422 lists every problem). VAT on lines is worked at the rate in force at the tax point and posted to the VAT account by Tolvi. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/journals/{journalId}/post
Name	In	Type	Description
`journalId`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (BooksJournal).

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

Void a posted journal

POST/api/v1/books/journals/{journalId}/void

Scopes: books:write

Anyone who can write in the books (books:write), including a linked practice with year-end or full bookkeeping access; a read-only link can’t. Its entry is reversed, dated on the journal’s date or the first open day after it. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/journals/{journalId}/void
Name	In	Type	Description
`journalId`required	path	`string (uuid)`

Request body

Optional. application/json: object (BooksVoidJournal).

Request body for POST /api/v1/books/journals/{journalId}/void
Field	Type	Description
`date`	`string (date)`	Defaults to the journal’s date, or the first open day after it. example "2026-03-31"

Responses

200 OK, `application/json`

Body: object (BooksJournal).

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

Amend a posted journal

POST/api/v1/books/journals/{journalId}/amend

Scopes: books:write

Anyone who can write in the books (books:write), including a linked practice with year-end or full bookkeeping access; a read-only link can’t. Tolvi reverses the posted entry and posts the journal as sent, in one step. Either is dated in the first open period if its own date is locked. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/journals/{journalId}/amend
Name	In	Type	Description
`journalId`required	path	`string (uuid)`

Request body

Required. application/json: object (BooksAmendJournal).

The journal as it should have been. Tolvi reverses the posted entry and posts this, in one step.

Request body for POST /api/v1/books/journals/{journalId}/amend
Field	Type	Description
`date`required	`string (date)`	example "2026-03-31"
`description`required	`string`	up to 500 characters
`reference`	`string`nullable	up to 60 characters
`lines`required	`array of BooksJournalLine`
`lines[].accountId`required	`string (uuid)`
`lines[].amountPence`required	`integer`	Integer pence (GBP). Debit positive, credit negative. With VAT, the net.
`lines[].description`	`string`nullable	up to 200 characters
`lines[].vat`	`object (BooksJournalLineVat)`nullable
`lines[].vat.vatCodeId`required	`string`	example "S20"
`lines[].vat.side`	`string (BooksVatSide)`nullable	One of: `sale`, `purchase`
`lines[].vat.netPence`	`integer`nullable	Integer pence (GBP). Defaults to the line’s amount.
`lines[].vat.vatPence`	`integer`nullable	Integer pence (GBP). Worked from the rate when left out.
`lines[].vat.taxPoint`	`string (date)`nullable	example "2026-03-31"
`lines[].vat.capitalGoods`	`boolean`nullable
`lines[].vat.frsRelevantGoods`	`boolean`nullable
`lines[].vat.frsOutsideScheme`	`boolean`nullable
`lines[].vat.workedVatPence`	`integer`nullable	Integer pence (GBP). Read only: the VAT as posting would work it.

Responses

200 OK, `application/json`

Body: object (BooksJournal).

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 trial balance at a date

GET/api/v1/books/trial-balance

Scopes: books:read

Derived from posted entries, never stored. Debit positive, credit negative. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/books/trial-balance
Name	In	Type	Description
`includeZero`	query	`string`	One of: `true`, `false`
`throughSeq`	query	`integer`	The ledger as it stood after this entry. at least 0
`yearStart`	query	`string (date)`	Defaults to the start of the financial year containing asAt, from the business’s year end.
`asAt`	query	`string (date)`	Defaults to today.

Responses

200 OK, `application/json`

Body: object (BooksTrialBalance).

The trial balance at a date, derived from posted entries (nothing is stored). Profit and loss before the year start is in retained earnings or the capital account. throughSeq and ledgerHash pin exactly which entries it reflects.

200 OK response for GET /api/v1/books/trial-balance
Field	Type	Description
`asAt`required	`string (date)`	example "2026-03-31"
`yearStart`required	`string (date)`	example "2026-03-31"
`throughSeq`required	`integer`
`ledgerHash`required	`string`nullable
`rows`required	`array of BooksTrialBalanceRow`
`rows[].accountId`required	`string (uuid)`
`rows[].code`required	`string`
`rows[].name`required	`string`
`rows[].ownerName`required	`string`
`rows[].ownerCategory`required	`string (BooksOwnerCategory)`	One of: `sales`, `other_income`, `direct_costs`, `staff`, `premises`, `travel`, `office`, `marketing`, `professional`, `finance_costs`, `other_costs`, `write_offs`, `tax`, `bank_and_cash`, `owed_to_you`, `you_owe`, `equipment`, `stock`, `owner`, `behind_the_scenes`
`rows[].ownerCategoryLabel`required	`string`
`rows[].class`required	`string (BooksAccountClass)`	One of: `asset`, `liability`, `equity`, `income`, `expense`
`rows[].normalBalance`required	`string (BooksNormalBalance)`	One of: `debit`, `credit`
`rows[].leadLine`required	`string`nullable
`rows[].balancePence`required	`integer`	Integer pence (GBP). Debit positive, credit negative.
`totalDebitsPence`required	`integer`	Integer pence (GBP).
`totalCreditsPence`required	`integer`	Integer pence (GBP). Positive: the sum of credit balances.

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

List changes since a ledger point

GET/api/v1/books/ledger/changes

Scopes: books:read

Postings made after throughSeq that change a balance on or before asAt. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/books/ledger/changes
Name	In	Type	Description
`asAt`required	query	`string (date)`	The period end it was taken for.
`throughSeq`required	query	`integer`	The ledger point a trial balance was taken at. at least 0

Responses

200 OK, `application/json`

Body: object (BooksLedgerChanges).

Postings made after a ledger point (throughSeq) that change a balance on or before asAt: what explains a difference since a trial balance was taken.

200 OK response for GET /api/v1/books/ledger/changes
Field	Type	Description
`throughSeq`required	`integer`
`asAt`required	`string (date)`	example "2026-03-31"
`headSeq`required	`integer`	The latest entry now.
`changes`required	`array of BooksLedgerChange`
`changes[].entryId`required	`string (uuid)`
`changes[].seq`required	`integer`
`changes[].lineIndex`required	`integer`
`changes[].accountId`required	`string (uuid)`
`changes[].accountCode`required	`string`
`changes[].date`required	`string (date)`	example "2026-03-31"
`changes[].description`required	`string`
`changes[].amountPence`required	`integer`	Integer pence (GBP).
`changes[].postedAt`required	`string (date-time)`
`changes[].kind`required	`string (BooksEntryKind)`	One of: `bank`, `invoice`, `credit_note`, `bill`, `bill_credit`, `receipt`, `expense_claim`, `journal`, `opening`, `reversal`, `year_end_adjustment`, `vat_settlement`, `fx_revaluation`
`changes[].via`required	`string (BooksPostedVia)`	One of: `web`, `api`, `mcp`, `bank_rule`, `ai_accepted`, `import`, `system`

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

Check the ledger’s hash chain

GET/api/v1/books/ledger/integrity

Scopes: books:read

Re-walks every entry from the first: numbered without gaps, each unchanged since it was posted, each balanced. Part of the books product: the firm must have it and you must have access to it.

Responses

200 OK, `application/json`

Body: object (BooksLedgerIntegrity).

The hash chain re-walked from the first entry: numbering without gaps, each entry unchanged since posting and balanced.

200 OK response for GET /api/v1/books/ledger/integrity
Field	Type	Description
`ok`required	`boolean`
`entries`required	`integer`
`headSeq`required	`integer`
`headHash`required	`string`nullable
`problem`required	`object (BooksLedgerIntegrityProblem)`nullable
`problem.seq`required	`integer`
`problem.kind`required	`string (BooksIntegrityProblemKind)`	One of: `sequence_gap`, `prev_hash_mismatch`, `hash_mismatch`, `unbalanced`
`problem.message`required	`string`

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

Get the period locks

GET/api/v1/books/locks

Scopes: books:read

The locks in force, their history and the first open date. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/books/locks
Name	In	Type	Description
`date`	query	`string (date)`	A date to check: dateProblem says why it can’t take an entry. Defaults to today.

Responses

200 OK, `application/json`

Body: object (BooksLocks).

The locks in force. owner: the business closed its books to a date (it or its practice can move it). accountant: the practice locked them after year-end sign-off (only it can reopen them). vatFiled: set by Tolvi when HMRC accepts a VAT return; never lifted.

200 OK response for GET /api/v1/books/locks
Field	Type	Description
`owner`required	`object (BooksLockState)`nullable
`owner.through`required	`string (date)`	Nothing new may be dated on or before this day. example "2026-03-31"
`owner.at`required	`string (date-time)`
`owner.byKind`required	`string (BooksLockBy)`	One of: `owner`, `practice`, `system`
`owner.byName`required	`string`nullable	The practice’s name, for an accountant’s lock.
`owner.linkId`required	`string (uuid)`nullable
`owner.reference`required	`string`nullable
`accountant`required	`object (BooksLockState)`nullable
`accountant.through`required	`string (date)`	Nothing new may be dated on or before this day. example "2026-03-31"
`accountant.at`required	`string (date-time)`
`accountant.byKind`required	`string (BooksLockBy)`	One of: `owner`, `practice`, `system`
`accountant.byName`required	`string`nullable	The practice’s name, for an accountant’s lock.
`accountant.linkId`required	`string (uuid)`nullable
`accountant.reference`required	`string`nullable
`vatFiled`required	`object (BooksLockState)`nullable
`vatFiled.through`required	`string (date)`	Nothing new may be dated on or before this day. example "2026-03-31"
`vatFiled.at`required	`string (date-time)`
`vatFiled.byKind`required	`string (BooksLockBy)`	One of: `owner`, `practice`, `system`
`vatFiled.byName`required	`string`nullable	The practice’s name, for an accountant’s lock.
`vatFiled.linkId`required	`string (uuid)`nullable
`vatFiled.reference`required	`string`nullable
`firstOpenDate`required	`string (date)`	example "2026-03-31"
`date`required	`string (date)`	example "2026-03-31"
`dateProblem`required	`string`nullable
`events`required	`array of BooksLockEvent`
`events[].id`required	`string (uuid)`
`events[].kind`required	`string (BooksLockKind)`	One of: `owner`, `vat_filed`, `accountant`
`events[].action`required	`string (BooksLockAction)`	One of: `lock`, `unlock`
`events[].through`required	`string (date)`nullable	example "2026-03-31"
`events[].at`required	`string (date-time)`
`events[].byKind`required	`string (BooksLockBy)`	One of: `owner`, `practice`, `system`
`events[].byName`required	`string`nullable
`events[].byUserId`required	`string (uuid)`nullable
`events[].linkId`required	`string (uuid)`nullable
`events[].reason`required	`string`nullable
`events[].reference`required	`string`nullable

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

Lock or unlock the books

POST/api/v1/books/locks

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

Needs a signed-in person (never a token or connected app). The owner lock: the business’s owners and admins, or a linked practice that can post. The accountant’s year-end lock: only a linked practice, and only the practice that set it can reopen the year, with a reason. The VAT lock is set by Tolvi when HMRC accepts a return and can’t be changed here. Part of the books product: the firm must have it and you must have access to it.

Request body

Required. application/json: object (BooksChangeLock).

Lock the books through a date, or move a lock back (with through) or lift it (no through).

Request body for POST /api/v1/books/locks
Field	Type	Description
`kind`required	`string (BooksPersonLockKind)`	owner: the business’s own lock. accountant: the practice’s year-end lock (practices only). One of: `owner`, `accountant`
`action`required	`string (BooksLockAction)`	One of: `lock`, `unlock`
`through`	`string (date)`nullable	example "2026-03-31"
`reason`	`string`	Needed to reopen a year the accountant locked. up to 500 characters
`reference`	`string`	e.g. the engagement behind a year-end lock. up to 100 characters

Responses

200 OK, `application/json`

Body: object (BooksLocks).

The fields are as shown above.

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

Get the opening balances in force

GET/api/v1/books/opening-balances

Scopes: books:read

The opening entry in force, if any, the suggested start date, and the accounts each plain-English question posts to. Part of the books product: the firm must have it and you must have access to it.

Responses

200 OK, `application/json`

Body: object (BooksOpeningStatus).

Whether the books have a start, and what the opening balances screen needs.

200 OK response for GET /api/v1/books/opening-balances
Field	Type	Description
`suggestedStartDate`required	`string (date)`	The first day of this financial year. example "2026-03-31"
`standing`required	`object (BooksOpeningStanding)`nullable	The opening entry in force.
`standing.entryId`required	`string (uuid)`
`standing.seq`required	`integer`
`standing.entryDate`required	`string (date)`	example "2026-03-31"
`standing.startDate`required	`string (date)`	The first day the books cover. example "2026-03-31"
`standing.fromWorkingPapers`required	`boolean`	Posted from a final trial balance in Working Papers.
`standing.postedAt`required	`string (date-time)`
`standing.lines`required	`array of BooksOpeningEntryLine`
`standing.lines[].accountId`required	`string (uuid)`
`standing.lines[].accountCode`required	`string`
`standing.lines[].accountName`required	`string`
`standing.lines[].ownerName`required	`string`
`standing.lines[].normalBalance`required	`string (BooksNormalBalance)`	One of: `debit`, `credit`
`standing.lines[].amountPence`required	`integer`	Integer pence (GBP). Debit positive, credit negative.
`standing.lines[].contactName`required	`string`nullable	The customer or supplier, on a control account line split by unpaid invoice or bill.
`standing.suspensePence`required	`integer`	Integer pence (GBP).
`standing.unpaidInvoices`required	`array of BooksOpeningStandingInvoice`
`standing.unpaidInvoices[].id`required	`string (uuid)`
`standing.unpaidInvoices[].number`required	`string`
`standing.unpaidInvoices[].customerName`required	`string`
`standing.unpaidInvoices[].amountPence`required	`integer`	Integer pence (GBP).
`standing.unpaidInvoices[].outstandingPence`required	`integer`	Integer pence (GBP).
`standing.unpaidBills`required	`array of BooksOpeningStandingBill`
`standing.unpaidBills[].id`required	`string (uuid)`
`standing.unpaidBills[].reference`required	`string`
`standing.unpaidBills[].supplierName`required	`string`
`standing.unpaidBills[].amountPence`required	`integer`	Integer pence (GBP).
`standing.unpaidBills[].outstandingPence`required	`integer`	Integer pence (GBP).
`guided`required	`object (BooksOpeningGuidedAccounts)`	The accounts each plain-English question posts to.
`guided.bank`required	`array of BooksOpeningAccountRef`
`guided.bank[].code`required	`string`
`guided.bank[].name`required	`string`
`guided.bank[].ownerName`required	`string`
`guided.debtors`required	`object (BooksOpeningAccountRef)`nullable
`guided.debtors.code`required	`string`
`guided.debtors.name`required	`string`
`guided.debtors.ownerName`required	`string`
`guided.creditors`required	`object (BooksOpeningAccountRef)`nullable
`guided.creditors.code`required	`string`
`guided.creditors.name`required	`string`
`guided.creditors.ownerName`required	`string`
`guided.vat`required	`object (BooksOpeningAccountRef)`nullable
`guided.vat.code`required	`string`
`guided.vat.name`required	`string`
`guided.vat.ownerName`required	`string`
`guided.loan`required	`object (BooksOpeningAccountRef)`nullable
`guided.loan.code`required	`string`
`guided.loan.name`required	`string`
`guided.loan.ownerName`required	`string`
`guided.worth`required	`object (BooksOpeningAccountRef)`nullable	Where the difference goes when it is what the business was worth.
`guided.worth.code`required	`string`
`guided.worth.name`required	`string`
`guided.worth.ownerName`required	`string`
`vatRegistered`required	`boolean`
`vatScheme`required	`string`nullable
`canSetUp`required	`boolean`	This person can post and reverse opening balances.

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

Post opening balances

POST/api/v1/books/opening-balances

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

The business’s owners and admins (books:admin), or a linked practice whose access lets it post (year-end or full bookkeeping). One entry dated the day before the books start. Every balance must have an account (422 lists any that don’t); a difference goes to suspense. Refused while earlier opening balances stand (409). Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/opening-balances
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 (BooksOpeningBalancesInput).

Opening balances from a trial balance (as accounts, or the CSV text of an export), at the date the books start.

Request body for POST /api/v1/books/opening-balances
Field	Type	Description
`conversionDate`required	`string (date)`	The first day the books cover; the entry is dated the day before. example "2026-03-31"
`accounts`	`array of object`
`accounts[].code`required	`string`
`accounts[].name`	`string`
`accounts[].balancePence`required	`integer`	Integer pence (GBP). Debit positive, credit negative.
`accounts[].leadLine`	`string`nullable
`csv`	`string`	A trial balance export as CSV text (code, name, debit, credit or balance).
`mapping`	`object`	Source code to an account code in these books.
`differenceTo`	`string (BooksOpeningDifferenceTo)`	suspense (the default): a difference is an error for the accountant to clear. equity: it is what the business was worth (capital or reserves). One of: `suspense`, `equity`
`unpaidInvoices`	`array of BooksOpeningUnpaidInvoiceInput`	Invoices issued before the books start and not yet paid. They are part of the debtors balance and can be paid and chased like any other.
`unpaidInvoices[].customerId`	`string (uuid)`
`unpaidInvoices[].customerName`	`string`	up to 200 characters
`unpaidInvoices[].number`required	`string`	The number it was issued with, outside Tolvi’s own series. up to 60 characters
`unpaidInvoices[].issueDate`required	`string (date)`	example "2026-03-31"
`unpaidInvoices[].dueDate`	`string (date)`	Defaults to the business’s usual payment terms. example "2026-03-31"
`unpaidInvoices[].amountPence`required	`integer`	Integer pence (GBP). What is still owed, including any VAT.
`unpaidBills`	`array of BooksOpeningUnpaidBillInput`	Bills dated before the books start and not yet paid. They are part of the creditors balance and can be paid and matched like any other, with no VAT breakdown.
`unpaidBills[].supplierId`	`string (uuid)`
`unpaidBills[].supplierName`	`string`	up to 200 characters
`unpaidBills[].reference`required	`string`	The supplier’s own invoice number. up to 60 characters
`unpaidBills[].billDate`required	`string (date)`	example "2026-03-31"
`unpaidBills[].dueDate`	`string (date)`	Defaults to the supplier’s payment terms, or 30 days. example "2026-03-31"
`unpaidBills[].amountPence`required	`integer`	Integer pence (GBP). What is still owed, including any VAT.

Responses

201 Created, `application/json`

Body: object (BooksOpeningBalancesPosted).

201 Created response for POST /api/v1/books/opening-balances
Field	Type	Description
`entry`required	`object (BooksEntry)`	A posted entry. Posted entries never change: a correction is a reversal and a new entry. `hash` chains each entry to the one before.
`entry.id`required	`string (uuid)`
`entry.seq`required	`integer`	Numbered from 1 per business, without gaps.
`entry.kind`required	`string (BooksEntryKind)`	One of: `bank`, `invoice`, `credit_note`, `bill`, `bill_credit`, `receipt`, `expense_claim`, `journal`, `opening`, `reversal`, `year_end_adjustment`, `vat_settlement`, `fx_revaluation`
`entry.date`required	`string (date)`	example "2026-03-31"
`entry.taxPoint`required	`string (date)`nullable	example "2026-03-31"
`entry.description`required	`string`
`entry.source`required	`object (BooksEntrySource)`nullable
`entry.source.type`required	`string`	example "journal"
`entry.source.id`required	`string`
`entry.source.key`required	`string`nullable
`entry.reversesSeq`required	`integer`nullable
`entry.reversedBySeq`required	`integer`nullable	The entry that reversed this one.
`entry.postedAt`required	`string (date-time)`
`entry.postedBy`required	`object (BooksActor)`
`entry.postedBy.kind`required	`string (BooksActorKind)`	One of: `person`, `rule`, `link`, `system`
`entry.postedBy.id`required	`string`
`entry.postedBy.version`required	`integer`nullable
`entry.via`required	`string (BooksPostedVia)`	One of: `web`, `api`, `mcp`, `bank_rule`, `ai_accepted`, `import`, `system`
`entry.actingFirmId`required	`string (uuid)`nullable	The practice that posted it through its link.
`entry.practiceLinkId`required	`string (uuid)`nullable
`entry.prevHash`required	`string`nullable
`entry.hash`required	`string`	example "sha256:…"
`entry.journalId`required	`string (uuid)`nullable	The manual journal it posted from.
`entry.lines`required	`array of BooksEntryLine`
`entry.lines[].lineIndex`required	`integer`
`entry.lines[].accountId`required	`string (uuid)`
`entry.lines[].accountCode`required	`string`
`entry.lines[].accountName`required	`string`
`entry.lines[].accountOwnerName`required	`string`
`entry.lines[].amountPence`required	`integer`	Integer pence (GBP). Debit positive, credit negative.
`entry.lines[].description`required	`string`nullable
`entry.lines[].contactId`required	`string (uuid)`nullable
`entry.lines[].vat`required	`object (BooksLineVat)`nullable	VAT on a posted line, worked once at posting and never recomputed.
`entry.lines[].vat.vatCodeId`required	`string`	example "S20"
`entry.lines[].vat.side`required	`string (BooksVatSide)`nullable	One of: `sale`, `purchase`
`entry.lines[].vat.netPence`required	`integer`	Integer pence (GBP).
`entry.lines[].vat.vatPence`required	`integer`	Integer pence (GBP).
`entry.lines[].vat.rateVersion`required	`string`nullable	example "S20@2011-01-04"
`entry.lines[].vat.taxPoint`required	`string (date)`nullable	When it differs from the entry’s. example "2026-03-31"
`entry.lines[].vat.cashBasisDate`required	`string (date)`nullable	example "2026-03-31"
`entry.lines[].vat.boxes`required	`array of BooksVatBoxContribution`
`entry.lines[].vat.boxes[].box`required	`integer`	example 1
`entry.lines[].vat.boxes[].amountPence`required	`integer`	Integer pence (GBP).
`entry.lines[].vat.capitalGoods`required	`boolean`nullable
`entry.lines[].vat.frsRelevantGoods`required	`boolean`nullable
`entry.lines[].vat.frsOutsideScheme`required	`boolean`nullable
`suspensePence`required	`integer`	Integer pence (GBP).
`warnings`required	`array of string`

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

Preview opening balances

POST/api/v1/books/opening-balances/preview

Scopes: books:write

The business’s owners and admins (books:admin), or a linked practice whose access lets it post (year-end or full bookkeeping). Where each balance would go and the entry that would be posted. Nothing is saved. Part of the books product: the firm must have it and you must have access to it.

Request body

Required. application/json: object (BooksOpeningBalancesInput).

Opening balances from a trial balance (as accounts, or the CSV text of an export), at the date the books start.

The fields are as shown above.

Responses

200 OK, `application/json`

Body: object (BooksOpeningBalancesPreview).

Where each balance would go, the entry that would be posted, and anything that must be mapped first.

200 OK response for POST /api/v1/books/opening-balances/preview
Field	Type	Description
`conversionDate`required	`string (date)`	example "2026-03-31"
`entryDate`required	`string (date)`	example "2026-03-31"
`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). What went to suspense to make it balance (debit positive).
`equityPence`required	`integer`	Integer pence (GBP). What went to capital or reserves to make it balance (debit positive).
`warnings`required	`array of string`
`problems`required	`array of string`	What stops it being posted, in words.
`unpaidInvoices`required	`array of BooksOpeningUnpaidInvoice`
`unpaidInvoices[].customerName`required	`string`
`unpaidInvoices[].newCustomer`required	`boolean`	The customer will be added.
`unpaidInvoices[].number`required	`string`
`unpaidInvoices[].issueDate`required	`string (date)`	example "2026-03-31"
`unpaidInvoices[].dueDate`required	`string (date)`	example "2026-03-31"
`unpaidInvoices[].amountPence`required	`integer`	Integer pence (GBP).
`unpaidBills`required	`array of BooksOpeningUnpaidBill`
`unpaidBills[].supplierName`required	`string`
`unpaidBills[].newSupplier`required	`boolean`	The supplier will be added.
`unpaidBills[].reference`required	`string`
`unpaidBills[].billDate`required	`string (date)`	example "2026-03-31"
`unpaidBills[].dueDate`required	`string (date)`	example "2026-03-31"
`unpaidBills[].amountPence`required	`integer`	Integer pence (GBP).
`alreadyPosted`required	`boolean`

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

Get the getting-started checklist

GET/api/v1/books/getting-started

Scopes: books:read

Six steps for a new business, each ticked from real data: business details, a bank, starting balances, how invoices look, VAT and an accountant. Part of the books product: the firm must have it and you must have access to it.

Responses

200 OK, `application/json`

Body: object (BooksGettingStarted).

The new business checklist, worked out from the business’s own data on every read.

200 OK response for GET /api/v1/books/getting-started
Field	Type	Description
`steps`required	`array of BooksGettingStartedStep`
`steps[].key`required	`string (BooksGettingStartedKey)`	One of: `details`, `bank`, `opening`, `invoices`, `vat`, `accountant`
`steps[].label`required	`string`
`steps[].done`required	`boolean`
`steps[].detail`required	`string`nullable	How it was done, when that needs saying.
`doneCount`required	`integer`
`complete`required	`boolean`	Every step is done.
`hidden`required	`boolean`	The owner hid the list from Home.
`notVatRegistered`required	`boolean`	The business said it isn’t registered for VAT.
`noOpeningBalances`required	`boolean`	The business said it has nothing to bring forward.

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

Answer or hide the getting-started checklist

PUT/api/v1/books/getting-started

Scopes: books:write

Hide the list or bring it back, and the two answers only a person can give: not registered for VAT, and nothing to bring forward. The business’s owners and admins, or a practice with a link that can post. Part of the books product: the firm must have it and you must have access to it.

Request body

Required. application/json: object (BooksUpdateGettingStarted).

Answers only a person can give. The ticks themselves come from the books.

Request body for PUT /api/v1/books/getting-started
Field	Type	Description
`hidden`	`boolean`	Hide the list from Home, or bring it back.
`notVatRegistered`	`boolean`	The business isn’t registered for VAT, so that step is done.
`noOpeningBalances`	`boolean`	A brand-new business with nothing to bring forward, so the starting balances step is done.

Responses

200 OK, `application/json`

Body: object (BooksGettingStarted).

The new business checklist, worked out from the business’s own data on every read.

The fields are as shown above.

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

Books

Sign a business up to Tolvi Books

Request body

Responses

202 Accepted, application/json

403 Forbidden

Get the business’s profile

Responses

200 OK, application/json

Change the business’s details

Request body

Responses

200 OK, application/json

List the business’s accountants

Responses

200 OK, application/json

Invite an accountant

Parameters

Request body

Responses

201 Created, application/json

Change an accountant’s access

Parameters

Request body

Responses

200 OK, application/json

End an accountant’s access

Parameters

Request body

Responses

200 OK, application/json

List practices’ requests for access

Responses

200 OK, application/json

Approve a practice’s request

Parameters

Request body

Responses

200 OK, application/json

Decline a practice’s request

Parameters

Responses

200 OK, application/json

List the firm’s links to businesses’ books

Responses

200 OK, application/json

Ask a business for access to its books

Parameters

Request body

Responses

201 Created, application/json

See what a business’s invitation offers

Request body

Responses

200 OK, application/json

Accept a business’s invitation

Request body

Responses

200 OK, application/json

End the firm’s access to a business’s books

Parameters

Request body

Responses

200 OK, application/json

Set Tolvi Books up for a client

Parameters

Request body

Responses

201 Created, application/json

Invite the owner of a business the firm set up

Parameters

Request body

Responses

200 OK, application/json

List clients’ books

Responses

200 OK, application/json

Get the chart of accounts

Responses

200 OK, application/json

202 Accepted, `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`

201 Created, `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`

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`

201 Created, `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`