Adding Workers to a Company in Flex

You can easily add one or more workers to a company that your application has access to through Flex. Initially, these workers will receive an "IN_PROGRESS" status and must be fully configured within the Flex system.

Required Fields:

• Given Name: The first name of the worker.
• Family Name: The last name of the worker.
• Worker Type: Select from the following enumerations:
  • 'EMPLOYEE': Represents a W2 type worker.
  • 'INDEPENDENT_CONTRACTOR': Represents a 1099 type worker.

Notes:

• It is not possible to create 'CONTRACTOR' types as these are considered company contractors, distinct from individual workers in our system.
• Similarly, adding a 'USER'—which differs from a worker in our systems—is also not possible outside of Paychex Flex.
• When adding multiple workers simultaneously, be sure to include a "workerCorrelationId" for each worker. This identifier will be used in our responses.

Upon successfully adding a new in-progress worker, the response will include a new workerId. You can use this ID in future updates to modify existing worker properties, such as federal taxes, or to add more details to the worker's communications, direct deposit, compensation, and state taxes.

For more detailed guidance on managing workers, such as sending an invitation for workers to add their personal information in Flex, visit the Worker page in Developer Resources.

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": []
}