How to read the reference

The reference is generated from /openapi/v1.json. Nothing in it is written by hand, which is the point: every summary, parameter, schema and status code you read there is the same metadata the running API publishes, so it cannot describe an endpoint that no longer behaves that way.

The consequence is worth knowing before you rely on it. The reference states facts and never teaches. If an operation page tells you what a field is but not why you would set it, the explanation is on a concept page, linked from the operation.

How it is grouped

Published operations carry OpenAPI tags — one per capability. An alphabetical list of tags is not navigation, so they are collected into reader-facing groups instead:

Group	What is in it	Operations	In the reference
Agency setup	The agency itself and the structures underneath it: branches, and the cost centres each branch books work against.	13	All of them
Clients & sites	Clients, the sites they operate, and everything hanging off a site — contact persons, rate contracts, activities and cost-centre links. Leads are prospective clients.	41	All of them
Workers	Workers and their onboarding: the worker record itself, and the compliance documents, driving licences, Driver CPC records, employment history and files that hang off it. One tag per sub-resource, so each reads as its own small CRUD surface.	57	All of them
Lookups	The agency-configurable reference data every other call refers to by id. Each tag is a small CRUD surface your agency owns; read the Reference data & agency lookups concept page once and most of the family follows. Read each operation's own page for the parts that differ — three of these delete by flagging the record, the rest remove it outright, and not every one checks a name for duplicates.	82	All of them
Reference data	Platform-wide read-only vocabularies — titles, genders, nationalities, worker types and the rest — identical for every agency. A worker or client record refers to these by id, so they are the values you need before you can create one. Distinct from Lookups, which your agency owns and configures.	50	42 of 50
Access	Obtaining and using credentials.	1	All of them
Published integrator surface		244	236 rendered

Inside a group the tags are alphabetical, except that a resource living under another one follows its parent rather than sorting away from it. Clients & sites therefore reads Clients, Sites, then the six resources that hang off a site, then Leads — the hierarchy is shown by position rather than by indentation, so every operation sits at the same depth in the sidebar however deep its path runs.

How operations are ordered

Within a tag, operations are listed in the order you work down the resource rather than alphabetically:

1. List the collection, then create in it.
2. Get one item, then update it, then delete it.
3. Anything else acting on that item — restoring it, or replacing a single field.
4. Each sub-resource in turn, in the same shape.

So a resource always opens with its own five operations and a sub-resource’s operations always sit together. Workers, which carries fifty-one operations across eleven sub-resources, reads as eleven blocks of that shape rather than one list sorted by first letter.

The two key information document lookups are the exception, and unavoidably so: they are singletons whose four operations all sit on one path with no {id}, so there is no collection to list first and they read Get, Update, Create, Delete.

The consequence to know: the wording of a summary does not affect where it appears. “Archive a site” is the delete on /clients/{clientId}/sites/{id}, so it sits fifth in Sites where a delete belongs, not first where the alphabet would put it. Verbs follow the domain — you will see Link, Log, Record, Archive and Restore — but each still occupies the position its method earns.

Why some operations are not here

A group showing “None yet” is not a gap in the API. Those operations exist, are supported, and are part of the published contract — what they lack is authored prose.

Generating a page for an operation whose only description is “Access.” would produce something that shows a method, a path and a schema while teaching nothing, and looks finished enough that nobody goes back to write it. Rather than ship that, those operations are reached through the playground, which is honest about being a raw contract explorer. They move into the reference as they are documented.

Whatever their state, all of them are in the published document and in the Postman collection, so nothing is hidden from you — only unexplained.

What every operation assumes

These hold across the whole surface and are not repeated on each page.

• Every operation needs a bearer token obtained through the two-call flow in Authentication. An operation page’s Access paragraph says which policy it requires.
• No operation takes an agency identifier. Scope comes from your credentials. See Multi-tenancy and data isolation.
• Paths are relative to the base URL in Environments.
• DateTime values are UK local time, not UTC — see Responses and pagination.
• 401, 403, 404 and 500 mean the same thing everywhere. The per-operation status lists say which a given endpoint can return; Errors says what each one means and what to do about it.

Reading one operation page

Each page carries the operation’s summary and description, its Access policy, its path and query parameters, the request body schema where there is one, and a response schema per status code it can return. Field descriptions and examples come from the API’s own source, so an example value is a realistic one rather than a placeholder.

What no operation page carries is prose about when to call it, or in what order. Sequencing lives in the concept pages, and each operation page links back to the ones that name it.

The other two surfaces

• The playground executes calls against your own credentials. Use it to confirm a response shape before writing a client. It opens the integrator document; the bare /scalar entry point also lists an unpruned document that includes endpoints outside this contract.
• The OpenAPI document is the machine-readable contract. Generate a client from it rather than hand-writing models.

Next

Domain model — what the operations in these groups act on.