Onboard a worker

By the end of this guide you will have created a worker against one of your branches and read the record back, with the worker number your agency’s sequence allocated.

Before you start

• A client-credentials access token.

• A read of Workers — especially the engagement types, which change what else you must send.

• A read of Reference data and agency lookups: a worker record refers to title, gender, nationality, worker type and similar by id, and you will want those lists to hand.

1. Choose the branch

A worker is registered against one branch, and it must be one your credentials can reach.

GET /v1/branches
Authorization: Bearer {accessToken}

This list is already narrowed to the branches the Recruso user behind your API app can access, so anything it returns is a valid choice — and anything it omits will be rejected even if the branch exists in your agency.

2. Collect the ids the record refers to

A worker points at two different tiers of configuration data, and both are readable through the API.

Platform-wide vocabularies — read-only, identical for every agency:

GET /v1/reference/titles
GET /v1/reference/genders
GET /v1/reference/nationalities
GET /v1/reference/worker-types
Authorization: Bearer {accessToken}

Your agency’s own lookups — job categories are the common one, and every id you send must belong to your agency:

GET /v1/job-categories
Authorization: Bearer {accessToken}

Fetch these before building the payload rather than guessing an id. See Work with agency lookups for the wider family.

3. Resolve the conditional requirements

This is where creation usually fails, because these fields are not required in general — they become required because of something else you set.

Work through them in this order:

1. Payment method. Bank details are required for every method except cheque. A building society account additionally needs the society name.
2. Engagement type. A subcontractor type must name the subcontractor the worker comes through.
3. Tax form. Starter-checklist statements are ignored by forms that do not use them, and for some forms the tax code you send is overridden entirely — so do not treat your value as authoritative.

The operation description in the reference states the exact rules. Read it rather than working from this summary.

4. Create the worker

Send the payload to the create endpoint. Fields you leave unset fall back to your agency’s own defaults — the default tax code, the default worker status, the default payment frequency — which means an identical request against a different agency produces a different worker. Set explicitly anything you care about rather than relying on a default you have not read.

The response is the created record, including the worker number allocated from your agency’s sequence.

5. Keep the id

Store the worker id from the response immediately. Store the worker number too — it is what appears on paperwork — but do not use it as your key; the id is what the endpoints take.

An id you fail to record can be found again, because listing workers doubles as a search:

GET /v1/workers?workerNumber=10432
GET /v1/workers?email=alice.baker@example.co.uk
Authorization: Bearer {accessToken}

Both return a page of summaries rather than a single record, so read the workerId from the entry and fetch the full record with it. The email match is on the whole address, ignoring case. Recovering ids this way is a fallback, not a design: keep the id and you never need the extra call.

Verify the outcome

Read the worker back:

GET /v1/workers/{workerId}
Authorization: Bearer {accessToken}

Check three things: the branch is the one you chose, the worker number is populated, and any field you deliberately left unset carries your agency’s default rather than a null you did not expect.

Failure modes

What you see	Why	What to do
400 naming a bank details field	The payment method requires them, and cheque is the only exception	Supply the bank details, or set the method to cheque
400 naming the subcontractor	The engagement type is a subcontractor type	Supply the subcontractor, or change the engagement type
400 on a job category id	The id belongs to another agency	Re-read the job categories list under these credentials
400 on a title or worker type id	The id is not in that vocabulary	Re-read the vocabulary; do not use a hardcoded mapping
400 or 404 on the branch	The branch is not in your accessible-branch list	Choose one the branches list returned
The tax code differs from what you sent	The tax form overrides it	Expected. Check which form you set
You have lost the worker id	It was not stored from the create response	List workers filtered by the worker number or email address, and take workerId from the entry
The list by email returns nothing	The filter matches the whole address, not part of it	Send the complete address, or search by name instead

Endpoints

Method	Path	What it does
POST	/v1/workers	Create a worker
GET	/v1/workers/{id}	Get worker details
GET	/v1/workers	List workers
GET	/v1/branches	List branches
GET	/v1/job-categories	List job categories
GET	/v1/reference/titles	List titles
GET	/v1/reference/worker-types	List worker types

Next

Handle and recover from validation errors — the failures above, and how to react to them systematically.