Validate Worker Document

POST/workers/{workerId}/documents/{documentId}/validate

Agency-scoped keys

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

Caller

This endpoint requires a company-scoped API key with the write:workers scope.

Summary

Records a manual validated status for a worker attachment or right-to-work document. The validation is owned by the selected company and records the validating user or API-key owner in its history.

Calling the endpoint for an existing manual validation updates it to validated and appends a status-history entry.

URL Parameters

Name	Type	Required	Description
workerId	string	Yes	Worker ObjectId or internal nanoid
documentId	string	Yes	Attachment or right-to-work document ObjectId

Query Parameters

Name	Type	Required	Description
company	string	Yes	Company ObjectId that owns the validation; it must be linked to key

Request Example

cURL

curl -X POST 'https://api.requidex.com/api/open/v1/workers/{workerId}/documents/{documentId}/validate?company={companyId}' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Accept: application/json'

JavaScript

const response = await fetch(
  "https://api.requidex.com/api/open/v1/workers/{workerId}/documents/{documentId}/validate?company={companyId}",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer <API_KEY>",
      Accept: "application/json",
    },
  },
);

const json = await response.json();

Python

import requests

response = requests.post(
    'https://api.requidex.com/api/open/v1/workers/{workerId}/documents/{documentId}/validate',
    params={'company': '{companyId}'},
    headers={
        'Authorization': 'Bearer <API_KEY>',
        'Accept': 'application/json',
    },
    timeout=30,
)

print(response.json())

Response Fields

Field	Type	Description
success	boolean	Whether the request succeeded
data.id	string	Validation id
data.company	object	Company that owns the manual validation
data.competency	object / null	Related competency, when present
data.user	object / null	User or API-key owner attributed to the action
data.validationType	string	manual
data.status	string	validated
data.resolvedAt	string	Validation timestamp
data.documentType	string	attachment or rightToWork
data.documentRef	string	Validated worker document id
data.statusHistory	array	Validation status history
data.statusHistory[].status	string	Status recorded for the history entry
data.statusHistory[].changedAt	string	Timestamp of the history entry
data.statusHistory[].changedBy	object	User reference attributed to the history entry
data.createdAt	string	Validation creation timestamp
data.updatedAt	string	Validation update timestamp

Response Example (200)

{
  "success": true,
  "data": {
    "id": "67bc36db80a1616ec3f48b01",
    "company": {
      "id": "67bc36db80a1616ec3f47001",
      "name": "Requidex Construction Ltd"
    },
    "competency": {
      "id": "67bc36db80a1616ec3f47234",
      "name": "CSCS"
    },
    "user": {
      "id": "67bc36db80a1616ec3f49998",
      "name": "Alex Carter"
    },
    "validationType": "manual",
    "status": "validated",
    "resolvedAt": "2026-08-21T09:00:00.000Z",
    "documentType": "attachment",
    "documentRef": "67bc36db80a1616ec3f48a10",
    "statusHistory": [
      {
        "status": "validated",
        "changedAt": "2026-08-21T09:00:00.000Z",
        "changedBy": {
          "id": "67bc36db80a1616ec3f49998",
          "name": "Alex Carter"
        }
      }
    ],
    "createdAt": "2026-08-21T09:00:00.000Z",
    "updatedAt": "2026-08-21T09:00:00.000Z"
  },
  "meta": {}
}

MCP Tool

The MCP server exposes this operation as open_api_validate_worker_document with the inputs workerId, documentId, and company.

Errors

HTTP Status	Description
400	Missing identifiers or the request does not select exactly one company
401	Missing, invalid, revoked, or expired API key
403	Missing write:workers scope or agency-scoped access
404	Worker or worker document not found
429	Rate limit exceeded
500	Unexpected internal error