Skip to content
Recruso API

Update one of a worker's previous employments

PUT
/v1/workers/{workerId}/previous-employments/{id}
curl --request PUT \
  --url https://api2.recruso.co.uk/v1/workers/1/previous-employments/1 \
  --header 'Authorization: <Authorization>' \
  --header 'Content-Type: application/json' \
  --data '{ "workerId": 4821, "id": 6602, "clientName": "Northgate Logistics Ltd", "companyRegNumber": "04512339", "telephone": "0161 496 0142", "fax": "0161 496 0143", "email": "hr@northgate-logistics.example.co.uk", "workerPosition": "Warehouse operative", "contactPersonName": "Priya Raval", "contactPersonPosition": "Shift manager", "reasonForLeft": "Site closed", "experience": "Picking and packing, plus counterbalance FLT from 2023.", "workFrom": "2022-04-04", "workTo": "2025-11-28", "honest": true, "reEmploy": true, "abilityRank": 4, "timeKeepingRank": 5, "referenceSentDate": "2026-01-06", "referenceOutcome": "Received 14 January 2026, satisfactory" }'

Replaces a previous employment recorded for a worker in your own agency.

This is a full replacement of that one record, not a partial merge: a field you omit is set to null. Recording a reference that has come back therefore means sending the employment’s other fields with it, not just the outcome.

A record that belongs to a different worker, or to another agency, returns 404 rather than 403. 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”
workerId
required
integer format: int32

The workerId path parameter

id
required
integer format: int32

The id path parameter

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

The replacement values for a previous employment already recorded. Every field is written from the request, so a field you omit is set to null.

object
workerId

The worker the employment belongs to. Taken from the route; a value in the request body is ignored.

integer format: int32
Example
4821
id

The employment record to update. Taken from the route; a value in the request body is ignored.

integer format: int32
Example
6602
clientName

The employer’s name, up to 100 characters. Required.

string
Example
Northgate Logistics Ltd
companyRegNumber

The employer’s company registration number, up to 20 characters. Required.

string
Example
04512339
telephone

A telephone number for the employer, up to 20 characters.

string
nullable
Example
0161 496 0142
fax

A fax number for the employer, up to 20 characters.

string
nullable
Example
0161 496 0143
email

An email address for the employer, up to 250 characters.

string
nullable
Example
hr@northgate-logistics.example.co.uk
workerPosition

The job the worker did there, up to 50 characters.

string
nullable
Example
Warehouse operative
contactPersonName

Who to ask for a reference, up to 50 characters.

string
nullable
Example
Priya Raval
contactPersonPosition

That person’s job, up to 50 characters.

string
nullable
Example
Shift manager
reasonForLeft

Why the worker left, up to 255 characters.

string
nullable
Example
Site closed
experience

What the worker did there, up to 350 characters.

string
nullable
Example
Picking and packing, plus counterbalance FLT from 2023.
workFrom

The date the worker started there.

string format: date
nullable
Example
2022-04-04
workTo

The date the worker left. Must not be before the start date.

string format: date
nullable
Example
2025-11-28
honest

Whether the reference described the worker as honest.

boolean
nullable
Example
true
reEmploy

Whether the employer said they would re-employ the worker.

boolean
nullable
Example
true
abilityRank

How the reference graded the worker’s ability, from 0 to 5 inclusive. Leave it out when the reference did not grade them.

integer format: uint8
nullable
Example
4
timeKeepingRank

How the reference graded the worker’s time keeping, from 0 to 5 inclusive. Leave it out when the reference did not grade them.

integer format: uint8
nullable
Example
5
referenceSentDate

The date the reference request was sent.

string format: date
nullable
Example
2026-01-06
referenceOutcome

What came back, up to 150 characters.

string
nullable
Example
Received 14 January 2026, satisfactory

Responses

Section titled “Responses”

200

Section titled “200”

OK

Media typeapplication/json
object
previousEmploymentId

The record’s identifier.

integer format: int32
clientName

The employer’s name.

string
companyRegNumber

The employer’s company registration number.

string
telephone

A telephone number for the employer.

string
nullable
fax

A fax number for the employer.

string
nullable
email

An email address for the employer.

string
nullable
workerPosition

The job the worker did there.

string
nullable
contactPersonName

Who to ask for a reference.

string
nullable
contactPersonPosition

That person’s job.

string
nullable
reasonForLeft

Why the worker left.

string
nullable
experience

What the worker did there.

string
nullable
workFrom

The date the worker started there.

string format: date
nullable
workTo

The date the worker left.

string format: date
nullable
honest

Whether the reference described the worker as honest.

boolean
nullable
reEmploy

Whether the employer said they would re-employ the worker.

boolean
nullable
abilityRank

How the reference graded the worker’s ability, from 0 to 5 inclusive. Null when the reference did not grade them.

integer format: uint8
nullable
timeKeepingRank

How the reference graded the worker’s time keeping, from 0 to 5 inclusive. Null when the reference did not grade them.

integer format: uint8
nullable
referenceSentDate

The date the reference request was sent.

string format: date
nullable
referenceOutcome

What came back.

string
nullable
Example
{
  "previousEmploymentId": 6602,
  "clientName": "Northgate Logistics Ltd",
  "companyRegNumber": "04512339",
  "telephone": "0161 496 0142",
  "fax": "0161 496 0143",
  "email": "hr@northgate-logistics.example.co.uk",
  "workerPosition": "Warehouse operative",
  "contactPersonName": "Priya Raval",
  "contactPersonPosition": "Shift manager",
  "reasonForLeft": "Site closed",
  "experience": "Picking and packing, plus counterbalance FLT from 2023.",
  "workFrom": "2022-04-04",
  "workTo": "2025-11-28",
  "honest": true,
  "reEmploy": true,
  "abilityRank": 4,
  "timeKeepingRank": 5,
  "referenceSentDate": "2026-01-06",
  "referenceOutcome": "Received 14 January 2026, satisfactory"
}

400

Section titled “400”

Bad Request

Media typeapplication/problem+json
object
type
string
nullable
title
string
nullable
status
integer format: int32
nullable
detail
string
nullable
instance
string
nullable
Examplegenerated
{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example"
}

401

Section titled “401”

Unauthorized

Media typeapplication/problem+json
object
type
string
nullable
title
string
nullable
status
integer format: int32
nullable
detail
string
nullable
instance
string
nullable
Examplegenerated
{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example"
}

403

Section titled “403”

Forbidden

Media typeapplication/problem+json
object
type
string
nullable
title
string
nullable
status
integer format: int32
nullable
detail
string
nullable
instance
string
nullable
Examplegenerated
{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example"
}

404

Section titled “404”

Not Found

Media typeapplication/problem+json
object
type
string
nullable
title
string
nullable
status
integer format: int32
nullable
detail
string
nullable
instance
string
nullable
Examplegenerated
{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example"
}