Workers
A worker is an individual the agency places into work at a client’s sites. The record holds who they are, how they are paid, what they are qualified and available to do, and the compliance evidence that lets them be placed at all.
A worker belongs to one agency, and to one branch
Section titled “A worker belongs to one agency, and to one branch”A worker is registered against a branch of your agency, and the branch has to be one your credentials can reach — see Multi-tenancy. That holds for the worker’s whole life, not only their registration: a worker under a branch the user behind your API app cannot access is left out of every list, and they and every record they hold return 404.
There is no shared worker identity across the platform. A person who works for two agencies that both use Recruso exists as two entirely separate workers, with different ids, different histories and no link between them. Do not attempt to reconcile them across tenants; from the API’s point of view they are unrelated people.
Two identifiers, and they are not the same
Section titled “Two identifiers, and they are not the same”Every worker carries both:
- A worker id — the surrogate key. This is what every other endpoint takes.
- A worker number — the human-facing reference, allocated from your agency’s own numbering sequence when the worker is created, and the one that appears on paperwork.
Use the id for API calls and the number for anything a person reads. They are not interchangeable and neither is derived from the other.
A GDPR-deleted worker is gone from the API
Section titled “A GDPR-deleted worker is gone from the API”When a worker’s record has been deleted under data-protection law, the API behaves as though they were never there. They are left out of every list and every search, and their id — or the id of anything they held, from a compliance document to an activity — returns 404, exactly as another agency’s worker does. The API withholds them; it never deletes anything itself, and nothing you send can mark a worker deleted or bring one back.
So a worker id you stored can start returning 404 without anything being wrong with your integration. The response does not say whether that is a data-protection deletion, by design — the same 404 covers every record your credentials cannot see. Treat it as gone from your side too.
Engagement type — PAYE, umbrella or subcontractor — changes almost everything
Section titled “Engagement type — PAYE, umbrella or subcontractor — changes almost everything”How a worker is engaged is the single most consequential field on the record. UK temporary recruitment recognises several models, and Recruso treats them differently:
- PAYE — the agency employs and pays the worker directly, operating tax and National Insurance.
- Limited company or umbrella — the worker is paid through an intermediary rather than on the agency’s payroll.
- Supplied through a subcontractor — a third-party supplier provides the worker, and is invoiced separately. A worker engaged this way must name the subcontractor they come through.
The engagement type drives payroll treatment, holiday handling — including whether holiday pay is rolled up into the hourly rate — and which Key Information Document template applies, since PAYE and subcontractor workers are templated separately. It is not a label; it changes the financial behaviour of everything downstream.
Conditionally required, not simply required
Section titled “Conditionally required, not simply required”Creating a worker is not a flat form. Several fields become mandatory only because of what you set elsewhere:
- Bank details are required for every payment method except cheque, and a building society account additionally needs the society name.
- A subcontractor must be named when the engagement type is a subcontractor type.
- Starter-checklist statements are ignored by tax forms that do not use them, and the tax code is overridden entirely for some forms.
Anything you leave unset falls back to your agency’s own defaults — the default tax code, the default worker status. Those defaults live on the agency record, so two agencies sending an identical request can get different workers back. Read the operation description in the reference for the exact rules; they are stated there rather than repeated here.
Availability, compliance and rates
Section titled “Availability, compliance and rates”Three things hang off the worker and govern whether a placement can happen at all:
- Availability records when the worker can work, day by day: each entry is a date with one of your agency’s availability statuses and, optionally, a start and finish time. In Recruso CRM it is used to match workers to bookings. It is published, and follows your agency’s own rules: how many entries a day it allows, how far back and ahead an entry can be recorded or changed, and the statuses that affect a worker’s AWR parity, which stay with Recruso CRM. Bookings are not published, so nothing the API does with availability touches them.
- Compliance is the evidence — right-to-work, qualifications, documents — that a placement depends on. Right-to-work documents, driving licences and their convictions, Driver CPC entitlement and training, uploaded documents and the worker photograph are all published. The worker’s standing at each site is held on the worker record too, as four site lists — suitable, not suitable, assessed and banned — described below.
- Rate floors on the worker, such as the lowest hourly or daily rate they will accept, constrain what they can be booked at. The hourly and daily floors are published as part of the worker’s details.
What the published API does today
Section titled “What the published API does today”The published surface covers the worker’s details — one request, replaced in full — and a set of sub-resources, each with its own operations: compliance documents, driving licences and the convictions against them, previous employments and their references, activities, uploaded documents, the profile image, Driver CPC entitlement and training, and availability. Their status history is readable but not writable. That split is deliberate rather than incidental: it follows the difference between current state and history described below. Workers themselves can be listed, but not deleted.
Listing and finding are one operation. Sent without filters it enumerates your agency’s workers a page at a time; narrowed by name, email address, worker number, branch or current status, it is how you find a particular worker again. Each entry is a summary — who the worker is, how they are engaged and how to reach them, but never their tax, bank or compliance details — so reading the full record is still a call for that one worker. Bookings are not yet published.
Details are replaced in full and held to the same rules as creating a worker — the conditionally required fields above apply identically. What a details update deliberately cannot reach is everything that is not the worker’s current state:
- Fixed at registration. The branch, the worker number and the registration audit. A worker cannot be moved between branches through this API.
- Status, and everything with dates of its own. Compliance documents, licences, previous employments, activities and CPC records are all history rather than current state, and each is written through its own operations. Saving a worker’s details can never change their status, remove a right-to-work record or edit a reference.
- Files. Documents and the profile image are uploaded as
multipart/form-datathrough their own operations, never as part of the details request. A document cannot be corrected once uploaded — the record has no modified-by audit to record a correction with — so replacing one is upload then remove. Removing a document or the image deletes the stored file with it, permanently. Both are read back through the API as well, always as a download and never as a link: where a file is stored is not something the API discloses.
What the details request does carry, beyond the worker’s own fields, is the things that are current state with no dates of their own: the job categories and vehicle classes they are booked for, the four site lists — suitable, not suitable, assessed and banned — and the free-text notes. A list you send is reconciled against what is held, so an id you leave out of it is removed; send an empty list to clear one. A list you omit altogether is left alone, and so are the notes: nothing historises any of them, and a client’s ban lifted by an update that never mentioned it could not be recovered.
Status is not something the published API changes yet. A worker holds one status at a time, and every move between statuses is recorded with the reason for it — a trail that is append-only and that you can read. What you cannot do through this version is move the worker: the status you get back is the one set at registration or changed elsewhere.
Sub-resources are history, and history accumulates. A renewal is a new record with its own dates, never an edit of the one it renews — that is as true of a Driver CPC period as it is of a right-to-work document. Correcting a record and superseding one are different acts, and every correction replaces that record in full. Removal is permanent everywhere: none of these tables has a soft delete. Two of them cascade, because the child has no meaning without its parent — removing a licence removes its convictions, and removing a CPC training period removes the modules recorded in it.
Compliance documents are a register rather than a list of current values. A worker holds the same document type repeatedly over the years, each with its own dates, so documents accumulate: a renewal is a new record, and correcting a record is a different act from superseding it. Removing one is permanent — there is no soft delete and nothing to restore — so it is for a document recorded in error, never for one that has merely expired. A worker always holds at least one, so the last document cannot be removed at all; replace it by adding the right one first.
Creating a worker means supplying ids for title, gender, nationality, worker type and similar. Those come from platform-wide read-only vocabularies, which you can list through the API — see Reference data and agency lookups.
Common misconceptions
Section titled “Common misconceptions”“The worker number is the id.” It is not. The number is your agency’s own reference; the id is what the endpoints take.
“Searching by email finds anyone whose address contains it.” It does not. The email filter matches the whole address, ignoring case, and part of an address matches nothing. Search by name when all you have is a fragment.
“An update only changes the fields I send.” It does not. It replaces the worker’s details in full, so a field left out is cleared rather than kept.
“Recording a renewed document means updating the old one.” It does not. A renewal is a new document; overwriting the old record erases the period it evidenced from the register.
“Engagement type is just reporting metadata.” It determines how the person is paid and which statutory documents apply. Setting it wrongly is a payroll problem, not a data-quality one.
Reference data and agency lookups — where the ids a worker record refers to come from.