List workers
const url = 'https://api2.recruso.co.uk/v1/workers?pageNumber=1&pageSize=25&name=baker&email=alice.baker%40example.co.uk&workerNumber=10432&branchId=4&workerStatusTypeId=3&sortColumn=surname&sortOrder=asc';const options = {method: 'GET', headers: {Authorization: '<Authorization>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://api2.recruso.co.uk/v1/workers?pageNumber=1&pageSize=25&name=baker&email=alice.baker%40example.co.uk&workerNumber=10432&branchId=4&workerStatusTypeId=3&sortColumn=surname&sortOrder=asc' \ --header 'Authorization: <Authorization>'Returns a paged list of the workers in your own agency. Sent without filters it lists them all; with filters it is how you find a worker — by name, email address, worker number, branch or current status. Filters combine, so a worker must match every one you send.
Each entry is a summary rather than the full record: who the worker is, how they are engaged — branch, cost centre, worker type, status, rating and transport — and how to reach them. Call GetWorkerById for one worker’s complete details; tax, bank and compliance details never appear in this list.
name matches case-insensitively on any part of the forename, surname or known-as name, or of the full name, so john smi finds John Smith. email is a case-insensitive match on the whole address: part of an address matches nothing. workerNumber and branchId are exact matches. workerStatusTypeId matches the worker’s current status, as an id from the worker status types vocabulary; an id that does not exist returns 400.
Workers who have left and workers engaged through a subcontractor are included. A worker whose record has been GDPR-deleted never appears, and neither does a worker registered against a branch the Recruso user behind your API app cannot access — even when branchId names that branch.
Results are paged: 25 per page by default, capped at 100. pageNumber below 1 is treated as 1. Sort with sortColumn (surname, forename, workernumber, createdon or modifiedon) and sortOrder (asc or desc); an unrecognised column sorts by surname.
Access. Requires a client-credentials access token. Tokens issued through the interactive user login are rejected.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”Page number, 1-based. Defaults to 1; anything below 1 is treated as 1.
Example
1Page number, 1-based. Defaults to 1; anything below 1 is treated as 1.
Number of workers per page. Defaults to 25, capped at 100.
Example
25Number of workers per page. Defaults to 25, capped at 100.
Case-insensitive partial match on the forename, the surname, the known-as name or the full name, so “john smi” finds John Smith.
Example
bakerCase-insensitive partial match on the forename, the surname, the known-as name or the full name, so “john smi” finds John Smith.
Case-insensitive match on the whole email address. Part of an address matches nothing.
Example
alice.baker@example.co.ukCase-insensitive match on the whole email address. Part of an address matches nothing.
Exact match on your agency’s worker number.
Example
10432Exact match on your agency’s worker number.
Exact match on the branch the worker is registered against.
Example
4Exact match on the branch the worker is registered against.
The worker’s current status, as an id from the platform Worker status types vocabulary. An id that does not exist returns 400.
Example
3The worker’s current status, as an id from the platform Worker status types vocabulary. An id that does not exist returns 400.
Column to sort by: surname, forename, workernumber, createdon or modifiedon. Defaults to surname, and an unrecognised value falls back to surname rather than failing.
Example
surnameColumn to sort by: surname, forename, workernumber, createdon or modifiedon. Defaults to surname, and an unrecognised value falls back to surname rather than failing.
Sort direction: asc (the default) or desc.
Example
ascSort direction: asc (the default) or desc.
Responses
Section titled “Responses”OK
object
One worker in a list: who they are, how they are engaged and how to reach them. Call GetWorkerById for the full record — this summary never carries tax, bank or compliance details.
object
The worker’s surrogate identifier. Use this on subsequent worker endpoints.
The worker’s human-facing reference, allocated from your agency’s own worker number sequence at creation.
The worker’s first name.
The worker’s family name.
What the worker prefers to be called, when it differs from their forename.
The worker’s date of birth.
The branch the worker is registered against.
The cost centre the worker is booked against.
The worker’s engagement type, as an id from the platform Worker types vocabulary.
The worker’s current status, as an id from the platform Worker status types vocabulary. Null for a worker who has never been given one.
The worker’s rating, on a 1-10 scale.
How the worker travels to work.
The town or city of the worker’s home address.
The county of the worker’s home address.
The postcode of the worker’s home address.
The worker’s mobile number.
The worker’s email address.
When the worker was created, in UK local time.
When the worker’s details were last updated, in UK local time. Null until they have been.
Example
{ "data": [ { "workerId": 4821, "workerNumber": 10432, "forename": "Alice", "surname": "Baker", "knownAs": "Ali", "birthDate": "1990-04-12", "branchId": 4, "costCentreId": 3, "workerTypeId": 1, "workerStatusTypeId": 3, "workerRating": 8, "transportId": 2, "town": "Manchester", "county": "Greater Manchester", "postalCode": "M1 1AA", "mobile": "07700 900123", "email": "alice.baker@example.co.uk", "createdOn": "2026-08-14T09:41:02", "modifiedOn": "2026-09-02T15:08:47" } ]}Bad Request
object
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example"}Unauthorized
object
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example"}Forbidden
object
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example"}