Skip to main content

List Workers

GET/workers

Access​

RequirementValue
Scoperead:workers
Company-scoped keysSupported
Agency-scoped keysSupported within agency access

Company-scoped API keys can filter workers by company and optionally include document validation rows.

Summary​

Returns a paginated list of workers available to the API key, with company, search, creation date, document expiry, field selection, and sorting controls.

Query Parameters​

NameTypeRequiredDescription
companystringNoFilter by company id(s). Pass a single id or comma-separated ids. If omitted, workers for all companies linked to the API key are returned.
pageintegerNoPage number (default 1)
limitintegerNoRecords per page (default 50, max 200)
querystringNoCase-insensitive search against worker name, reference, and email
includeDocumentValidationsbooleanNoIf true, include validation records for each document in attachments and rightToWork. Non-system validations are limited to companies linked to the API key.
expiringAfterstringNoReturn workers with at least one attachments or rightToWork document expiring on or after this date (YYYY-MM-DD)
expiringBeforestringNoReturn workers with at least one attachments or rightToWork document expiring on or before this date (YYYY-MM-DD)
fromstringNoCreated date filter start (YYYY-MM-DD)
tostringNoCreated date filter end (YYYY-MM-DD)
sortByenum(createdAt, updatedAt, name, firstName, lastName, ref)NoSort field
sortOrderenum(asc, desc)NoSort direction
fieldsstringNoComma-separated list of response fields or dot-path nested fields to return

from, to, expiringAfter and expiringBefore must be real calendar dates in YYYY-MM-DD format. Impossible dates such as 2026-02-30 return 400 BAD_REQUEST; leap days are accepted only in leap years. This applies to company and agency keys.

Request Example​

curl -X GET 'https://api.requidex.com/api/open/v1/workers?includeDocumentValidations=true' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Accept: application/json'

The saved rightToWork[].rightToWorkCheck is available to company and agency callers for documents they can view. It reports the retained result, not a fresh check or a guarantee of current permission. Term-date evidence is returned in rightToWork[].files with docType: "Term dates". Check metadata cannot be supplied or changed through worker create/update requests.

Saved SIA verification is returned under attachments[].siaCheck for company and agency callers who can view the document. It includes the retained register details and screengrab link; it does not run a new check. Documents saved without a completed SIA check omit this field. SIA check metadata is read-only and cannot be supplied through worker create/update requests.

Right-to-work evidence is shared on the worker record. Agency-scoped keys can read that evidence regardless of which agency uploaded it. Supplier metadata does not restrict RTW visibility.

Response Fields​

FieldTypeDescription
addressobject
Show child attributes
  • lineOne string - Address line one
  • lineTwo string - Address line two
  • city string - City
  • region string - Region
  • country string - Country
  • code string - Postal code
  • latitude number - Latitude
  • longitude number - Longitude
  • formattedAddress string - Full formatted address
agenciesarray[object]
Show child attributes
  • id string - Agency id
  • name string - Agency name
  • agencyId string - Agency-specific worker identifier
  • active boolean - Whether the worker is active for this agency link
attachmentsarray[object]
Show child attributes
  • id string - Worker document id
  • type string - Document collection name
  • documentType string - Document type label
  • documentNumber string - Document number
  • expiration string - Expiration timestamp, when present
  • indefinite boolean - Whether the document has no expiry date
  • createdAt string - Timestamp when the document was added
  • files array[object] -
    Show child attributes
    • fileName string - Document file name
    • url string - Public file URL
    • docType string - File role within the document set
  • siaCheck object - Saved SIA licence verification when available.
    Show child attributes
    • outcome string - Saved check outcome: VALID, INVALID, MANUAL_REVIEW or NOT_FOUND
    • verified boolean - Whether the saved check verified the licence
    • licenceNumber string - Licence number checked
    • checkedAt string - Check timestamp
    • source string - Register source URL
    • expiryDate string - Licence expiry in YYYY-MM-DD format, or null
    • reasons array[string] - Reasons recorded by the check
    • licence object - Register details when found.
      Show child attributes
      • firstName string - First name
      • surname string - Surname
      • licenceNumber string - Licence number
      • status string - Licence status
      • role string - Licence role
      • sector string - Licence sector
      • expiryDate string - Expiry date as displayed by the register
      • statusExplanation string - Register status explanation
      • conditions string - Additional conditions
    • evidence object - Saved register screengrab when available.
      Show child attributes
      • fileName string - Evidence file name
      • url string - Evidence URL
      • docType string - SIA register evidence
  • verification object - CSCS Smart Check verification details when available.
    Show child attributes
    • verified boolean - Whether the document passed CSCS Smart Check
    • cardTypeName string - Verified card type name
    • serial string - Card serial number
    • customerName string - Cardholder name returned by Smart Check
    • documentNumber string - Verified card number
    • photoType string - Cardholder photo content type
    • expiry string - Verified expiry value
    • occupationQualifications array[object] - Occupation qualifications returned by Smart Check (qual)
    • lastVerifiedAt string - Timestamp of the latest Smart Check result
  • systemValidation object - Automated document validation result, when available.
    Show child attributes
    • status string - System validation status
    • checkedAt string - Timestamp of the system validation result
    • documentType string - Document type evaluated by the system validator
    • reason string - System validation failure reason, when present
  • validations array[object] - Returned only when includeDocumentValidations=true. Non-system rows are limited to companies linked to the API key.
    Show child attributes
    • id string - Validation id
    • company object - Hiring company the decision belongs to. Use its id to select the company you are reporting on.
      Show child attributes
      • id string - Company id
      • name string - Company name
    • competency object -
      Show child attributes
      • id string - Competency id
      • name string - Competency name
    • user object -
      Show child attributes
      • id string - User id
      • name string - User name
    • validationType string - Validation source type
    • status string - Current decision: validated, referred or invalid. Older records with a named validator return validated even if no status was originally saved. If omitted, the validation is unconfirmed
    • invalidReason string - Invalidation reason code, when present
    • invalidReasonText string - Additional invalidation notes, when present
    • resolvedAt string - Timestamp when the validation was resolved, when present
    • documentType string - Document type recorded on the validation row, when present
    • documentRef string - Candidate document id referenced by the validation, when present
    • statusHistory array[object] - Recorded status changes. Older records may have an empty history; read status for the current decision.
      Show child attributes
      • status string - Validation status recorded for the history entry
      • invalidReason string - Invalidation reason code, when present
      • invalidReasonText string - Additional invalidation notes, when present
      • changedAt string - Timestamp when the history entry was recorded
      • changedBy object - User reference for the change (id, name)
    • createdAt string - Validation creation timestamp
    • updatedAt string - Validation update timestamp
companyIdsarray[object]Optional worker identifiers assigned by hiring companies. May be empty.
Show child attributes
  • company string - Company ID accessible to the API key
  • id string - Worker ID assigned by that company
createdAtstringCreation timestamp in ISO 8601 date-time format
dobstringDate of birth in ISO 8601 date-time format
emailstringWorker email
firstNamestringWorker first name
genderstringWorker gender
idstringWorker id
lastNamestringWorker last name
namestringWorker full name
nationalitystringNationality
phoneobject
Show child attributes
  • countryCode string - Country dialing code
  • number string - Phone number
referencestringWorker reference
rightToWorkarray[object]
Show child attributes
  • id string - Worker document id
  • type string - Document collection name
  • documentType string - Document type label
  • documentNumber string - Document number
  • expiration string - Expiration timestamp, when present
  • indefinite boolean - Whether the document has no expiry date
  • createdAt string - Timestamp when the document was added
  • files array[object] -
    Show child attributes
    • fileName string - Document file name
    • url string - Public file URL
    • docType string - File role within the document set
  • rightToWorkCheck object - Read-only saved Home Office verification, omitted when no check is saved.
    Show child attributes
    • outcome string - Stored Home Office outcome: ACCEPTED, REFUSED or UNKNOWN
    • name string - Name returned by the Home Office
    • checkDate string - Home Office check date, for example 9 October 2026
    • checkedAt string - Timestamp recorded when the check completed
    • referenceNumber string - Home Office check reference
    • startDate string - Permission start date in YYYY-MM-DD format
    • expiryDate string - Permission expiry date in YYYY-MM-DD format; not share-code expiry
    • summary string - Home Office permission summary
    • indefinite boolean - Whether the check explicitly confirms indefinite permission
    • studentRestricted boolean - Whether student restrictions were detected
    • termTimeHours number - Weekly term-time hours limit, or null when not stated
    • details array[string] - Additional Home Office details
    • conditions array[string] - Home Office work conditions
    • restrictions array[string] - Home Office work restrictions
    • evidence object - Saved Home Office PDF, when available.
      Show child attributes
      • fileName string - File name
      • url string - File URL
      • docType string - Home Office check
  • systemValidation object - Automated document validation result, when available.
    Show child attributes
    • status string - System validation status
    • checkedAt string - Timestamp of the system validation result
    • documentType string - Document type evaluated by the system validator
    • reason string - System validation failure reason, when present
  • validations array[object] - Returned only when includeDocumentValidations=true. Non-system rows are limited to companies linked to the API key.
    Show child attributes
    • id string - Validation id
    • company object - Hiring company the decision belongs to. Use its id to select the company you are reporting on.
      Show child attributes
      • id string - Company id
      • name string - Company name
    • competency object -
      Show child attributes
      • id string - Competency id
      • name string - Competency name
    • user object -
      Show child attributes
      • id string - User id
      • name string - User name
    • validationType string - Validation source type
    • status string - Current decision: validated, referred or invalid. Older records with a named validator return validated even if no status was originally saved. If omitted, the validation is unconfirmed
    • invalidReason string - Invalidation reason code, when present
    • invalidReasonText string - Additional invalidation notes, when present
    • resolvedAt string - Timestamp when the validation was resolved, when present
    • documentType string - Document type recorded on the validation row, when present
    • documentRef string - Candidate document id referenced by the validation, when present
    • statusHistory array[object] - Recorded status changes. Older records may have an empty history; read status for the current decision.
      Show child attributes
      • status string - Validation status recorded for the history entry
      • invalidReason string - Invalidation reason code, when present
      • invalidReasonText string - Additional invalidation notes, when present
      • changedAt string - Timestamp when the history entry was recorded
      • changedBy object - User reference for the change (id, name)
    • createdAt string - Validation creation timestamp
    • updatedAt string - Validation update timestamp
tradesarray[object]
Show child attributes
  • id string - Trade id
  • name string - Trade name
updatedAtstringLast update timestamp in ISO 8601 date-time format

Response Example (200)​

{
  "success": true,
  "data": [
    {
      "id": "67bc36db80a1616ec3f48999",
      "reference": "WK-1001",
      "companyIds": [{ "company": "67bc36db80a1616ec3f47001", "id": "BUILD-1001" }],
      "firstName": "Jordan",
      "lastName": "Smith",
      "name": "Jordan Smith",
      "gender": "male",
      "nationality": "British",
      "dob": "1990-01-01T00:00:00.000Z",
      "phone": {
        "countryCode": "+44",
        "number": "1234567890"
      },
      "email": "jordan@example.com",
      "address": {
        "lineOne": "1 Main Street",
        "city": "Manchester",
        "country": "United Kingdom",
        "code": "M1 1AA"
      },
      "agencies": [
        {
          "id": "67bc36db80a1616ec3f47101",
          "name": "Northline Labour Desk",
          "agencyId": "AG-1001",
          "active": true
        }
      ],
      "trades": [
        {
          "id": "67bc36db80a1616ec3f47102",
          "name": "Electrician"
        }
      ],
      "attachments": [
        {
          "id": "67bc36db80a1616ec3f48a10",
          "type": "attachment",
          "documentType": "CSCS Card",
          "documentNumber": "CSCS-123",
          "expiration": "2027-01-01T00:00:00.000Z",
          "indefinite": false,
          "createdAt": "2026-02-01T09:00:00.000Z",
          "files": [
            {
              "fileName": "cscs-front.jpg",
              "url": "https://files.requidex.com/cscs-front.jpg",
              "docType": "Front"
            }
          ],
          "verification": {
            "verified": true,
            "cardTypeName": "Gold Skilled Worker",
            "serial": "CSCS-SERIAL-1",
            "customerName": "Jordan Smith",
            "documentNumber": "CSCS-123",
            "photoType": "image/jpeg",
            "expiry": "2027-01-01",
            "occupationQualifications": [
              {
                "qual": "Electrician"
              }
            ],
            "lastVerifiedAt": "2026-02-02T12:00:00.000Z"
          },
          "systemValidation": {
            "status": "validated",
            "checkedAt": "2026-02-02T12:00:00.000Z",
            "documentType": "CSCS Card",
            "reason": null
          },
          "validations": [
            {
              "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-02-05T12:00:00.000Z",
              "documentType": "attachment",
              "documentRef": "67bc36db80a1616ec3f48a10",
              "statusHistory": [
                {
                  "status": "validated",
                  "changedAt": "2026-02-05T12:00:00.000Z",
                  "changedBy": {
                    "id": "67bc36db80a1616ec3f49998",
                    "name": "Alex Carter"
                  }
                }
              ],
              "createdAt": "2026-02-05T12:00:00.000Z",
              "updatedAt": "2026-02-05T12:00:00.000Z"
            }
          ]
        }
      ],
      "rightToWork": [
        {
          "id": "67bc36db80a1616ec3f48a11",
          "type": "rightToWork",
          "documentType": "Passport",
          "documentNumber": "P1234567",
          "expiration": "2028-01-01T00:00:00.000Z",
          "indefinite": false,
          "createdAt": "2026-02-03T09:00:00.000Z",
          "files": [
            {
              "fileName": "passport-front.jpg",
              "url": "https://files.requidex.com/passport-front.jpg",
              "docType": "Front"
            }
          ],
          "systemValidation": {
            "status": "validated",
            "checkedAt": "2026-02-04T12:00:00.000Z",
            "documentType": "Passport",
            "reason": null
          },
          "validations": [
            {
              "id": "67bc36db80a1616ec3f48b02",
              "company": {
                "id": "67bc36db80a1616ec3f47001",
                "name": "Requidex Construction Ltd"
              },
              "competency": null,
              "user": {
                "id": "67bc36db80a1616ec3f49997",
                "name": "Pat Taylor"
              },
              "validationType": "manual",
              "status": "validated",
              "resolvedAt": "2026-02-06T12:00:00.000Z",
              "documentType": "rightToWork",
              "documentRef": "67bc36db80a1616ec3f48a11",
              "statusHistory": [],
              "createdAt": "2026-02-06T12:00:00.000Z",
              "updatedAt": "2026-02-06T12:00:00.000Z"
            }
          ]
        }
      ],
      "createdAt": "2026-01-15T10:00:00.000Z",
      "updatedAt": "2026-02-10T14:00:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 1
  }
}

MCP Tool​

The MCP server exposes this operation as open_api_list_workers with the inputs company, page, limit, query, includeDocumentValidations, expiringAfter, expiringBefore, from, to, sortBy, sortOrder, and fields.

Errors​

HTTP StatusDescription
400Invalid query parameter
401Missing, invalid, revoked, or expired API key
404Company not found
405Method not allowed on Open API routes
429Rate limit exceeded
500Unexpected internal error