Update Worker

PATCH/workers/{id}

Caller

This endpoint requires the write:workers scope. Company-scoped keys can update only the company worker ID for a worker linked to a company on the key. Agency-scoped keys can update workers represented by the selected agency.

For keys scoped to multiple companies or agencies, select the company or agency in the corresponding query parameter.

Summary

Company-scoped keys update only their own workerId, which must be unique within the company. Agency-scoped keys can update the supported worker fields. Conflicting identity values, agency IDs, or company worker IDs return 409 CONFLICT.

URL Parameters

Name	Type	Required	Description
id	string	Yes	Worker ObjectId or internal nanoid

Query Parameters

Name	Type	Required	Description
company	string	Conditional	Company ObjectId; required when a company-scoped key includes multiple companies
agency	string	Conditional	Agency ObjectId; required when an agency-scoped key includes multiple agencies

Company-scoped request

Send only workerId, the ID assigned to the worker by the selected company. It must be a non-empty string and unique among that company's workers. Other worker fields cannot be updated with a company-scoped key.

When the ID changes, assignments and timesheets for that worker and company are updated in the same transaction.

Field	Type	Required	Description
workerId	string	Yes	Worker ID assigned by the company

{ "workerId": "BUILD-1001" }

Agency-scoped request

All fields are optional, but the body must contain at least one supported field.

Documents without an id are added as new records. To update an existing attachment or right-to-work record, include its generated document id from a worker response and only the fields to change. If files is supplied when updating, it replaces the complete file set; omit it to retain the current files.

New Visa documents, changes to a visa's share code, and changes from another document type to Visa require a completed Home Office check saved against that worker. The latest saved check takes precedence, including a newer refusal. Complete share-code checks or request manual verification through the Requidex portal; this endpoint does not run a live check or accept client-supplied check results. Existing editable visas without a saved check can retain their current share code and document type.

Follow the upload steps in File Uploads: request a token for the worker and attachments or rightToWork purpose, upload the file using the returned link, then supply { "uploadToken": "<TOKEN>", "docType": "Front" } in the relevant files array. docType remains optional. Do not combine an upload token with fileName or content. Inline base64 files are not accepted by this endpoint.

Validated documents cannot be edited. This includes documents successfully validated by the system or a company, and documents verified through CSCS Smart Check. A document with a pending manual verification request also cannot be changed until that request is processed.

Use the qualification's documentCollection, expiry settings, and minimum upload count from List Master Qualifications. Agency-specific attachments, such as CVs, can only be updated by the agency that added them.

For CSCS Smart Check eligible documents, Requidex automatically performs Smart Check using the available configurations for companies connected to the agency. A failed check rejects the complete operation; a successful check stores the verification result and replaces the document expiry with the value returned by Smart Check.

Agency request fields

Field	Type	Required	Description
firstName	string	No	Worker first name
lastName	string	No	Worker last name
dob	string	No	Date of birth in YYYY-MM-DD format
email	string	No	Valid worker email address
phone	string	No	Worker phone number; cannot be empty
countryCode	string	No	Exact value from Telephone Country Codes, including the leading +
gender	enum	No	Exact value from Genders
nationality	string	No	Exact value from Countries
nationalIns	string	Conditional	Required when the resulting nationality and identity values require it
passportNo	string	Conditional	Passport number or share code when the resulting nationality and identity values require it
address	object	No	Replacement worker address Show child attributes lineOne string, required - First address line lineTwo string, optional - Second address line city string, optional - City or town country string, required - Exact value from Countries code string, required - Postal code
trades	array[string]	No	Replacement list of one or more IDs returned by List Master Trades
agencyId	string	No	Agency's unique identifier for the worker
active	boolean	No	Whether the worker is active for the selected agency
attachments	array[object]	No	Non-right-to-work documents to add or update. Show child attributes id string, conditional - Existing worker document ID to update; omit to add a new document documentId string, conditional - Master qualification ID; required for new documents and optional when updating documentNumber string, conditional - Required for new documents and optional when updating expiration string, conditional - Expiry date in YYYY-MM-DD format when required by the master qualification indefinite boolean, conditional - Use true when indefinite validity is supported instead of an expiry date files array, conditional - Required for new documents. For an update, replaces the complete current file set when supplied. Must meet the master qualification's minUploadRequired value Show file attributes uploadToken string, required - Token from Create File Upload docType enum - Front or Back; defaults by file order
rightToWork	array[object]	No	Right-to-work documents to add or update. Uses the same child attributes and create/update rules as attachments.

Agency request example

cURL

curl -X PATCH 'https://api.requidex.com/api/open/v1/workers/{id}' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  --data '{
    "phone": "07987654321",
    "countryCode": "+44",
    "address": {
      "lineOne": "20 New Street",
      "city": "Manchester",
      "country": "United Kingdom",
      "code": "M2 2AA"
    },
    "agencyId": "AG-1001",
    "active": true,
    "attachments": [
      {
        "id": "67bc36db80a1616ec3f48998",
        "documentId": "67bc36db80a1616ec3f47104",
        "documentNumber": "CSCS-123456",
        "files": [
          {
            "uploadToken": "<UPLOAD_TOKEN>"
          }
        ]
      }
    ]
  }'

JavaScript

const response = await fetch("https://api.requidex.com/api/open/v1/workers/{id}", {
  method: "PATCH",
  headers: {
    Authorization: "Bearer <API_KEY>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phone: "07987654321",
    countryCode: "+44",
    address: {
      lineOne: "20 New Street",
      city: "Manchester",
      country: "United Kingdom",
      code: "M2 2AA",
    },
    agencyId: "AG-1001",
    active: true,
    attachments: [
      {
        id: "67bc36db80a1616ec3f48998",
        documentId: "67bc36db80a1616ec3f47104",
        documentNumber: "CSCS-123456",
        files: [
          {
            uploadToken: "<UPLOAD_TOKEN>",
          },
        ],
      },
    ],
  }),
});

const json = await response.json();

Python

import requests

response = requests.patch(
    'https://api.requidex.com/api/open/v1/workers/{id}',
    headers={'Authorization': 'Bearer <API_KEY>'},
    json={
        'phone': '07987654321',
        'countryCode': '+44',
        'address': {
            'lineOne': '20 New Street',
            'city': 'Manchester',
            'country': 'United Kingdom',
            'code': 'M2 2AA',
        },
        'agencyId': 'AG-1001',
        'active': True,
        'attachments': [
            {
                'id': '67bc36db80a1616ec3f48998',
                'documentId': '67bc36db80a1616ec3f47104',
                'documentNumber': 'CSCS-123456',
                'files': [
                    {
                        'uploadToken': '<UPLOAD_TOKEN>',
                    },
                ],
            },
        ],
    },
    timeout=30,
)

print(response.json())

Go

package main

import (
  "bytes"
  "fmt"
  "io"
  "net/http"
)

func main() {
  body := []byte(`{"phone":"07987654321","countryCode":"+44","address":{"lineOne":"20 New Street","city":"Manchester","country":"United Kingdom","code":"M2 2AA"},"agencyId":"AG-1001","active":true,"attachments":[{"id":"67bc36db80a1616ec3f48998","documentId":"67bc36db80a1616ec3f47104","documentNumber":"CSCS-123456","files":[{"uploadToken":"<UPLOAD_TOKEN>"}]}]}`)
  req, _ := http.NewRequest("PATCH", "https://api.requidex.com/api/open/v1/workers/{id}", bytes.NewReader(body))
  req.Header.Set("Authorization", "Bearer <API_KEY>")
  req.Header.Set("Content-Type", "application/json")

  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  responseBody, _ := io.ReadAll(res.Body)
  fmt.Println(string(responseBody))
}

New documents use qualification IDs from List Master Qualifications. Sending a document array does not remove records that are not referenced in the request.

When changing nationality or identity fields, the same nationality rules as worker creation apply to the resulting worker record.

Response Fields

Company-scoped keys

Field	Type	Description
success	boolean	Whether the request succeeded
data	object	Show child attributes id string - Requidex worker ID company string - Company ID workerId string - Company worker ID updatedAt string - Last update timestamp

Agency-scoped keys

Field	Type	Description
success	boolean	Whether the request succeeded
data	object	Update result. Show child attributes id string - Worker ID reference string - Requidex worker reference attachments array[object] - Stored attachment records Show document attributes id string - Generated worker document ID type string - Document collection documentType string - Document type label documentNumber string - Document number expiration string - Expiration timestamp, including the Smart Check expiry when performed indefinite boolean - Whether the document has no expiry date createdAt string - Timestamp when the document was added files array[object] - Stored file records Show file attributes fileName string - Original file name url string - Generated file URL docType string - File role within the document set verification object / null - Generated Smart Check result Show verification attributes verified boolean cardTypeName string / null serial string / null customerName string / null documentNumber string / null photoType string / null expiry string / null occupationQualifications array[object] lastVerifiedAt string / null rightToWork array[object] - Stored right-to-work records with the same generated document and file attributes as attachments updatedAt string - Worker last update timestamp

Response Example (200)

Company-scoped keys

{
  "success": true,
  "data": {
    "id": "67bc36db80a1616ec3f48999",
    "company": "67bc36db80a1616ec3f47001",
    "workerId": "BUILD-1001",
    "updatedAt": "2026-09-03T10:20:00.000Z"
  }
}

Agency-scoped keys

{
  "success": true,
  "data": {
    "id": "67bc36db80a1616ec3f48999",
    "reference": "W1001",
    "attachments": [
      {
        "id": "67bc36db80a1616ec3f48998",
        "type": "attachment",
        "documentType": "CSCS",
        "documentNumber": "CSCS-123456",
        "expiration": "2028-06-30T00:00:00.000Z",
        "indefinite": false,
        "createdAt": "2026-08-01T09:00:00.000Z",
        "files": [
          {
            "fileName": "cscs.pdf",
            "url": "https://files.requidex.com/worker-documents/example/cscs.pdf",
            "docType": "Front"
          }
        ],
        "verification": {
          "verified": true,
          "cardTypeName": "Gold Skilled Worker",
          "serial": "CSCS-123456",
          "customerName": "Jordan Smith",
          "documentNumber": "CSCS-123456",
          "photoType": "image/jpeg",
          "expiry": "2028-06-30",
          "occupationQualifications": [{ "qual": "Electrical installation" }],
          "lastVerifiedAt": "2026-09-03T10:20:00.000Z"
        }
      }
    ],
    "rightToWork": [],
    "updatedAt": "2026-09-03T10:20:00.000Z"
  }
}

If an existing visa has a retained Home Office check, changing its share code or the worker's date of birth requires a new check in Requidex. The retained Home Office PDF is preserved. A checked student visa must retain its term and vacation dates evidence; use the Requidex document dialog to replace that evidence, as this endpoint accepts only Front and Back file roles.

Errors

HTTP Status	Description
400	Invalid worker/document data or a locked document update
401	Missing, invalid, revoked, or expired API key
403	Missing write:workers scope or required key scope
404	Selected company or worker is not accessible to the key
409	Worker identity, agency ID, or company worker ID conflicts
413	Request exceeds the 50 MB JSON body limit
429	Rate limit exceeded
500	Unexpected internal or storage error