Domain model

This page is the map. It says what exists and how it connects; the pages it links to explain each part properly.

Two facts shape everything else, and each has its own page:

• Every response is scoped to your own agency, enforced below the API — Multi-tenancy and data isolation.
• The whole system is week-driven, against a week the agency defines — The recruitment week.

The chain that runs through the product is:

Bookings → worker assignment → weekly plans → timesheets → payroll and invoices.

The tenancy chain

Entity	Belongs to	Explained in
Agency	—	Agencies
Branch	One agency	Branches
Client	One branch	Clients
Site	One client	Sites
Worker	One branch	Workers

The ids these entities refer to each other by come from three tiers of configuration data — Reference data and agency lookups — and the rules for reading an id or a timestamp out of a response are in Identifiers, audit and timestamps.

The financial core

None of the entities in this section are published by the API yet. They are described because the rest of the model does not make sense without them, and because the vocabulary appears throughout the product.

Availability records when a worker can work. It is used to match workers to bookings, and is overridden by bookings already made and by booked holiday.

A booking assigns a worker to a client site for a given date and time. Bookings carry their own pay and charge rates, have a status, and can recur.

A plan groups a worker’s bookings at a site within one week — the unit the financial side of the product acts on. Plans carry hours worked, a status such as completed, adjustments like bonuses and deductions, and holiday taken. They are the input to both timesheets and invoices.

Plans data is intentionally asymmetric

A weekly rate lives on the reference plan only; daily rates are per day. Plans are deliberately sparse. Completing a plan snapshots the agreed hours and rates and produces legally authoritative payroll and invoice values, so do not normalise, flatten or redistribute plan data in your own system, and never recalculate historical rates.

Invoices are generated from completed plans. One invoice belongs to one client and can cover several plans within a week. Credit notes adjust an invoice — for over-billing, cancellations and similar — and belong to one invoice. Both can be linked to external accounting systems.

A subcontractor is a third-party company supplying workers to the agency. Subcontractors belong to a branch, can have several workers associated with them, carry their own documents such as contracts and insurance, and are invoiced separately.

What is published today

Agencies, branches, clients, sites, workers and the agency lookup and settings data are on the published surface. Bookings, plans, timesheets, payroll and invoicing are not.

The endpoints will appear in the reference when those modules ship. Nothing is being withheld — they do not exist in the API yet, and pre-documenting them would be worse than an honest gap.

Next

Agencies — the tenant your token is bound to, and the configuration everything else inherits.