Skip to main content
BETA
MenuClose

Filing queue

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

What could be filed

GET/api/v1/filing-batches/ready

Role
Manager or above
Access
A signed-in Tolvi session only, never an API token.

Self Assessment returns, Company Tax Returns and Companies House accounts approved in your products. Where a product’s filing is off, the row says it opens soon. Never available to API keys or connected assistants.

Needs the Manager role or above.

Responses

200 OK, application/json

Body: object (FilingReadyList).

200 OK response for GET /api/v1/filing-batches/ready
FieldTypeDescription
itemsrequiredarray of FilingReadyItem
items[].​productrequiredstring (FilingProduct)

One of: self_assessment, corporation_tax, companies_house

items[].​returnIdrequiredstring (uuid)
items[].​clientIdrequiredstring (uuid)
items[].​clientNamerequiredstring
items[].​labelrequiredstring
items[].​figuresHashrequiredstring
items[].​canFilerequiredboolean

Whether this can go in a batch today.

items[].​reasonrequiredstringnullable
items[].​filingOpenrequiredboolean
items[].​opensSoonMessagerequiredstringnullable

Shown instead of a way to file while the switch is off.

productsrequiredarray of FilingProductState
products[].​productrequiredstring (FilingProduct)

One of: self_assessment, corporation_tax, companies_house

products[].​filingOpenrequiredboolean
products[].​opensSoonMessagerequiredstringnullable
declarationsrequiredobject

The declarations a person accepts to start a batch, by product.

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

List batches

GET/api/v1/filing-batches

Role
Manager or above
Access
A signed-in Tolvi session only, never an API token.

Never available to API keys or connected assistants.

Needs the Manager role or above.

Responses

200 OK, application/json

Body: object (FilingBatchList).

200 OK response for GET /api/v1/filing-batches
FieldTypeDescription
itemsrequiredarray of FilingBatch
items[].​idrequiredstring (uuid)
items[].​statusrequiredstring (FilingBatchStatus)

One of: ready, running, finished

items[].​createdAtrequiredstring (date-time)
items[].​startedAtrequiredstring (date-time)nullable
items[].​finishedAtrequiredstring (date-time)nullable
items[].​itemsrequiredarray of FilingBatchItem
items[].​items[].​idrequiredstring (uuid)
items[].​items[].​positionrequiredinteger
items[].​items[].​productrequiredstring (FilingProduct)

One of: self_assessment, corporation_tax, companies_house

items[].​items[].​returnIdrequiredstring (uuid)
items[].​items[].​clientNamerequiredstring
items[].​items[].​labelrequiredstring
items[].​items[].​statusrequiredstring (FilingItemStatus)

One of: waiting, sending, filed, with_authority, test_accepted, refused, rejected, no_answer

items[].​items[].​messagerequiredstringnullable

In plain words.

items[].​items[].​finishedAtrequiredstring (date-time)nullable

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

Build a batch

POST/api/v1/filing-batches

Role
Manager or above
Access
A signed-in Tolvi session only, never an API token.

Nothing is sent. Answers 503 while batch filing or any chosen product’s filing is 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.

Request body

Required. application/json: object (CreateFilingBatch).

Request body for POST /api/v1/filing-batches
FieldTypeDescription
itemsrequiredarray of FilingBatchNewItem
items[].​productrequiredstring (FilingProduct)

One of: self_assessment, corporation_tax, companies_house

items[].​returnIdrequiredstring (uuid)
items[].​figuresHashrequiredstring

The hash you reviewed. A change since is refused.

items[].​accountIdrequiredstring (uuid)

The HMRC account or Companies House presenter to file with.

items[].​variantstring (FilingVariant)

One of: full, filleted

Responses

200 OK, application/json

Body: object (FilingBatch).

200 OK response for POST /api/v1/filing-batches
FieldTypeDescription
idrequiredstring (uuid)
statusrequiredstring (FilingBatchStatus)

One of: ready, running, finished

createdAtrequiredstring (date-time)
startedAtrequiredstring (date-time)nullable
finishedAtrequiredstring (date-time)nullable
itemsrequiredarray of FilingBatchItem
items[].​idrequiredstring (uuid)
items[].​positionrequiredinteger
items[].​productrequiredstring (FilingProduct)

One of: self_assessment, corporation_tax, companies_house

items[].​returnIdrequiredstring (uuid)
items[].​clientNamerequiredstring
items[].​labelrequiredstring
items[].​statusrequiredstring (FilingItemStatus)

One of: waiting, sending, filed, with_authority, test_accepted, refused, rejected, no_answer

items[].​messagerequiredstringnullable

In plain words.

items[].​finishedAtrequiredstring (date-time)nullable

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

A batch and each return’s status

GET/api/v1/filing-batches/{id}

Role
Manager or above
Access
A signed-in Tolvi session only, never an API token.

Never available to API keys or connected assistants.

Needs the Manager role or above.

Parameters

Parameters for GET /api/v1/filing-batches/{id}
NameInTypeDescription
idrequiredpathstring (uuid)

Responses

200 OK, application/json

Body: object (FilingBatch).

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

Start a batch

POST/api/v1/filing-batches/{id}/start

Role
Manager or above
Access
A signed-in Tolvi session only, never an API token.
Retries
Send an Idempotency-Key to make retries safe.

A manager or partner with a second factor. Each return goes through its own product’s filing, one at a time, with every control that has. A refusal stops that return and not the rest. 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.

Parameters

Parameters for POST /api/v1/filing-batches/{id}/start
NameInTypeDescription
idrequiredpathstring (uuid)
Idempotency-Keyheaderstring

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

Request body for POST /api/v1/filing-batches/{id}/start
FieldTypeDescription
declarationsobject

The declaration accepted for each product in the batch: { accepted: true, version }.

companyCodesobject

Companies House company authentication codes by item id. Used once, never stored.

Responses

200 OK, application/json

Body: object (FilingBatch).

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