Create Worker

POST/workers

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.

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

Summary

Creates a worker only when Requidex finds no matching worker record. The request uses the same identity matching rules as the portal, including exact National Insurance or passport matches and the existing multi-field match score.

If any worker matches, the endpoint returns 409 WORKER_MATCH_REQUIRES_REVIEW. The worker must then be reviewed and assigned to the agency in the Requidex portal. The API does not expose matching worker details or choose a match automatically.

Query Parameters

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

Request

Attachments and right-to-work evidence can be included in this request. Document IDs come from List Master Qualifications. Add right-to-work qualifications to rightToWork and other supported worker documents to attachments.

Use the qualification's documentCollection, expiry settings, and minimum upload count when constructing a document. An agencySpecific attachment, such as a CV, is stored for the selected agency rather than shared with other agencies representing the worker.

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 uses the expiry returned by Smart Check.

Each file requires its fileName and its complete content as a base64 data URL, such as data:image/jpeg;base64,.... 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.

Request Fields

Field	Type	Required	Description
firstName	string	Yes	Worker first name
lastName	string	Yes	Worker last name
dob	string	Yes	Date of birth in YYYY-MM-DD format
email	string	Yes	Valid worker email address
phone	string	Yes	Worker phone number
countryCode	string	Yes	Exact value from Telephone Country Codes, including the leading +
gender	enum	Yes	Exact value from Genders
nationality	string	Yes	Exact value from Countries
nationalIns	string	Conditional	UK National Insurance number or Irish PPS number, according to the nationality rules below
passportNo	string	Conditional	Passport number or share code when required by the nationality rules below
address	object	Yes	Worker home 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]	Yes	One or more IDs returned by List Master Trades
agencyId	string	Yes	Agency's unique identifier for the worker
consent	boolean	Yes	Must be true to confirm the agency has the worker's written consent
attachments	array[object]	No	Non-right-to-work documents to add. Show child attributes documentId string, required - Master qualification ID documentNumber string, required - Document number 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, required - 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. Uses the same child attributes as attachments.

Request Example

cURL

curl -X POST 'https://api.requidex.com/api/open/v1/workers' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  --data '{
    "firstName": "Jordan",
    "lastName": "Smith",
    "dob": "1990-01-01",
    "email": "jordan.smith@example.com",
    "phone": "07123456789",
    "countryCode": "+44",
    "gender": "Male",
    "nationality": "United Kingdom",
    "nationalIns": "AB123456C",
    "address": {
      "lineOne": "1 Main Street",
      "city": "Manchester",
      "country": "United Kingdom",
      "code": "M1 1AA"
    },
    "trades": ["67bc36db80a1616ec3f47102"],
    "rightToWork": [
      {
        "documentId": "67bc36db80a1616ec3f47103",
        "documentNumber": "P1234567",
        "expiration": "2030-01-01",
        "files": [
          {
            "fileName": "passport-front.jpg",
            "content": "data:image/jpeg;base64,<BASE64_FILE_CONTENT>",
            "docType": "Front"
          }
        ]
      }
    ],
    "agencyId": "AG-1001",
    "consent": true
  }'

JavaScript

const response = await fetch("https://api.requidex.com/api/open/v1/workers", {
  method: "POST",
  headers: {
    Authorization: "Bearer <API_KEY>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    firstName: "Jordan",
    lastName: "Smith",
    dob: "1990-01-01",
    email: "jordan.smith@example.com",
    phone: "07123456789",
    countryCode: "+44",
    gender: "Male",
    nationality: "United Kingdom",
    nationalIns: "AB123456C",
    address: {
      lineOne: "1 Main Street",
      city: "Manchester",
      country: "United Kingdom",
      code: "M1 1AA",
    },
    trades: ["67bc36db80a1616ec3f47102"],
    rightToWork: [
      {
        documentId: "67bc36db80a1616ec3f47103",
        documentNumber: "P1234567",
        expiration: "2030-01-01",
        files: [
          {
            fileName: "passport-front.jpg",
            content: "data:image/jpeg;base64,<BASE64_FILE_CONTENT>",
            docType: "Front",
          },
        ],
      },
    ],
    agencyId: "AG-1001",
    consent: true,
  }),
});

const json = await response.json();

Python

import requests

response = requests.post(
    'https://api.requidex.com/api/open/v1/workers',
    headers={'Authorization': 'Bearer <API_KEY>'},
    json={
        'firstName': 'Jordan',
        'lastName': 'Smith',
        'dob': '1990-01-01',
        'email': 'jordan.smith@example.com',
        'phone': '07123456789',
        'countryCode': '+44',
        'gender': 'Male',
        'nationality': 'United Kingdom',
        'nationalIns': 'AB123456C',
        'address': {
            'lineOne': '1 Main Street',
            'city': 'Manchester',
            'country': 'United Kingdom',
            'code': 'M1 1AA',
        },
        'trades': ['67bc36db80a1616ec3f47102'],
        'rightToWork': [
            {
                'documentId': '67bc36db80a1616ec3f47103',
                'documentNumber': 'P1234567',
                'expiration': '2030-01-01',
                'files': [
                    {
                        'fileName': 'passport-front.jpg',
                        'content': 'data:image/jpeg;base64,<BASE64_FILE_CONTENT>',
                        'docType': 'Front',
                    },
                ],
            },
        ],
        'agencyId': 'AG-1001',
        'consent': True,
    },
    timeout=30,
)

print(response.json())

Go

package main

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

func main() {
  body := []byte(`{"firstName":"Jordan","lastName":"Smith","dob":"1990-01-01","email":"jordan.smith@example.com","phone":"07123456789","countryCode":"+44","gender":"Male","nationality":"United Kingdom","nationalIns":"AB123456C","address":{"lineOne":"1 Main Street","city":"Manchester","country":"United Kingdom","code":"M1 1AA"},"trades":["67bc36db80a1616ec3f47102"],"rightToWork":[{"documentId":"67bc36db80a1616ec3f47103","documentNumber":"P1234567","expiration":"2030-01-01","files":[{"fileName":"passport-front.jpg","content":"data:image/jpeg;base64,<BASE64_FILE_CONTENT>","docType":"Front"}]}],"agencyId":"AG-1001","consent":true}`)
  req, _ := http.NewRequest("POST", "https://api.requidex.com/api/open/v1/workers", 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))
}

For United Kingdom workers, nationalIns is required and must be a valid UK National Insurance number. For Irish workers, nationalIns must contain either a valid UK National Insurance number or Irish PPS number. For other nationalities, provide a passport number or share code in passportNo, or a valid UK National Insurance number in nationalIns.

Response Fields

Field	Type	Description
success	boolean	Whether the request succeeded
data	object	Creation result. Show child attributes id string - Generated worker ID reference string - Generated 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 createdAt string - Worker creation timestamp

Response Example (200)

{
  "success": true,
  "data": {
    "id": "67bc36db80a1616ec3f48999",
    "reference": "W1001",
    "attachments": [],
    "rightToWork": [
      {
        "id": "67bc36db80a1616ec3f48a10",
        "type": "rightToWork",
        "documentType": "Passport",
        "documentNumber": "P1234567",
        "expiration": "2030-01-01T00:00:00.000Z",
        "indefinite": false,
        "createdAt": "2026-09-03T10:15:00.000Z",
        "files": [
          {
            "fileName": "passport-front.jpg",
            "url": "https://files.requidex.com/worker-documents/example/passport-front.jpg",
            "docType": "Front"
          }
        ]
      }
    ],
    "createdAt": "2026-09-03T10:15:00.000Z"
  }
}

Match Review Response (409)

{
  "success": false,
  "error": {
    "code": "WORKER_MATCH_REQUIRES_REVIEW",
    "message": "A matching worker already exists. Create or assign this worker through the Requidex portal"
  }
}

Errors

HTTP Status	Description
400	Invalid worker or document data
401	Missing, invalid, revoked, or expired API key
403	Key is not agency-scoped or does not have write:workers
409	Worker match or conflicting worker data requires intervention
413	Request exceeds the 50 MB JSON body limit
429	Rate limit exceeded
500	Unexpected internal or storage error