Create a worker
const url = 'https://api2.recruso.co.uk/v1/workers';const options = { method: 'POST', headers: {Authorization: '<Authorization>', 'Content-Type': 'application/json'}, body: '{"branchId":4,"compliances":[{"complianceId":3,"startDate":"2026-01-15","endDate":"2031-01-14"}],"titleId":2,"forename":"Alice","surname":"Baker","knownAs":"Ali","initials":"AB","birthDate":"1990-04-12","genderId":2,"maritalStatusId":1,"ethnicOriginId":3,"nationalityId":14,"address1":"12 High Street","address2":"Flat 2","town":"Manchester","county":"Greater Manchester","country":"United Kingdom","postalCode":"M1 1AA","telephone1":"0161 496 0123","mobile":"07700 900123","email":"alice.baker@example.co.uk","nextOfKinFullName":"Jane Baker","nextOfKinContactNumber":"07700 900456","nextOfKinEmailAddress":"jane.baker@example.co.uk","niNumber":"AB123456C","formId":1,"niCategoryId":1,"statementA":true,"statementB":false,"statementC":false,"noStatement":false,"employeeTaxCode":"1257L","week1BasisFlag":false,"paymentMethodId":1,"dni":false,"hiWiz":false,"safetyBoots":true,"digitalTacho":false,"wtdOptout":false,"isStudent":false,"canNotSendSmsEmail":false,"workerRating":8,"costCentreId":3,"workerTypeId":1,"transportId":2,"recruitmentSourceId":6,"workRadius":25,"minimumHourlyRate":12.21,"minimumDailyRate":97.68,"rtwShareCode":"W3K 9QP 7ZB","subContractorId":55,"bankDetails":{"bankAccountTypeId":1,"accountName":"A Baker","accountNumber":"12345678","sortCode":"01-02-03","buildingSoc":"Skipton"},"additionalDetails":{"memo":"Prefers early shifts; will travel to Salford at short notice.","experience":"Three years warehouse picking, counterbalance FLT since 2023.","notes":"Registered in branch; documents seen in person.","blacklistReason":"Left a shift without notice at Trafford Park, 14 August 2026.","assessment":"Assessed on counterbalance FLT 12 May 2026 — competent, no retraining needed.","bookingAvailabilityNotes":"Not available Thursdays; college day."},"jobCategoryIds":[1],"vehicleCategoryIds":[1],"suitableAtSiteIds":[1],"notSuitableAtSiteIds":[1],"assessedAtSiteIds":[1],"bannedAtSiteIds":[1]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api2.recruso.co.uk/v1/workers \ --header 'Authorization: <Authorization>' \ --header 'Content-Type: application/json' \ --data '{ "branchId": 4, "compliances": [ { "complianceId": 3, "startDate": "2026-01-15", "endDate": "2031-01-14" } ], "titleId": 2, "forename": "Alice", "surname": "Baker", "knownAs": "Ali", "initials": "AB", "birthDate": "1990-04-12", "genderId": 2, "maritalStatusId": 1, "ethnicOriginId": 3, "nationalityId": 14, "address1": "12 High Street", "address2": "Flat 2", "town": "Manchester", "county": "Greater Manchester", "country": "United Kingdom", "postalCode": "M1 1AA", "telephone1": "0161 496 0123", "mobile": "07700 900123", "email": "alice.baker@example.co.uk", "nextOfKinFullName": "Jane Baker", "nextOfKinContactNumber": "07700 900456", "nextOfKinEmailAddress": "jane.baker@example.co.uk", "niNumber": "AB123456C", "formId": 1, "niCategoryId": 1, "statementA": true, "statementB": false, "statementC": false, "noStatement": false, "employeeTaxCode": "1257L", "week1BasisFlag": false, "paymentMethodId": 1, "dni": false, "hiWiz": false, "safetyBoots": true, "digitalTacho": false, "wtdOptout": false, "isStudent": false, "canNotSendSmsEmail": false, "workerRating": 8, "costCentreId": 3, "workerTypeId": 1, "transportId": 2, "recruitmentSourceId": 6, "workRadius": 25, "minimumHourlyRate": 12.21, "minimumDailyRate": 97.68, "rtwShareCode": "W3K 9QP 7ZB", "subContractorId": 55, "bankDetails": { "bankAccountTypeId": 1, "accountName": "A Baker", "accountNumber": "12345678", "sortCode": "01-02-03", "buildingSoc": "Skipton" }, "additionalDetails": { "memo": "Prefers early shifts; will travel to Salford at short notice.", "experience": "Three years warehouse picking, counterbalance FLT since 2023.", "notes": "Registered in branch; documents seen in person.", "blacklistReason": "Left a shift without notice at Trafford Park, 14 August 2026.", "assessment": "Assessed on counterbalance FLT 12 May 2026 — competent, no retraining needed.", "bookingAvailabilityNotes": "Not available Thursdays; college day." }, "jobCategoryIds": [ 1 ], "vehicleCategoryIds": [ 1 ], "suitableAtSiteIds": [ 1 ], "notSuitableAtSiteIds": [ 1 ], "assessedAtSiteIds": [ 1 ], "bannedAtSiteIds": [ 1 ] }'Registers a worker against one of your branches and returns the created record, including the worker number allocated from your agency’s sequence.
Several fields are conditionally required rather than always required:
- Bank details are required for every payment method except Cheque. A building society account additionally requires the society name.
- SubContractorId is required when the worker type is a subcontractor type.
- Starter-checklist statements are ignored for tax forms that do not use them, and the tax code is overridden when the form is None or Not Required.
Unset fields fall back to your agency’s defaults — the default tax code, the default worker status, and weekly payment frequency. BranchId must be a branch you can access. At least one JobCategoryIds entry is required, and every one of them must belong to your agency. VehicleCategoryIds are ids from the platform Vehicle categories vocabulary — the same for every agency — and are optional, as are the four site lists, whose ids must be sites of your own agency.
BranchId and the compliance documents are only settable here: UpdateWorker changes neither.
AdditionalDetails — the free-text notes — is optional here and on UpdateWorker. Most workers are registered without any, and the record is only written when the object is sent.
Access. Requires a client-credentials access token. Tokens issued through the interactive user login are rejected.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”A new worker: the fields shared with an edit, plus the two that only a registration carries — the branch the worker is registered against and the compliance documents that clear them to start work.
object
The branch to register the worker against. Must be a branch the Recruso user behind your API app can access. Set once — a worker cannot be moved between branches through the worker endpoints.
Example
4Compliance documents. At least one is required.
A single compliance document held for the worker.
object
The kind of document, as an id from your agency’s Compliance lookup.
Example
3The date the document takes effect.
Example
2026-01-15The date the document expires. Must not be before the start date.
Example
2031-01-14The worker’s title, as an id from the platform Titles vocabulary. Required.
Example
2The worker’s first name. Required, up to 100 characters.
Example
AliceThe worker’s family name. Required, up to 50 characters.
Example
BakerWhat the worker prefers to be called, when it differs from their forename.
Example
AliThe worker’s initials, up to 7 characters.
Example
ABThe worker’s date of birth. Required, and they must be at least 16 years old.
Example
1990-04-12The worker’s gender, as an id from the platform Genders vocabulary.
Example
2The worker’s marital status, as an id from the platform vocabulary.
Example
1The worker’s ethnic origin, as an id from the platform vocabulary.
Example
3The worker’s nationality, as an id from the platform Nationalities vocabulary.
Example
14The first line of the worker’s home address. Required, up to 100 characters.
Example
12 High StreetThe second line of the worker’s home address, up to 50 characters.
Example
Flat 2The town or city of the worker’s home address.
Example
ManchesterThe county of the worker’s home address.
Example
Greater ManchesterThe country of the worker’s home address.
Example
United KingdomThe postcode of the worker’s home address. Required, up to 50 characters.
Example
M1 1AAThe worker’s landline number, up to 50 characters.
Example
0161 496 0123The worker’s mobile number. Required, up to 50 characters.
Example
07700 900123The worker’s email address. Required, and must be a valid address.
Example
alice.baker@example.co.ukWho to contact in an emergency, up to 150 characters.
Example
Jane BakerThe emergency contact’s telephone number, up to 50 characters.
Example
07700 900456The emergency contact’s email address. Must be a valid address when supplied.
Example
jane.baker@example.co.ukThe worker’s National Insurance number. Required, up to 50 characters.
Example
AB123456CThe tax form the worker provided, as an id from the platform Forms provided vocabulary. Required. The form decides whether the starter-checklist statements below carry any meaning, and for two of the forms it overrides the tax code outright.
Example
1The worker’s National Insurance category letter, as an id from the platform vocabulary. Required.
Example
1Starter-checklist statement A: this is their first job since 6 April. Cleared for forms that do not use the starter checklist.
Example
trueStarter-checklist statement B: this is now their only job. Defaults to true when omitted, and cleared for forms that do not use the starter checklist.
Example
falseStarter-checklist statement C: they have another job or a pension. Cleared for forms that do not use the starter checklist.
Example
falseThe starter-checklist “none of the above” statement. Cleared for forms that do not use the starter checklist.
Example
falseThe worker’s tax code, up to 50 characters. Left unset, this falls back to your agency’s default tax code. A tax form of None applies the emergency code instead, and Not Required leaves the worker without one.
Example
1257LWhether tax is calculated on a week-1/month-1 basis rather than cumulatively. Defaults to false when omitted, and forced to false when the tax form is None or Not Required.
Example
falseHow the worker is paid, as an id from the platform Payment methods vocabulary. Required. Bank details must accompany every method except Cheque.
Example
1Whether the worker is flagged Do Not Import.
Example
falseWhether the worker uses HiWiz.
Example
falseWhether the worker holds their own safety boots.
Example
trueWhether the worker holds a digital tachograph card.
Example
falseWhether the worker has opted out of the Working Time Directive.
Example
falseWhether the worker is a student.
Example
falseDo not send SMS/Email. Defaults to false when omitted.
Example
falseWorker rating from 1 to 10.
Example
8The cost centre the worker is booked against, as an id from your agency’s Cost centres. Required.
Example
3How the worker is engaged, as an id from the platform Worker types vocabulary. Required. Subcontractor types additionally require .
Example
1How the worker travels to work, as an id from your agency’s Transports lookup.
Example
2Where the worker came from, as an id from your agency’s Recruitment sources lookup.
Example
6How far the worker is willing to travel, in miles, from 1 to 100.
Example
25The lowest hourly rate the worker will accept. Cannot be negative.
Example
12.21The lowest daily rate the worker will accept. Cannot be negative.
Example
97.68The worker’s Home Office right-to-work share code, up to 20 characters.
Example
W3K 9QP 7ZBThe subcontractor the worker is engaged through. Required when the worker type is Limited, PSC-In Scope or PSC-Out of Scope.
Example
55Where the worker’s pay is sent. Required unless the payment method is Cheque; the mandatory fields within depend on the account type — see .
object
The kind of account, as an id from the platform Bank account types vocabulary — a bank account or a building society account. It decides which of the fields below are mandatory.
Example
1The name the account is held in, up to 75 characters.
Example
A BakerThe account number, up to 12 characters.
Example
12345678The sort code, up to 8 characters.
Example
01-02-03The building society name or roll number, up to 50 characters. Required for a building society account.
Example
SkiptonFree-text notes about the worker. Optional, and the one part of this request that is not a replacement: omit it and the notes already on file are left exactly as they are. Send it and every field within it is written, so a field you leave out of a sent object is cleared.
object
A short note about the worker, up to 550 characters.
Example
Prefers early shifts; will travel to Salford at short notice.The work the worker has done before, up to 600 characters.
Example
Three years warehouse picking, counterbalance FLT since 2023.General notes, up to 650 characters.
Example
Registered in branch; documents seen in person.Why the worker is blacklisted, up to 1000 characters. Recording a reason here does not itself blacklist anyone — the worker’s status is a separate matter.
Example
Left a shift without notice at Trafford Park, 14 August 2026.The outcome of assessing the worker, up to 1500 characters.
Example
Assessed on counterbalance FLT 12 May 2026 — competent, no retraining needed.Notes about when the worker can be booked, up to 1000 characters.
Example
Not available Thursdays; college day.Job categories the worker can be booked for, as ids from your agency’s Job categories lookup. Required — at least one and at most 500, with no duplicates. The first entry is recorded as the worker’s default category.
The vehicle classes the worker is licensed to drive, as ids from the platform Vehicle categories vocabulary. At most 500, with no duplicates. Optional — most workers drive nothing. On an update, omit it to keep the list held and send an empty list to clear it.
Sites the worker is approved to work at, as ids of your agency’s own sites. At most 500, with no duplicates. On an update, omit it to keep the list held and send an empty list to clear it.
Sites the worker is not to be sent to, as ids of your agency’s own sites. At most 500, with no duplicates. A site can appear here and in at once — nothing rejects the combination, because the legacy data already contains it. On an update, omit it to keep the list held and send an empty list to clear it.
Sites the worker has been assessed at, as ids of your agency’s own sites. At most 500, with no duplicates. On an update, omit it to keep the list held and send an empty list to clear it.
Sites that have banned the worker, as ids of your agency’s own sites. At most 500, with no duplicates. On an update, omit it to keep the bans held and send an empty list to lift them all: a ban is not historised, so one lifted by mistake cannot be recovered.
Responses
Section titled “Responses”Created
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. Unique within the agency, not across the platform.
The branch the worker is registered against. Fixed at registration.
The worker’s title, as an id from the platform Titles vocabulary.
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 initials.
The worker’s date of birth.
The worker’s gender, as an id from the platform Genders vocabulary.
The worker’s marital status, as an id from the platform vocabulary.
The worker’s ethnic origin, as an id from the platform vocabulary.
The worker’s nationality, as an id from the platform Nationalities vocabulary.
The first line of the worker’s home address.
The second line of the worker’s home address.
The town or city of the worker’s home address.
The county of the worker’s home address.
The country of the worker’s home address.
The postcode of the worker’s home address.
The worker’s landline number.
The worker’s mobile number.
The worker’s email address.
Who to contact in an emergency.
The emergency contact’s telephone number.
The emergency contact’s email address.
Whether the worker is flagged Do Not Import.
Whether the worker uses HiWiz.
Whether the worker holds their own safety boots.
Whether the worker holds a digital tachograph card.
Whether the worker has opted out of the Working Time Directive.
Whether the worker is a student.
Whether the worker has asked not to be sent SMS or email.
The worker’s rating, on a 1-10 scale.
The cost centre the worker is booked against.
The worker’s engagement type. Subcontractor types additionally require to be set.
How the worker travels to work.
Where the worker came from, as an id from your agency’s Recruitment sources lookup.
How far the worker is willing to travel, in miles.
The lowest hourly rate the worker will accept.
The lowest daily rate the worker will accept.
The worker’s Home Office right-to-work share code.
The subcontractor the worker is engaged through, when the worker type requires one.
The date the worker was registered, in UK local time. Fixed at registration.
The Recruso user the worker is registered under.
The Recruso user id (tblUsers.UserID) that created the worker, not the ASP.NET Identity id.
When the worker was created, in UK local time.
The Recruso user id (tblUsers.UserID) that last updated the worker, not the ASP.NET Identity id. Null until the worker has been updated.
When the worker was last updated, in UK local time. Null until the worker has been updated.
The worker’s current status. Assigned from the agency default at registration, when one is configured; updating a worker’s details does not change it.
The worker’s tax and payment setup.
object
The worker’s National Insurance number.
The tax form the worker provided. Forms that do not use the starter checklist clear the statement fields below; a form of None or Not Required also overrides .
The worker’s National Insurance category letter.
Starter-checklist statement A: this is their first job since 6 April.
Starter-checklist statement B: this is now their only job. Defaults to true.
Starter-checklist statement C: they have another job or a pension.
The starter-checklist “none of the above” statement.
The worker’s tax code. Falls back to the agency’s default tax code when the request does not supply one.
When true, tax is calculated on a week-1/month-1 basis rather than cumulatively.
How the worker is paid. Every method other than Cheque requires to be present.
How often the worker is paid. New workers default to weekly, and an update keeps whatever they are already on.
Where the worker’s pay is sent. Absent for a worker who has never had an account on file.
object
The kind of account. A building society account additionally requires .
The name the account is held in.
The account number.
The sort code.
The building society name, required for building society accounts.
Free-text notes about the worker. Absent for a worker nobody has written a note about.
object
A short note about the worker.
The work the worker has done before.
General notes.
Why the worker is blacklisted, where a reason has been recorded.
The outcome of assessing the worker.
Notes about when the worker can be booked.
The compliance documents held for the worker. Set at registration; updating a worker’s details leaves them untouched.
A compliance document held for the worker.
object
The record’s identifier.
The kind of document, as an id from your agency’s Compliance lookup.
The date the document takes effect.
The date the document expires.
The vehicle classes the worker is licensed to drive, as ids from the platform Vehicle categories vocabulary.
Sites the worker is approved to work at.
Sites the worker is not to be sent to.
Sites the worker has been assessed at.
Sites that have banned the worker.
The job categories the worker can be booked for.
A job category the worker can be booked for.
object
The record’s identifier. Stable across updates that keep the category.
The job category, as an id from your agency’s Job categories lookup.
Whether this is the worker’s default category — the first one sent on a write.
Example
{ "workerId": 4821, "workerNumber": 10432, "branchId": 4, "titleId": 2, "forename": "Alice", "surname": "Baker", "knownAs": "Ali", "initials": "AB", "birthDate": "1990-04-12", "genderId": 2, "maritalStatusId": 1, "ethnicOriginId": 3, "nationalityId": 14, "address1": "12 High Street", "address2": "Flat 2", "town": "Manchester", "county": "Greater Manchester", "country": "United Kingdom", "postalCode": "M1 1AA", "telephone1": "0161 496 0123", "mobile": "07700 900123", "email": "alice.baker@example.co.uk", "nextOfKinFullName": "Jane Baker", "nextOfKinContactNumber": "07700 900456", "nextOfKinEmailAddress": "jane.baker@example.co.uk", "dni": false, "hiWiz": false, "safetyBoots": true, "digitalTacho": false, "wtdOptout": false, "isStudent": false, "canNotSendSmsEmail": false, "workerRating": 8, "costCentreId": 3, "workerTypeId": 1, "transportId": 2, "recruitmentSourceId": 6, "workRadius": 25, "minimumHourlyRate": 12.21, "minimumDailyRate": 97.68, "rtwShareCode": "W3K 9QP 7ZB", "subContractorId": 55, "registeredDate": "2026-08-14", "userId": 100, "createdBy": 100, "createdOn": "2026-08-14T09:41:02", "modifiedBy": 100, "modifiedOn": "2026-09-02T15:08:47", "workerStatusTypeId": 3, "taxDetails": { "niNumber": "AB123456C", "formId": 1, "niCategoryId": 1, "statementA": true, "statementB": false, "statementC": false, "noStatement": false, "employeeTaxCode": "1257L", "week1BasisFlag": false, "paymentMethodId": 1, "paymentFrequencyId": 1 }, "bankDetails": { "bankAccountTypeId": 1, "accountName": "A Baker", "accountNumber": "12345678", "sortCode": "01-02-03", "buildingSoc": "Skipton" }, "additionalDetails": { "memo": "Prefers early shifts; will travel to Salford at short notice.", "experience": "Three years warehouse picking, counterbalance FLT since 2023.", "notes": "Registered in branch; documents seen in person.", "blacklistReason": "Left a shift without notice at Trafford Park, 14 August 2026.", "assessment": "Assessed on counterbalance FLT 12 May 2026 — competent, no retraining needed.", "bookingAvailabilityNotes": "Not available Thursdays; college day." }, "compliances": [ { "workerComplianceId": 7311, "complianceId": 3, "startDate": "2026-01-15", "endDate": "2031-01-14" } ], "jobCategories": [ { "workerJobCategoryId": 9014, "jobCategoryId": 27, "isDefault": true } ]}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"}