Conventions
The rules every operation follows: formats, errors, paging, retries, versions and limits.
Requests and responses
- JSON in UTF-8, with
snake_casekeys. - Times in ISO 8601 with an offset (
2026-10-24T09:30:00Z); dates alone as2026-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.