Update Worker

PATCH/workers/{id}

Agency-scoped keys

This endpoint is only available for agency-scoped API keys.

Caller

This endpoint requires an agency-scoped API key with the write:workers scope. The worker must already be represented by the selected agency.

If the key is scoped to multiple agencies, pass the agency ObjectId in the agency query parameter.

Summary

Updates the supplied worker fields. Identity values and the agency's own agencyId must remain unique. A conflicting National Insurance number, passport number, email address, or agency ID returns 409 CONFLICT.

URL Parameters

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

Query Parameters

Name	Type	Required	Description
agency	string	Conditional	Agency ObjectId; required when the API key includes multiple agencies

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.

Each new file requires its fileName and complete base64 data URL in content. PDF, JPEG, and PNG files are supported, with a maximum decoded size of 20 MB per file and a 50 MB limit for the complete JSON request.

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.

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 fileName string, required - Original file name, including its extension content string, required - Complete PDF, JPEG, or PNG base64 data URL 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.

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": [
          {
            "fileName": "cscs.pdf",
            "content": "data:application/pdf;base64,<BASE64_FILE_CONTENT>"
          }
        ]
      }
    ]
  }'

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: [
          {
            fileName: "cscs.pdf",
            content: "data:application/pdf;base64,<BASE64_FILE_CONTENT>",
          },
        ],
      },
    ],
  }),
});

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': [
                    {
                        'fileName': 'cscs.pdf',
                        'content': 'data:application/pdf;base64,<BASE64_FILE_CONTENT>',
                    },
                ],
            },
        ],
    },
    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":[{"fileName":"cscs.pdf","content":"data:application/pdf;base64,<BASE64_FILE_CONTENT>"}]}]}`)
  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

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)

{
  "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"
  }
}

Errors

HTTP Status	Description
400	Invalid worker/document data or a locked document update
401	Missing, invalid, revoked, or expired API key
403	Key is not agency-scoped or does not have write:workers
404	Worker is not available to the selected agency
409	Worker identity or agency reference conflicts
413	Request exceeds the 50 MB JSON body limit
429	Rate limit exceeded
500	Unexpected internal or storage error