Tolvi API reference

The Tolvi API has 606 operations in 41 areas. This reference is built from the OpenAPI 3.1 specification that the API generates from its own code (API version 1.0.0), so it matches what the API does.

Conventions

Base URL: Paths in this reference start /api/v1 and are relative to https://api.tolvi.co.uk.
Authentication: Authorization: Bearer <token> with a personal access token, a client-credentials token or an OAuth access token. Each operation lists the scopes it needs, and the caller's role also applies. Tokens, scopes and roles.
Firm: If you belong to several firms, send x-firm-id with the firm's id. It must be one of your own firms. It isn't repeated in each operation below.
Money: Every amount is an integer number of pence, in fields ending Pence: 123456 is 1,234.56 pounds. There are no decimal amounts anywhere. Trial balance amounts are debit positive, so credits are negative.
Dates and times: Dates are YYYY-MM-DD (format date). Times are ISO 8601 in UTC (format date-time).
Pagination: Lists are cursor-based. Pass limit (1 to 100) and the previous page's nextCursor as cursor. Lists return rows, nextCursor and pageSize; a null cursor means the last page.
GET /api/v1/clients?limit=50 → { "rows": [ … ], "nextCursor": "eyJ…", "pageSize": 50 } GET /api/v1/clients?limit=50&cursor=eyJ… → { "rows": [ … ], "nextCursor": null, "pageSize": 50 }
Idempotency: Operations that accept an Idempotency-Key header can be retried safely. The first successful response is replayed for 24 hours with Idempotent-Replayed: true. Reusing a key for a different request is a 422.
Rate limits: Every response carries RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and RateLimit-Policy. Limits by plan, person and firm.
Fields: "Required" fields are always present in a response and must be sent in a request. "Nullable" fields can be null. New optional fields may appear within version 1, so ignore any you don't know.

Errors

Errors are RFC 9457 problem details, with Content-Type: application/problem+json. The status code says what kind of error it is, and detail says what to fix. The OAuth token endpoint is the one exception: it answers with the OAuth error shape that OAuth clients expect.

The problem details object
Field	Type	Description
`type`required	`string`	A URI for the problem type; about:blank means "see the status". example "about:blank"
`title`required	`string`	The HTTP status phrase. example "Forbidden"
`status`required	`integer`	example 403
`detail`	`string`	example "This needs the Manager role or above"
`instance`	`string`	The request path. example "/api/v1/work/assign"
`errors`	`array of string`	Every validation message, when there was more than one.
`rateLimitScope`	`string (RateLimitScope)`	On a 429, which limit was hit: `person` (one person's web sessions), `firm` (everyone in the firm signed in to the web app), `client` (this API credential or connected app) or `ip` (this address, before sign-in or on a sign-in endpoint). One of: `person`, `firm`, `client`, `ip` example "person"

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json

{
  "type": "about:blank",
  "title": "Forbidden",
  "status": 403,
  "detail": "This needs the Manager role or above",
  "instance": "/api/v1/work/assign"
}

400 the request isn't valid. errors lists every message when there's more than one.
401 no token, or the token isn't valid or has expired.
403 the role or the token's scopes don't allow it, or a workflow rule blocks it.
404 not found in your firm. Another firm's records are never visible, so they're a 404 too.
409 and 422 the change conflicts with the current state, or an idempotency key was reused.
429 over a rate limit. Wait for Retry-After seconds; rateLimitScope says whose limit it was (client, person, firm or ip).