Skip to main content

Imports

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

List imports

GET/api/v1/imports

Scopes
clients:read

The firm’s latest imports, newest first, with how far each has got. Part of the hub product: the firm must have it and you must have access to it.

Responses

200 OK, application/json

Body: object (ImportBatchList).

200 OK response for GET /api/v1/imports
FieldTypeDescription
batchesrequiredarray of ImportBatch
batches[].​idrequiredstring (uuid)
batches[].​kindrequiredstring (ImportKind)

One of: clients, trial_balance, ct_opening, sa_prior_year

batches[].​statusrequiredstring (ImportStatus)

One of: pending_upload, pending_scan, reading, needs_mapping, checking, ready, importing, completed, undoing, undone, failed, rejected

batches[].​fileNamerequiredstring
batches[].​sizeBytesrequiredinteger
batches[].​problemrequiredstringnullable

Why it stopped, in plain words.

batches[].​noticesrequiredarray of string

About the file as a whole, such as columns left out.

batches[].​sheetsrequiredarray of string
batches[].​sheetrequiredstringnullable
batches[].​headerLinerequiredintegernullable

The line or row the headings were found on.

batches[].​columnsrequiredarray of ImportColumn
batches[].​columns[].​columnrequiredinteger
batches[].​columns[].​headerrequiredstring
batches[].​columns[].​fieldrequiredstringnullable

The field it goes to, or null to ignore it.

batches[].​columns[].​confidencerequiredstring (ImportColumnConfidence)

One of: exact, close, none

batches[].​columns[].​refusedstring

Set when Tolvi won’t keep this column, with what it holds.

batches[].​columns[].​samplesrequiredarray of string

The first few values.

batches[].​clientIdrequiredstring (uuid)nullable

Trial balance: whose.

batches[].​clientNamerequiredstringnullable
batches[].​periodEndrequiredstring (date)nullable

example "2026-03-31"

batches[].​userequiredstring (ImportTbUse)nullable

One of: this_year, comparatives

batches[].​totalRowsrequiredinteger
batches[].​skippedRowsrequiredinteger

Blank, total and heading rows left out when reading.

batches[].​doneRowsrequiredinteger
batches[].​countsrequiredobject (ImportCounts)
batches[].​counts.​readyrequiredinteger
batches[].​counts.​warningrequiredinteger
batches[].​counts.​errorrequiredinteger
batches[].​counts.​duplicaterequiredinteger
batches[].​counts.​toImportrequiredinteger

Rows a person has chosen to bring in.

batches[].​counts.​createdrequiredinteger
batches[].​counts.​updatedrequiredinteger
batches[].​counts.​appliedrequiredinteger
batches[].​counts.​skippedrequiredinteger
batches[].​counts.​failedrequiredinteger
batches[].​counts.​undonerequiredinteger
batches[].​counts.​keptrequiredinteger

Left in place by undo, with the reason on the row.

batches[].​createdByNamerequiredstringnullable
batches[].​createdAtrequiredstring (date-time)
batches[].​confirmedAtrequiredstring (date-time)nullable
batches[].​completedAtrequiredstring (date-time)nullable
batches[].​undoneAtrequiredstring (date-time)nullable

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

Start an import

POST/api/v1/imports

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

Records the file and returns where to PUT it. A signed-in manager, partner or firm admin, never an API credential or assistant: a person always confirms what comes in.

Needs the Manager role or above. Part of the hub product: the firm must have it and you must have access to it.

Request body

Required. application/json: object (CreateImportRequest).

Request body for POST /api/v1/imports
FieldTypeDescription
kindrequiredstring (ImportKind)

One of: clients, trial_balance, ct_opening, sa_prior_year

fileNamerequiredstring
contentTypestring
sizeBytesrequiredinteger
clientIdstring (uuid)

Trial balance: whose.

periodEndstring (date)

Trial balance: the period of the accounts it goes in.

example "2026-03-31"

periodStartstring (date)

Left out: twelve months.

example "2026-03-31"

usestring (ImportTbUse)

comparatives: the file’s balances become last year’s column.

One of: this_year, comparatives

Responses

201 Created, application/json

Body: object (ImportCreated).

201 Created response for POST /api/v1/imports
FieldTypeDescription
batchrequiredobject (ImportBatch)

One uploaded file on its way into Tolvi.

batch.​idrequiredstring (uuid)
batch.​kindrequiredstring (ImportKind)

One of: clients, trial_balance, ct_opening, sa_prior_year

batch.​statusrequiredstring (ImportStatus)

One of: pending_upload, pending_scan, reading, needs_mapping, checking, ready, importing, completed, undoing, undone, failed, rejected

batch.​fileNamerequiredstring
batch.​sizeBytesrequiredinteger
batch.​problemrequiredstringnullable

Why it stopped, in plain words.

batch.​noticesrequiredarray of string

About the file as a whole, such as columns left out.

batch.​sheetsrequiredarray of string
batch.​sheetrequiredstringnullable
batch.​headerLinerequiredintegernullable

The line or row the headings were found on.

batch.​columnsrequiredarray of ImportColumn
batch.​columns[].​columnrequiredinteger
batch.​columns[].​headerrequiredstring
batch.​columns[].​fieldrequiredstringnullable

The field it goes to, or null to ignore it.

batch.​columns[].​confidencerequiredstring (ImportColumnConfidence)

One of: exact, close, none

batch.​columns[].​refusedstring

Set when Tolvi won’t keep this column, with what it holds.

batch.​columns[].​samplesrequiredarray of string

The first few values.

batch.​clientIdrequiredstring (uuid)nullable

Trial balance: whose.

batch.​clientNamerequiredstringnullable
batch.​periodEndrequiredstring (date)nullable

example "2026-03-31"

batch.​userequiredstring (ImportTbUse)nullable

One of: this_year, comparatives

batch.​totalRowsrequiredinteger
batch.​skippedRowsrequiredinteger

Blank, total and heading rows left out when reading.

batch.​doneRowsrequiredinteger
batch.​countsrequiredobject (ImportCounts)
batch.​counts.​readyrequiredinteger
batch.​counts.​warningrequiredinteger
batch.​counts.​errorrequiredinteger
batch.​counts.​duplicaterequiredinteger
batch.​counts.​toImportrequiredinteger

Rows a person has chosen to bring in.

batch.​counts.​createdrequiredinteger
batch.​counts.​updatedrequiredinteger
batch.​counts.​appliedrequiredinteger
batch.​counts.​skippedrequiredinteger
batch.​counts.​failedrequiredinteger
batch.​counts.​undonerequiredinteger
batch.​counts.​keptrequiredinteger

Left in place by undo, with the reason on the row.

batch.​createdByNamerequiredstringnullable
batch.​createdAtrequiredstring (date-time)
batch.​confirmedAtrequiredstring (date-time)nullable
batch.​completedAtrequiredstring (date-time)nullable
batch.​undoneAtrequiredstring (date-time)nullable
uploadrequiredobject (ImportUpload)

PUT the file here, then POST …/uploaded.

upload.​urlrequiredstring
upload.​methodrequiredstring
upload.​headersrequiredobject

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

List what can be imported

GET/api/v1/imports/kinds

Scopes
clients:read

Each kind of import, its fields, the file types and limits, and whether you can use it. Part of the hub product: the firm must have it and you must have access to it.

Responses

200 OK, application/json

Body: object (ImportKindList).

200 OK response for GET /api/v1/imports/kinds
FieldTypeDescription
kindsrequiredarray of ImportKindInfo
kinds[].​kindrequiredstring (ImportKind)

One of: clients, trial_balance, ct_opening, sa_prior_year

kinds[].​labelrequiredstring
kinds[].​descriptionrequiredstring
kinds[].​availablerequiredboolean

False when this firm or person can’t use the product it goes into.

kinds[].​unavailableReasonrequiredstringnullable
kinds[].​fieldsrequiredarray of ImportField
kinds[].​fields[].​keyrequiredstring

example "companyNumber"

kinds[].​fields[].​labelrequiredstring

example "Company number"

kinds[].​fields[].​requiredrequiredboolean
kinds[].​fields[].​multiplerequiredboolean

Several columns may feed it.

extensionsrequiredarray of string

Extensions accepted.

maxBytesrequiredinteger
maxRowsrequiredinteger

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

Download a template

GET/api/v1/imports/templates/{kind}

Scopes
clients:read

A spreadsheet with the headings Tolvi reads first and worked examples to overwrite. Part of the hub product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/imports/templates/{kind}
NameInTypeDescription
kindrequiredpathstring

One of: clients, trial_balance, ct_opening, sa_prior_year

formatquerystring

One of: xlsx, csv

Responses

200 OK

A spreadsheet.

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

Get an import

GET/api/v1/imports/{id}

Scopes
clients:read

Status, the columns found with what Tolvi suggests for each, and counts. Poll this while it reads, checks or imports. Part of the hub product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/imports/{id}
NameInTypeDescription
idrequiredpathstring (uuid)

Responses

200 OK, application/json

Body: object (ImportBatch).

One uploaded file on its way into Tolvi.

200 OK response for GET /api/v1/imports/{id}
FieldTypeDescription
idrequiredstring (uuid)
kindrequiredstring (ImportKind)

One of: clients, trial_balance, ct_opening, sa_prior_year

statusrequiredstring (ImportStatus)

One of: pending_upload, pending_scan, reading, needs_mapping, checking, ready, importing, completed, undoing, undone, failed, rejected

fileNamerequiredstring
sizeBytesrequiredinteger
problemrequiredstringnullable

Why it stopped, in plain words.

noticesrequiredarray of string

About the file as a whole, such as columns left out.

sheetsrequiredarray of string
sheetrequiredstringnullable
headerLinerequiredintegernullable

The line or row the headings were found on.

columnsrequiredarray of ImportColumn
columns[].​columnrequiredinteger
columns[].​headerrequiredstring
columns[].​fieldrequiredstringnullable

The field it goes to, or null to ignore it.

columns[].​confidencerequiredstring (ImportColumnConfidence)

One of: exact, close, none

columns[].​refusedstring

Set when Tolvi won’t keep this column, with what it holds.

columns[].​samplesrequiredarray of string

The first few values.

clientIdrequiredstring (uuid)nullable

Trial balance: whose.

clientNamerequiredstringnullable
periodEndrequiredstring (date)nullable

example "2026-03-31"

userequiredstring (ImportTbUse)nullable

One of: this_year, comparatives

totalRowsrequiredinteger
skippedRowsrequiredinteger

Blank, total and heading rows left out when reading.

doneRowsrequiredinteger
countsrequiredobject (ImportCounts)
counts.​readyrequiredinteger
counts.​warningrequiredinteger
counts.​errorrequiredinteger
counts.​duplicaterequiredinteger
counts.​toImportrequiredinteger

Rows a person has chosen to bring in.

counts.​createdrequiredinteger
counts.​updatedrequiredinteger
counts.​appliedrequiredinteger
counts.​skippedrequiredinteger
counts.​failedrequiredinteger
counts.​undonerequiredinteger
counts.​keptrequiredinteger

Left in place by undo, with the reason on the row.

createdByNamerequiredstringnullable
createdAtrequiredstring (date-time)
confirmedAtrequiredstring (date-time)nullable
completedAtrequiredstring (date-time)nullable
undoneAtrequiredstring (date-time)nullable

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

Discard an import

DELETE/api/v1/imports/{id}

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

Removes the file and what was read, before anything has come in. A signed-in manager, partner or firm admin, never an API credential or assistant: a person always confirms what comes in.

Needs the Manager role or above. Part of the hub product: the firm must have it and you must have access to it.

Parameters

Parameters for DELETE /api/v1/imports/{id}
NameInTypeDescription
idrequiredpathstring (uuid)

Responses

204 No content

Gone.

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

Say the file has uploaded

POST/api/v1/imports/{id}/uploaded

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

Checks what storage holds, hands it to the malware scan and, once clean, reads it. A signed-in manager, partner or firm admin, never an API credential or assistant: a person always confirms what comes in.

Needs the Manager role or above. Part of the hub product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/imports/{id}/uploaded
NameInTypeDescription
idrequiredpathstring (uuid)

Responses

200 OK, application/json

Body: object (ImportBatch).

One uploaded file on its way into Tolvi.

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

Choose the sheet or heading row

PUT/api/v1/imports/{id}/layout

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

Reads the file again from another sheet or heading row. A signed-in manager, partner or firm admin, never an API credential or assistant: a person always confirms what comes in.

Needs the Manager role or above. Part of the hub product: the firm must have it and you must have access to it.

Parameters

Parameters for PUT /api/v1/imports/{id}/layout
NameInTypeDescription
idrequiredpathstring (uuid)

Request body

Required. application/json: object (ImportLayoutRequest).

Request body for PUT /api/v1/imports/{id}/layout
FieldTypeDescription
sheetstring
headerLineinteger

The line or row the headings are on.

Responses

200 OK, application/json

Body: object (ImportBatch).

One uploaded file on its way into Tolvi.

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

Confirm the columns

PUT/api/v1/imports/{id}/mapping

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

Says which column is which field, then checks every row in the background. Nothing comes in yet. A signed-in manager, partner or firm admin, never an API credential or assistant: a person always confirms what comes in.

Needs the Manager role or above. Part of the hub product: the firm must have it and you must have access to it.

Parameters

Parameters for PUT /api/v1/imports/{id}/mapping
NameInTypeDescription
idrequiredpathstring (uuid)

Request body

Required. application/json: object (ImportMappingRequest).

Request body for PUT /api/v1/imports/{id}/mapping
FieldTypeDescription
columnsrequiredarray of ColumnChoice
columns[].​columnrequiredinteger
columns[].​fieldrequiredstringnullable

Responses

200 OK, application/json

Body: object (ImportBatch).

One uploaded file on its way into Tolvi.

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 an import’s rows

GET/api/v1/imports/{id}/rows

Scopes
clients:read

What each row said, what’s wrong with it in plain words, any client it matches, and what happened to it. Part of the hub product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/imports/{id}/rows
NameInTypeDescription
idrequiredpathstring (uuid)
limitqueryinteger
afterqueryinteger
outcomequerystring
statusquerystring

Responses

200 OK, application/json

Body: object (ImportRowPage).

200 OK response for GET /api/v1/imports/{id}/rows
FieldTypeDescription
rowsrequiredarray of ImportRow
rows[].​linerequiredinteger
rows[].​labelrequiredstring
rows[].​statusrequiredstring (ImportRowStatus)

One of: unchecked, ready, warning, error, duplicate

rows[].​decisionrequiredstring (ImportRowDecision)

One of: create, fill_blanks, apply, skip

rows[].​outcomerequiredstring (ImportRowOutcome)

One of: pending, created, updated, applied, skipped, failed, undone, kept

rows[].​outcomeNoterequiredstringnullable
rows[].​errorsrequiredarray of string
rows[].​warningsrequiredarray of string
rows[].​valuesrequiredobjectnullable

What was read. Money is integer pence.

rows[].​matchClientIdrequiredstring (uuid)nullable
rows[].​matchClientNamerequiredstringnullable
rows[].​matchHowrequiredstring (ImportMatchHow)nullable

One of: utr, company_number, name

nextAfterrequiredintegernullable

Pass as after for the next page.

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

Decide one row

PATCH/api/v1/imports/{id}/rows/{line}

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

Bring it in, fill the blanks on the matching client, or skip it; or give the client type or statement line it lacks. A signed-in manager, partner or firm admin, never an API credential or assistant: a person always confirms what comes in.

Needs the Manager role or above. Part of the hub product: the firm must have it and you must have access to it.

Parameters

Parameters for PATCH /api/v1/imports/{id}/rows/{line}
NameInTypeDescription
idrequiredpathstring (uuid)
linerequiredpathinteger

Request body

Required. application/json: object (ImportRowPatchRequest).

Request body for PATCH /api/v1/imports/{id}/rows/{line}
FieldTypeDescription
decisionstring (ImportRowDecision)

One of: create, fill_blanks, apply, skip

entityTypestring

The client type, when the file didn’t give one Tolvi knows.

statementLinestring

Trial balance: the statement line for this account.

Responses

200 OK, application/json

Body: object (ImportRow).

One row of the file.

200 OK response for PATCH /api/v1/imports/{id}/rows/{line}
FieldTypeDescription
linerequiredinteger
labelrequiredstring
statusrequiredstring (ImportRowStatus)

One of: unchecked, ready, warning, error, duplicate

decisionrequiredstring (ImportRowDecision)

One of: create, fill_blanks, apply, skip

outcomerequiredstring (ImportRowOutcome)

One of: pending, created, updated, applied, skipped, failed, undone, kept

outcomeNoterequiredstringnullable
errorsrequiredarray of string
warningsrequiredarray of string
valuesrequiredobjectnullable

What was read. Money is integer pence.

matchClientIdrequiredstring (uuid)nullable
matchClientNamerequiredstringnullable
matchHowrequiredstring (ImportMatchHow)nullable

One of: utr, company_number, name

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

Decide every row of a status

POST/api/v1/imports/{id}/rows/decide

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

For instance, fill the blanks on every duplicate. A signed-in manager, partner or firm admin, never an API credential or assistant: a person always confirms what comes in.

Needs the Manager role or above. Part of the hub product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/imports/{id}/rows/decide
NameInTypeDescription
idrequiredpathstring (uuid)

Request body

Required. application/json: object (ImportBulkDecisionRequest).

Request body for POST /api/v1/imports/{id}/rows/decide
FieldTypeDescription
statusrequiredstring (ImportRowStatus)

One of: unchecked, ready, warning, error, duplicate

decisionrequiredstring (ImportRowDecision)

One of: create, fill_blanks, apply, skip

Responses

200 OK, application/json

Body: object (ImportBatch).

One uploaded file on its way into Tolvi.

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

Confirm and import

POST/api/v1/imports/{id}/confirm

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

Brings in the rows chosen, in the background. Safe to retry. A signed-in manager, partner or firm admin, never an API credential or assistant: a person always confirms what comes in.

Needs the Manager role or above. Part of the hub product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/imports/{id}/confirm
NameInTypeDescription
idrequiredpathstring (uuid)

Request body

Required. application/json: object (ImportConfirmRequest).

A person confirming what they have seen.

Request body for POST /api/v1/imports/{id}/confirm
FieldTypeDescription
expectedRowsrequiredinteger

How many rows the person saw would come in. Refused if that has changed.

Responses

200 OK, application/json

Body: object (ImportBatch).

One uploaded file on its way into Tolvi.

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

Carry on after a stop

POST/api/v1/imports/{id}/retry

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

Rows already done are left alone. A signed-in manager, partner or firm admin, never an API credential or assistant: a person always confirms what comes in.

Needs the Manager role or above. Part of the hub product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/imports/{id}/retry
NameInTypeDescription
idrequiredpathstring (uuid)

Responses

200 OK, application/json

Body: object (ImportBatch).

One uploaded file on its way into Tolvi.

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

Undo an import

POST/api/v1/imports/{id}/undo

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

Takes out what the whole file brought in. A client with work on it, or anything changed since, is kept, and the report says why. A signed-in manager, partner or firm admin, never an API credential or assistant: a person always confirms what comes in.

Needs the Manager role or above. Part of the hub product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/imports/{id}/undo
NameInTypeDescription
idrequiredpathstring (uuid)

Responses

200 OK, application/json

Body: object (ImportBatch).

One uploaded file on its way into Tolvi.

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

Download the results report

GET/api/v1/imports/{id}/report

Scopes
clients:read

What happened to every row, as CSV. Values that a spreadsheet would run as a formula are neutralised. Part of the hub product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/imports/{id}/report
NameInTypeDescription
idrequiredpathstring (uuid)

Responses

200 OK

A CSV file.

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