Update a worker
const url = 'https://api2.recruso.co.uk/v1/workers/1';const options = { method: 'PUT', headers: {Authorization: '<Authorization>', 'Content-Type': 'application/json'}, body: '{"id":4821,"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 PUT \ --url https://api2.recruso.co.uk/v1/workers/1 \ --header 'Authorization: <Authorization>' \ --header 'Content-Type: application/json' \ --data '{ "id": 4821, "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 ] }'Updates one worker in your own agency.
This is a full replacement, not a partial merge: every mutable field is written from the request, so a field you omit is set to null. Send the complete record, not just the fields you are changing.
The same validation as CreateWorker applies — bank details are required for every payment method except Cheque, a building society account also requires the society name, SubContractorId is required for a subcontractor worker type, the starter-checklist statements are cleared for tax forms that do not use them, and an unset tax code falls back to your agency’s default. Every referenced id must exist and belong to your agency; one that does not returns 400.
At least one job category is required here too: an edit is a full replacement, so a worker cannot be saved with the list emptied.
Job categories and vehicle categories are reconciled against the ids you send: those already held are kept as they are, those missing from the request are removed, and only new ones are added. The first job category is the worker’s default. Reconciling rather than replacing is also what keeps a surviving vehicle category’s original audit intact.
The four site lists — SuitableAtSiteIds, NotSuitableAtSiteIds, AssessedAtSiteIds and BannedAtSiteIds — are reconciled the same way, and are independent of one another: a site may appear on more than one. Every id you add must be a site of your own agency; one that is not returns 400 rather than disclosing that it exists elsewhere. A site the worker already holds on a list is not checked again, so it stays on that list even after your agency deletes the site.
VehicleCategoryIds and the four site lists are exceptions to full replacement: omit one, or send it as null, and the list already held is left exactly as it is; send an empty list to clear it. Nothing historises them, and a client’s ban lifted by an update that never mentioned it could not be recovered.
Some of a worker’s record is deliberately out of reach here. BranchId, WorkerNumber, RegisteredDate and the created-by audit are fixed at registration. Compliance documents and the worker’s status are effective-dated history rather than current state, so they are not part of this request and are returned unchanged — a save of the worker’s details can never delete a right-to-work record. A worker paid by cheque keeps any bank account already on file rather than having it deleted.
AdditionalDetails — the free-text notes — is also an exception to full replacement: omit it and the notes on file are left alone, because nothing historises them and a silently cleared blacklist reason or assessment could not be recovered. Send the object to write them, and every field within it is replaced.
A worker id belonging to another agency returns 404 rather than 403, so their existence is never disclosed. modifiedBy and modifiedOn are set from your credentials and the current UK local time; they are not taken from the request.
Access. Requires a client-credentials access token. Tokens issued through the interactive user login are rejected.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The id path parameter
Request Bodyrequired
Section titled “Request Bodyrequired”The replacement details for a worker. Every mutable field is written from the request, so a field you omit is set to null — except the free-text notes, the vehicle categories and the four site lists, which are left as they are when omitted.
object
The worker to update. Taken from the route; a value in the request body is ignored.
Example
4821The 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”OK
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"}Not Found
object
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example"}