Practice VAT
7 operations in the Tolvi API, version 1. Paths are relative to https://api.tolvi.co.uk. Every amount is integer pence.
List clients’ VAT returns
GET/api/v1/practice-vat/returns
- Scopes
self_assessment:read
Part of the self_assessment product: the firm must have it and you must have access to it.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
clientId | query | string (uuid) |
Responses
200 OK, application/json
Body: object (PracticeVatReturnList).
| Field | Type | Description |
|---|---|---|
itemsrequired | array of PracticeVatReturn | |
items[].idrequired | string (uuid) | |
items[].clientIdrequired | string (uuid) | |
items[].clientName | string | |
items[].vrnrequired | string | |
items[].periodKeyrequired | string | |
items[].periodStartrequired | string (date) | example "2026-03-31" |
items[].periodEndrequired | string (date) | example "2026-03-31" |
items[].boxesrequired | object | box1 to box9, integer pence. |
items[].sourcerequired | string (PracticeVatSource) | One of: |
items[].sourceNoterequired | stringnullable | |
items[].statusrequired | string (PracticeVatStatus) | One of: |
items[].submissionStatusrequired | stringnullable | |
items[].receiptrequired | objectnullable | |
items[].lastErrorrequired | stringnullable | |
items[].returnHashrequired | string | |
items[].clientApprovedOnrequired | string (date)nullable | example "2026-03-31" |
items[].clientApprovalCurrentrequired | boolean | |
items[].canSubmitrequired | boolean | |
items[].cannotSubmitReasonrequired | stringnullable | |
items[].filingEnabledrequired | boolean | |
items[].declarationrequired | object |
Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).
Prepare a client’s VAT return
POST/api/v1/practice-vat/returns
- Scopes
self_assessment:write- Role
- Preparer or above
From a bridging sheet, or nine boxes typed or carried from Working Papers or Books and labelled so.
Needs the Preparer role or above. Part of the self_assessment product: the firm must have it and you must have access to it.
Request body
Required. application/json: object (CreatePracticeVatReturn).
| Field | Type | Description |
|---|---|---|
clientIdrequired | string (uuid) | |
vrn | string | Left out, the VAT number on the client’s record. The return keeps the number it was prepared under. |
periodKeyrequired | string | HMRC’s period key, from the client’s VAT account. |
periodStartrequired | string (date) | example "2026-03-31" |
periodEndrequired | string (date) | example "2026-03-31" |
sourcerequired | string (PracticeVatSource) | One of: |
sourceNote | string | |
rows | array of array of string | |
boxes | object |
Responses
200 OK, application/json
Body: object (PracticeVatReturn).
| Field | Type | Description |
|---|---|---|
idrequired | string (uuid) | |
clientIdrequired | string (uuid) | |
clientName | string | |
vrnrequired | string | |
periodKeyrequired | string | |
periodStartrequired | string (date) | example "2026-03-31" |
periodEndrequired | string (date) | example "2026-03-31" |
boxesrequired | object | box1 to box9, integer pence. |
sourcerequired | string (PracticeVatSource) | One of: |
sourceNoterequired | stringnullable | |
statusrequired | string (PracticeVatStatus) | One of: |
submissionStatusrequired | stringnullable | |
receiptrequired | objectnullable | |
lastErrorrequired | stringnullable | |
returnHashrequired | string | |
clientApprovedOnrequired | string (date)nullable | example "2026-03-31" |
clientApprovalCurrentrequired | boolean | |
canSubmitrequired | boolean | |
cannotSubmitReasonrequired | stringnullable | |
filingEnabledrequired | boolean | |
declarationrequired | object |
Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).
Read a bridging sheet
POST/api/v1/practice-vat/returns/read-sheet
- Scopes
self_assessment:write- Role
- Preparer or above
Says what the rows give, and what’s wrong. Keeps nothing.
Needs the Preparer role or above. Part of the self_assessment product: the firm must have it and you must have access to it.
Request body
Required. application/json: object (SpreadsheetRows).
| Field | Type | Description |
|---|---|---|
rowsrequired | array of array of string | Label, then amount in pounds. |
Responses
200 OK, application/json
Body: object (PracticeVatSheetReading).
| Field | Type | Description |
|---|---|---|
boxesrequired | objectnullable | |
problemsrequired | array of string | |
ignoredrequired | array of string |
Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).
A client’s VAT return
GET/api/v1/practice-vat/returns/{id}
- Scopes
self_assessment:read
Part of the self_assessment product: the firm must have it and you must have access to it.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string (uuid) |
Responses
Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).
Approve
POST/api/v1/practice-vat/returns/{id}/approve
- Scopes
self_assessment:write- Role
- Manager or above
- Access
- A signed-in Tolvi session only, never an API token.
By the firm’s approver setting, against the hash reviewed. Never available to API keys or connected assistants.
Needs the Manager role or above. Part of the self_assessment product: the firm must have it and you must have access to it.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string (uuid) |
Request body
Required. application/json: object (PracticeVatHash).
| Field | Type | Description |
|---|---|---|
returnHashrequired | string |
Responses
Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).
Record the client’s approval
POST/api/v1/practice-vat/returns/{id}/client-approval
- Scopes
self_assessment:write- Role
- Preparer or above
- Access
- A signed-in Tolvi session only, never an API token.
Never available to API keys or connected assistants.
Needs the Preparer role or above. Part of the self_assessment product: the firm must have it and you must have access to it.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string (uuid) |
Request body
Required. application/json: object (PracticeVatClientApproval).
| Field | Type | Description |
|---|---|---|
approvedOnrequired | string (date) | example "2026-03-31" |
returnHashrequired | string |
Responses
Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).
File with HMRC
POST/api/v1/practice-vat/returns/{id}/submit
- Scopes
self_assessment:write- Role
- Manager or above
- Access
- A signed-in Tolvi session only, never an API token.
- Retries
- Send an
Idempotency-Keyto make retries safe.
A manager or partner with a second factor, once approved and the client has approved. Answers 503 while off. Off by default. It has only run against a fake: HMRC has not reviewed or accepted any of it. Never available to API keys or connected assistants.
Needs the Manager role or above. Part of the self_assessment product: the firm must have it and you must have access to it.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string (uuid) | |
Idempotency-Key | header | string | A unique key (1-255 visible characters) to make retries safe. Replayed for 24 hours. 1 to 255 characters |
Request body
Required. application/json: object (SubmitPracticeVat).
| Field | Type | Description |
|---|---|---|
returnHashrequired | string | |
declarationrequired | object | |
clientFactsrequired | object | The browser’s facts, for HMRC’s fraud prevention headers. |
Responses
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).