Skip to main content
BETA
MenuClose

Client list

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

List the fields of the client list

GET/api/v1/client-list/fields

Scopes
clients:read

One group per module, with each field’s type and what it can be filtered by. Only modules for products you can use, and your credential has a scope for. Part of the hub product: the firm must have it and you must have access to it.

Responses

200 OK, application/json

Body: object (ClientFieldCatalogue).

200 OK response for GET /api/v1/client-list/fields
FieldTypeDescription
modulesrequiredarray of ClientFieldModuleEntry
modules[].​keyrequiredstring
modules[].​labelrequiredstring
defaultColumnsrequiredarray of string
fieldsrequiredarray of ClientField
fields[].​idrequiredstring

The id to use in columns, filter and sort.

example "ct.due"

fields[].​modulerequiredstring

example "corporation_tax"

fields[].​labelrequiredstring
fields[].​typerequiredstring (ClientFieldType)

One of: text, enum, person, date, money, number

fields[].​filterablerequiredboolean
fields[].​sortablerequiredboolean
fields[].​operatorsrequiredarray of string

The operators a condition on this field can use.

fields[].​optionsarray of ClientFieldOption
fields[].​options[].​valuerequiredstring
fields[].​options[].​labelrequiredstring
fields[].​descriptionstring

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

List clients with chosen columns and filters

GET/api/v1/client-list

Scopes
clients:read

Filtered, sorted and paged on the server, with data from every product you can use. Only fields in the catalogue can be named. Part of the hub product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/client-list
NameInTypeDescription
limitqueryinteger

1 to 200; default 50

pagequeryinteger

at least 1; default 1

qquerystring

Part of the client name or company number.

up to 100 characters

sortquerystring

A field id, with a leading - for descending. Blanks come last. Name, then id, break ties.

up to 61 characters

columnsquerystring

Field ids, comma separated. Left out: the default columns.

filterquerystring

JSON: { "match": "all", "conditions": [{ "field": "ct.due", "operator": "next_days", "value": 30 }] }. Groups nest. Conditions on a product you can’t use aren’t applied, and are named in hiddenFields.

up to 8000 characters

Responses

200 OK, application/json

Body: object (ClientListPage).

200 OK response for GET /api/v1/client-list
FieldTypeDescription
rowsrequiredarray of ClientListRow
rows[].​idrequiredstring (uuid)
rows[].​valuesrequiredobject

By field id. Money is integer pence; dates are ISO; a person is their name.

columnsrequiredarray of string

The columns returned, in order.

pagerequiredinteger
pageSizerequiredinteger
totalrequiredinteger
hiddenFieldsrequiredarray of ClientListHiddenField

Fields asked for from products you can’t use: left out of the columns, and conditions on them not applied.

hiddenFields[].​idrequiredstring
hiddenFields[].​labelrequiredstring
hiddenFields[].​modulerequiredstring
hiddenFields[].​moduleLabelrequiredstring

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

Export the client list as CSV

GET/api/v1/client-list/export

Scopes
clients:read

The same filter, sort and columns as the list, every matching row, up to 10,000. Money is in pounds, with credits in brackets. Refused when it’s more than that, or SA tax due is a column and more than 500 clients match. Part of the hub product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/client-list/export
NameInTypeDescription
qquerystring

Part of the client name or company number.

up to 100 characters

sortquerystring

A field id, with a leading - for descending. Blanks come last. Name, then id, break ties.

up to 61 characters

columnsquerystring

Field ids, comma separated. Left out: the default columns.

filterquerystring

JSON: { "match": "all", "conditions": [{ "field": "ct.due", "operator": "next_days", "value": 30 }] }. Groups nest. Conditions on a product you can’t use aren’t applied, and are named in hiddenFields.

up to 8000 characters

Responses

200 OK, text/csv

The CSV.

Body: string.

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

List saved views

GET/api/v1/client-list/views

Scopes
clients:read

Those shared with the practice, and your own private ones. Part of the hub product: the firm must have it and you must have access to it.

Responses

200 OK, application/json

Body: object (ClientListViews).

200 OK response for GET /api/v1/client-list/views
FieldTypeDescription
viewsrequiredarray of ClientListView
views[].​idrequiredstring (uuid)
views[].​namerequiredstring
views[].​visibilityrequiredstring (ClientViewVisibility)

One of: private, firm

views[].​columnsrequiredarray of string
views[].​filterrequiredobject

{ match: "all" | "any", conditions: [{ field, operator, value } | group] }, nesting three groups deep and 40 conditions at most.

views[].​sortrequiredobject (ClientListSort)nullable
views[].​sort.​fieldrequiredstring
views[].​sort.​dirrequiredstring (ClientListSortDirection)

One of: asc, desc

views[].​createdByrequiredstring (uuid)nullable
views[].​createdByNamerequiredstringnullable
views[].​isDefaultrequiredboolean

The view you open the client list on.

views[].​canEditrequiredboolean

Whether you can change or delete it.

views[].​hiddenFieldsrequiredarray of ClientListHiddenField

What this view uses from products you can’t use.

views[].​hiddenFields[].​idrequiredstring
views[].​hiddenFields[].​labelrequiredstring
views[].​hiddenFields[].​modulerequiredstring
views[].​hiddenFields[].​moduleLabelrequiredstring
views[].​updatedAtrequiredstring (date-time)
defaultViewIdrequiredstring (uuid)nullable

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

Save a view

POST/api/v1/client-list/views

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

Anyone signed in can save one, private or shared with the practice. An API credential also needs clients:write. Part of the hub product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/client-list/views
NameInTypeDescription
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 (CreateClientListViewRequest).

Request body for POST /api/v1/client-list/views
FieldTypeDescription
namerequiredstring

up to 80 characters

visibilitystring (ClientViewVisibility)

private (the default) or firm: everyone in the practice.

One of: private, firm

columnsrequiredarray of string
filterobject

{ match: "all" | "any", conditions: [{ field, operator, value } | group] }, nesting three groups deep and 40 conditions at most.

sortobject (ClientListSort)nullable
sort.​fieldrequiredstring
sort.​dirrequiredstring (ClientListSortDirection)

One of: asc, desc

Responses

201 Created, application/json

Body: object (ClientListView).

201 Created response for POST /api/v1/client-list/views
FieldTypeDescription
idrequiredstring (uuid)
namerequiredstring
visibilityrequiredstring (ClientViewVisibility)

One of: private, firm

columnsrequiredarray of string
filterrequiredobject

{ match: "all" | "any", conditions: [{ field, operator, value } | group] }, nesting three groups deep and 40 conditions at most.

sortrequiredobject (ClientListSort)nullable
sort.​fieldrequiredstring
sort.​dirrequiredstring (ClientListSortDirection)

One of: asc, desc

createdByrequiredstring (uuid)nullable
createdByNamerequiredstringnullable
isDefaultrequiredboolean

The view you open the client list on.

canEditrequiredboolean

Whether you can change or delete it.

hiddenFieldsrequiredarray of ClientListHiddenField

What this view uses from products you can’t use.

hiddenFields[].​idrequiredstring
hiddenFields[].​labelrequiredstring
hiddenFields[].​modulerequiredstring
hiddenFields[].​moduleLabelrequiredstring
updatedAtrequiredstring (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).

Change a saved view

PATCH/api/v1/client-list/views/{viewId}

Scopes
clients:read

Its creator, or for a shared view a manager or above. Only its creator can change who sees it. Someone else’s private view is 404. Part of the hub product: the firm must have it and you must have access to it.

Parameters

Parameters for PATCH /api/v1/client-list/views/{viewId}
NameInTypeDescription
viewIdrequiredpathstring (uuid)

Request body

Required. application/json: object (UpdateClientListViewRequest).

Request body for PATCH /api/v1/client-list/views/{viewId}
FieldTypeDescription
namestring

up to 80 characters

visibilitystring (ClientViewVisibility)

Only whoever made the view can change this.

One of: private, firm

columnsarray of string
filterobject

{ match: "all" | "any", conditions: [{ field, operator, value } | group] }, nesting three groups deep and 40 conditions at most.

sortobject (ClientListSort)nullable
sort.​fieldrequiredstring
sort.​dirrequiredstring (ClientListSortDirection)

One of: asc, desc

Responses

200 OK, application/json

Body: object (ClientListView).

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 a saved view

DELETE/api/v1/client-list/views/{viewId}

Scopes
clients:read

Its creator, or for a shared view a manager 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/client-list/views/{viewId}
NameInTypeDescription
viewIdrequiredpathstring (uuid)

Responses

204 No content

Deleted.

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

Duplicate a saved view

POST/api/v1/client-list/views/{viewId}/duplicate

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

The copy is yours, and private. Part of the hub product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/client-list/views/{viewId}/duplicate
NameInTypeDescription
viewIdrequiredpathstring (uuid)
Idempotency-Keyheaderstring

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

Request body for POST /api/v1/client-list/views/{viewId}/duplicate
FieldTypeDescription
namestring

up to 80 characters

Responses

201 Created, application/json

Body: object (ClientListView).

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

Open the client list on this view

PUT/api/v1/client-list/views/{viewId}/default

Scopes
clients:read

For you alone. Part of the hub product: the firm must have it and you must have access to it.

Parameters

Parameters for PUT /api/v1/client-list/views/{viewId}/default
NameInTypeDescription
viewIdrequiredpathstring (uuid)

Responses

200 OK, application/json

Body: object (ClientListView).

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

Stop opening the client list on a saved view

DELETE/api/v1/client-list/default-view

Scopes
clients:read

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

Responses

204 No content

Cleared.

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