Create InProgress worker    

Create In-Progress worker API allows your application to add new worker records to a company with a temporary IN_PROGRESS status. These records appear in Paychex Flex with minimal required data (such as givenName, familyName, and workerType) and must be completed by a Flex user before becoming fully active. When multiple workers are created, each entry must include a unique workerCorrelationId, and a new workerId is returned on successful creation. In-Progress workers are pre-populated in Paychex Flex and must be completed by a Flex user before becoming fully active on the platform.

Use the POST /companies/{companyId}/workers endpoint to begin creating a worker record. Grab the companyId from Companies API Response. Below is the cURL example for the POST Workers endpoint:

curl --location 'https://api.paychex.com/companies/<companyId>/workers' \
--header 'Authorization: Bearer <your_bearerToken_here>' \
--header 'Accept: application/vnd.paychex.workers.v1+json' \
--header 'Content-Type: application/json' \

--data '[{

"employmentType":"FULL_TIME",
"workerCorrelationId":"1",
"employeeId": "123",
"workerType":"EMPLOYEE",
"ethnicityCode":"HISPANIC_OR_LATINO",
"birthDate": "1987-06-22T11:36:39Z",
"legalId": {
"legalIdType": "SSN",
"legalIdValue": "000000000"
},
"name": {
"familyName":"InProgress-Test-Worker",
"middleName": "D",
"givenName": "DK"
},

"currentStatus": {
"statusType": "IN_PROGRESS",
"statusReason": "PENDING_HIRE",
"effectiveDate": "2020-04-25T00:00:00Z"
}}
]'

 Sample Response

  {
    "content": [
        {
            "workerId": "00KRLXGAMKAYL3CESR2C",
            "employeeId": "123",
            "workerType": "EMPLOYEE",
            "employmentType": "FULL_TIME",
            "birthDate": "1987-06-22T00:00:00Z",
            "sex": "NOT_SPECIFIED",
            "ethnicityCode": "HISPANIC_OR_LATINO",
            "name": {
                "familyName": "InProgress-Test-Worker",
                "middleName": "D",
                "givenName": "DK"
            },
            "legalId": {
                "legalIdType": "SSN",
                "legalIdValue": "000000000"
            },
            "currentStatus": {
                "workerStatusId": "00KRLXGAMKAYL3CESR2B",
                "statusType": "IN_PROGRESS",
                "statusReason": "PENDING_HIRE",
                "statusDate": "2026-01-12T00:00:00Z"
            },
            "workerCorrelationId": "0",
            "links": [
                {
                    "rel": "self",
                    "href": "https://api.paychex.com/workers/00KRLXGAMKAYL3CESR2C"
                },
                {
                    "rel": "communications",
                    "href": "https://api.paychex.com/workers/00KRLXGAMKAYL3CESR2C/communications"
                }
            ]
        }
    ],
    "links": []
}

Error to Be Aware Of: 423 Error Response

A 423 error occurs when you try to create an In-Progress Worker (IPW) while the client’s Paychex account is locked. In this case, the request may partially succeed, and a workerId may still be generated—however, this workerId is invalid and should not be used.

Action Required

If you receive a 423 status with a workerId:
•    Do not use that workerId.
•    Remove it from your system.
•    Retry the request after the client account is unlocked.
•    Only use workerIds returned from a successful (200) response.

PATCH InProgress worker

PATCH Worker API lets you update a unique worker (employee and contractor) that your application has been granted access to modify. Grab the "workerId" you wish to modify and Use the cURL below to modify the allowed fields of a worker.

curl --location --request PATCH 'https://api.paychex.com/workers/<workerId>' \
--header 'Authorization: Bearer <your_bearerToken>' \
--header 'Content-Type: application/json' \
--data '{
  "employeeId": "10",
  "employmentType": "PART_TIME",
  "birthDate": "1987-06-22T11:36:39Z",
  "sex": "MALE",
  "clockId": "2",
  "name": {
    "familyName": "john",
    "middleName": "A",
    "givenName": "Joe",
    "preferredName": "john",
    "preferredLastName": "joe",
    "qualificationAffixCode": "Dr",
    "titleAffixCode": "III",
    "pronoun": "He/him/his"
  }
}'

Sample Response

{
    "content": [
        {
            "workerId": "00KRLXGAMKAYL3CESR2C",
            "employeeId": "10",
            "workerType": "EMPLOYEE",
            "employmentType": "PART_TIME",
            "birthDate": "1987-06-22T00:00:00Z",
            "sex": "MALE",
            "ethnicityCode": "HISPANIC_OR_LATINO",
            "clockId": "2",
            "name": {
                "familyName": "john",
                "middleName": "A",
                "givenName": "Joe",
                "preferredName": "john",
                "preferredLastName": "joe",
                "pronoun": "He/him/his",
                "qualificationAffixCode": "Dr",
                "titleAffixCode": "III"
            },
            "legalId": {
                "legalIdType": "SSN",
                "legalIdValue": "000000000"
            },
            "currentStatus": {
                "workerStatusId": "00ZAJSWSJ0DYTECE004S",
                "statusType": "IN_PROGRESS",
                "statusReason": "PENDING_HIRE",
                "effectiveDate": "2026-01-12T00:00:00Z"
            },
            "links": [
                {
                    "rel": "self",
                    "href": "https://api.paychex.com/workers/00KRLXGAMKAYL3CESR2C"
                },
                {
                    "rel": "communications",
                    "href": "https://api.paychex.com/workers/00KRLXGAMKAYL3CESR2C/communications"
                }
            ]
        }
    ],
    "links": []
}