Conventions

The rules every operation follows: formats, errors, paging, retries, versions and limits.

Requests and responses

  • JSON in UTF-8, with snake_case keys.
  • Times in ISO 8601 with an offset (2026-10-24T09:30:00Z); dates alone as 2026-10-24.
  • Money as an object with the amount as a string, never a number: { "amount": "14500.00", "currency": "GBP" }.
  • IDs are opaque strings with a prefix that says what they are: env_… for an envelope, req_… for a time off request.
  • Anything inside a company is under /v1/workspaces/{workspace_id}/…; things about you are under /v1/me/….
  • Nothing personal ever goes in a URL or a query string.

Errors

Errors are application/problem+json (RFC 9457): a type URL that names the kind of error and never changes, a title written for people in the language you ask for (Accept-Language), a detail, the status, and errors[] pointing at each field that was wrong. An error never contains personal details or a document's text.

Lists

Lists are paged by cursor: pass limit (50 unless you say, at most 200) and the next_cursor from the last page as cursor. The last page's next_cursor is null.

Retrying safely

Send an Idempotency-Key header (a UUID of your own) with every POST. The same key with the same body returns the same result for 24 hours, so a request retried after a timeout does the thing once. The same key with a different body is refused with 409.

Versions

The major version is in the path. Version 0 may change at any time. From version 1, changes within the version only add things; anything removed is announced 12 months ahead, with a Deprecation header on the way out.

Limits

Each client and each account has a rate limit, shown in the RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers. Over the limit, the answer is 429 with Retry-After.

On this page