Get all Workers of a Company
The Workers API allows your Partner App to retrieve all workers (employees) associated with a specific company your application has access to. Each worker record includes essential details such as worker identifiers, employment type, exemption type, work state, and other profile attributes
Use the GET /companies/{companyId}/workers endpoint to return the list of workers belonging to the selected company.
Grab the specific companyId from the Companies API to retrieve the Workers associated.
Below is the cURL example for the GET Workers endpoint:
curl --location 'https://api.paychex.com/companies/{companyId}/workers' \
--header 'Authorization: Bearer <Your_bearerToken_here>' \
--header 'Accept: application/json' \Sample Response
{
"metadata": {
"contentItemCount": 1
},
"content": [
{
"workerId": "00622SLMM6RL2YO3RSZV",
"employeeId": "1",
"workerType": "EMPLOYEE",
"exemptionType": "NON_EXEMPT",
"workState": "IL",
"sex": "NOT_SPECIFIED",
"hireDate": "2025-02-05T00:00:00Z",
"name": {
"familyName": "Scott",
"givenName": "Ian"
},
"organization": {
"organizationId": "970008650723146",
"name": "Company"
},
"currentStatus": {
"workerStatusId": "00DWS906IMW2JSH8AQJ9",
"statusType": "ACTIVE",
"statusReason": "HIRED",
"effectiveDate": "2025-02-05T00:00:00Z"
},
"communications": [
{
"communicationId": "00622SLMM6RL2YO3RSZY",
"type": "EMAIL",
"usageType": "BUSINESS",
"uri": "ianscott@example.com",
"links": [
{
"rel": "self",
"href": "https://api.paychex.com/workers/00622SLMM6RL2YO3RSZV/communications/00622SLMM6RL2YO3RSZY"
}
]
}
],
"links": [
{
"rel": "self",
"href": "https://api.paychex.com/workers/00622SLMM6RL2YO3RSZV"
},
{
"rel": "communications",
"href": "https://api.paychex.com/workers/00622SLMM6RL2YO3RSZV/communications"
}
]
}
],
"links": [
{
"rel": "self",
"href": "https://api.paychex.com/workers/?companyid=00622SLMM6RR507C6FW8"
}
]
Accept header:
Accept in the request header is used as a key with the Vendor Media Type as a value (also called out as ‘Content Type’ on the API documentation for each endpoint) , to allow an endpoint to have different responses based on the profile being requested.
For example, these are the Vendor Media Types or Content Types of GET Workers endpoint which filters the response as per our requirement. Click on each VMT below to know more.
Returns the full worker profile including PII (DOB, sex, ethnicity, SSN), job details, organization, supervisor, employment info, and communication links.
Sample Request
curl --location 'https://api.paychex.com/companies/<companyId>/workers?offset=1&limit=1' \
--header 'Authorization: Bearer <Your_bearerToken_here>' \
--header 'Accept: application/vnd.paychex.workers.v1+json' \Sample Response
{
"metadata": {
"contentItemCount": 1,
"pagination": {
"offset": 1,
"limit": 1,
"itemCount": 3643,
"total": 3643
}
},
"content": [
{
"workerId": "00H2A1IUKSDVPSCW1UQU",
"employeeId": "11012707",
"workerType": "EMPLOYEE",
"exemptionType": "NON_EXEMPT",
"workState": "IL",
"sex": "NOT_SPECIFIED",
"hireDate": "2021-08-01T00:00:00Z",
"name": {
"familyName": "2",
"givenName": "demoworker"
},
"laborAssignmentId": "970003437117733",
"locationId": "970003436212414",
"organization": {
"organizationId": "970003163104803",
"name": "2 South Division",
"number": "2"
},
"currentStatus": {
"workerStatusId": "00DWS906IMW2JSH8AQJ9",
"statusType": "ACTIVE",
"statusReason": "HIRED",
"effectiveDate": "2021-08-01T00:00:00Z"
},
"links": [
{
"rel": "self",
"href": "https://api.paychex.com/workers/00H2A1IUKSDVPSCW1UQU"
},
{
"rel": "communications",
"href": "https://api.paychex.com/workers/00H2A1IUKSDVPSCW1UQU/communications"
}
]
}
],
"links": [
{
"rel": "self",
"href": "https://api.paychex.com/workers/?companyid=00H2A1IUK695XL45NDO6&offset=1&limit=1"
},
{
"rel": "next",
"href": "https://api.paychex.com/workers/?companyid=00H2A1IUK695XL45NDO6&offset=2&limit=1"
},
{
"rel": "prev",
"href": "https://api.paychex.com/workers/?companyid=00H2A1IUK695XL45NDO6&offset=0&limit=1"
}
]
}Returns the full worker profile with PII plus all communication details (phone, email, address, fax, mobile, pager)
Sample Request
curl --location 'https://api.paychex.com/companies/<companyId>/workers?offset=1&limit=1' \
--header 'Authorization: Bearer <Your_bearerToken_here>' \
--header 'Accept: application/vnd.paychex.workers_communications.v1+json' \Sample Response
{
"metadata": {
"contentItemCount": 1,
"pagination": {
"offset": 1,
"limit": 1,
"itemCount": 3643,
"total": 3643
}
},
"content": [
{
"workerId": "00H2A1IUKSDVPSCW1UQU",
"employeeId": "11012707",
"workerType": "EMPLOYEE",
"exemptionType": "NON_EXEMPT",
"workState": "IL",
"sex": "NOT_SPECIFIED",
"hireDate": "2021-08-01T00:00:00Z",
"name": {
"familyName": "2",
"givenName": "demoworker"
},
"laborAssignmentId": "970003437117733",
"locationId": "970003436212414",
"organization": {
"organizationId": "970003163104803",
"name": "2 South Division",
"number": "2"
},
"currentStatus": {
"workerStatusId": "00DWS906IMW2JSH8AQJ9",
"statusType": "ACTIVE",
"statusReason": "HIRED",
"effectiveDate": "2021-08-01T00:00:00Z"
},
"links": [
{
"rel": "self",
"href": "https://api.paychex.com/workers/00H2A1IUKSDVPSCW1UQU"
},
{
"rel": "communications",
"href": "https://api.paychex.com/workers/00H2A1IUKSDVPSCW1UQU/communications"
}
]
}
],
"links": [
{
"rel": "self",
"href": "https://api.paychex.com/workers/?companyid=00H2A1IUK695XL45NDO6&offset=1&limit=1"
},
{
"rel": "next",
"href": "https://api.paychex.com/workers/?companyid=00H2A1IUK695XL45NDO6&offset=2&limit=1"
},
{
"rel": "prev",
"href": "https://api.paychex.com/workers/?companyid=00H2A1IUK695XL45NDO6&offset=0&limit=1"
}
]
}Returns a worker profile without any PII (no SSN, DOB, sex, ethnicity), but includes job, organization, employment details, supervisor, and status.
Sample Request
curl --location 'https://api.paychex.com/companies/<companyId>/workers?offset=1&limit=1' \
--header 'Authorization: Bearer <Your_bearerToken_here>' \
--header 'Accept: application/vnd.paychex.workers.nonpii.v1+json' \Sample Response
{
"metadata": {
"contentItemCount": 1,
"pagination": {
"offset": 1,
"limit": 1,
"itemCount": 3643,
"total": 3643
}
},
"content": [
{
"workerId": "00H2A1IUKSDVPSCW1UQU",
"employeeId": "11012707",
"workerType": "EMPLOYEE",
"laborAssignmentId": "970003437117733",
"locationId": "970003436212414",
"exemptionType": "NON_EXEMPT",
"hireDate": "2021-08-01T00:00:00Z",
"name": {
"familyName": "2",
"givenName": "demoworker"
},
"organization": {
"organizationId": "970003163104803",
"name": "2 South Division"
},
"currentStatus": {
"workerStatusId": "00DWS906IMW2JSH8AQJ9",
"statusType": "ACTIVE",
"statusReason": "HIRED",
"effectiveDate": "2021-08-01T00:00:00Z"
},
"links": [
{
"rel": "self",
"href": "https://api.paychex.com/workers/00H2A1IUKSDVPSCW1UQU"
},
{
"rel": "communications",
"href": "https://api.paychex.com/workers/00H2A1IUKSDVPSCW1UQU/communications"
}
]
}
],
"links": [
{
"rel": "self",
"href": "https://api.paychex.com/workers/?companyid=00H2A1IUK695XL45NDO6&offset=1&limit=1"
},
{
"rel": "next",
"href": "https://api.paychex.com/workers/?companyid=00H2A1IUK695XL45NDO6&offset=2&limit=1"
},
{
"rel": "prev",
"href": "https://api.paychex.com/workers/?companyid=00H2A1IUK695XL45NDO6&offset=0&limit=1"
}
]
}Returns a non-PII worker profile along with communication records such as address, phone, and email details.
Sample Request
curl --location 'https://api.paychex.com/companies/<companyId>/workers?offset=1&limit=1' \
--header 'Authorization: Bearer <Your_bearerToken_here>' \
--header 'Accept: application/vnd.paychex.workers.nonpii_communications.v1+json' \Sample Response
{
"metadata": {
"contentItemCount": 1,
"pagination": {
"offset": 1,
"limit": 1,
"itemCount": 3643,
"total": 3643
}
},
"content": [
{
"workerId": "00H2A1IUKSDVPSCW1UQU",
"employeeId": "11012707",
"workerType": "EMPLOYEE",
"laborAssignmentId": "970003437117733",
"locationId": "970003436212414",
"exemptionType": "NON_EXEMPT",
"hireDate": "2021-08-01T00:00:00Z",
"name": {
"familyName": "2",
"givenName": "demoworker"
},
"organization": {
"organizationId": "970003163104803",
"name": "2 South Division"
},
"currentStatus": {
"workerStatusId": "00DWS906IMW2JSH8AQJ9",
"statusType": "ACTIVE",
"statusReason": "HIRED",
"effectiveDate": "2021-08-01T00:00:00Z"
},
"links": [
{
"rel": "self",
"href": "https://api.paychex.com/workers/00H2A1IUKSDVPSCW1UQU"
},
{
"rel": "communications",
"href": "https://api.paychex.com/workers/00H2A1IUKSDVPSCW1UQU/communications"
}
]
}
],
"links": [
{
"rel": "self",
"href": "https://api.paychex.com/workers/?companyid=00H2A1IUK695XL45NDO6&offset=1&limit=1"
},
{
"rel": "next",
"href": "https://api.paychex.com/workers/?companyid=00H2A1IUK695XL45NDO6&offset=2&limit=1"
},
{
"rel": "prev",
"href": "https://api.paychex.com/workers/?companyid=00H2A1IUK695XL45NDO6&offset=0&limit=1"
}
]
} Returns a lightweight roster list with only employeeId, basic name, and limited communication details for quick worker directory views.
Sample Request
curl --location 'https://api.paychex.com/companies/<companyId>/workers?offset=1&limit=1' \
--header 'Authorization: Bearer <Your_bearerToken_here' \
--header 'Accept: application/vnd.paychex.workers.roster.v1+json' \Sample Response
{
"metadata": {
"contentItemCount": 1,
"pagination": {
"offset": 1,
"limit": 1,
"itemCount": 129,
"total": 129
}
},
"content": [
{
"employeeId": "11012707",
"name": {
"familyName": "2",
"givenName": "demoworker"
}
}
],
"links": []
}
Pagination
Many Paychex API endpoints return large datasets(companies, workers, paycomponents, etc.). To improve performance and reduce response size, these endpoints support pagination parameters. Pagination allows you to retrieve data in smaller chunks instead of receiving everything in one request.
Each paginated endpoint accepts two query parameters:
Parameter Description
offset The position to start returning records from.
limit The number of records to return in one response.
GET /workers?offset=0&limit=10
offset=0 -> start with first record
limit=10 -> returns 10 records, The above endpoint returns records 0-9.
If you do not provide pagination parameters:
• offset defaults to 0
• limit defaults based on the endpoint
Sample Paginated Request
curl --location 'https://api.paychex.com/companies/<companyId>/workers?offset=10&limit=2' \
--header 'Authorization: Bearer <Your_bearerToken_here>' \
--header 'Accept: application/vnd.paychex.workers.v1+json' \Sample Paginated Response
{
"metadata": {
"contentItemCount": 2,
"pagination": {
"offset": 10,
"limit": 2,
"itemCount": 3643,
"total": 3643
}
},
"content": [
{
"workerId": "00H2A1IUKQ9JLGTN2RM5",
"workerType": "EMPLOYEE",
"hireDate": "2018-10-30T00:00:00Z",
"name": {
"familyName": "BARRERA",
"givenName": "LEOPOLDO"
},
"currentStatus": {
"workerStatusId": "00ZAJSWSJ0DYTECE004S",
"statusType": "IN_PROGRESS",
"statusReason": "PENDING_HIRE",
"effectiveDate": "2021-06-23T00:00:00Z"
},
"links": [
{
"rel": "self",
"href": "https://api.paychex.com/workers/00H2A1IUKQ9JLGTN2RM5"
},
{
"rel": "communications",
"href": "https://api.paychex.com/workers/00H2A1IUKQ9JLGTN2RM5/communications"
}
]
},
{
"workerId": "00H2A1IUKQ9HOKMJ3714",
"workerType": "EMPLOYEE",
"hireDate": "2018-10-30T00:00:00Z",
"name": {
"familyName": "BARRERA",
"givenName": "LEOPOLDO"
},
"currentStatus": {
"workerStatusId": "00ZAJSWSJ0DYTECE004S",
"statusType": "IN_PROGRESS",
"statusReason": "PENDING_HIRE",
"effectiveDate": "2021-06-23T00:00:00Z"
},
"links": [
{
"rel": "self",
"href": "https://api.paychex.com/workers/00H2A1IUKQ9HOKMJ3714"
},
{
"rel": "communications",
"href": "https://api.paychex.com/workers/00H2A1IUKQ9HOKMJ3714/communications"
}
]
}
],
"links": [
{
"rel": "self",
"href": "https://api.paychex.com/workers/companyid=00H2A1IUK695XL45NDO6&offset=10&limit=2"
},
{
"rel": "next",
"href": "https://api.paychex.com/workers/companyid=00H2A1IUK695XL45NDO6&offset=12&limit=2"
},
{
"rel": "prev",
"href": "https://api.paychex.com/workers/?companyid=00H2A1IUK695XL45NDO6&offset=8&limit=2"
}
]
}
Field Descriptions:
Field Meaning
offset The starting index for this page of results.
limit Number of items requested.
itemCount Number of items actually returned in this response.
total Total number of items available for this endpoint.
GET Worker API provides details about an individual worker — employee or contractor — that your application has access to. Currently, only workers in Paychex Flex payroll are supported, with future enhancements planned to include workers from additional Paychex systems.
Use the below cURL to GET a worker using workerId
curl --location 'https://api.paychex.com/workers/<workerId>' \
--header 'Authorization: Bearer <Your_bearertoken_here>' \
--header 'Accept: application/vnd.paychex.worker.v1+json' \Sample Response
{
"content": [
{
"workerId": "00H2A1IUKAESBXZN4PYS",
"employeeId": "101",
"workerType": "EMPLOYEE",
"employmentType": "PART_TIME",
"exemptionType": "NON_EXEMPT",
"workState": "IL",
"birthDate": "1987-06-22T00:00:00Z",
"sex": "MALE",
"ethnicityCode": "ASIAN",
"hireDate": "2020-05-20T00:00:00Z",
"clockId": "2",
"name": {
"familyName": "john",
"middleName": "A",
"givenName": "Joe",
"preferredName": "john",
"qualificationAffixCode": "Dr",
"titleAffixCode": "III"
},
"legalId": {
"legalIdType": "SSN",
"legalIdValue": "000000000"
},
"laborAssignmentId": "970003437117733",
"locationId": "970003436212414",
"jobId": "970003585037029",
"job": {
"jobTitleId": "970003436212359",
"title": "Tester"
},
"organization": {
"organizationId": "970003163104799",
"name": "1 North Division",
"number": "1"
},
"supervisor": {
"workerId": "00H2A1IUK72UOFRV3FK1",
"name": {
"familyName": "Jimmy",
"givenName": "Jimmy carter SR",
"qualificationAffixCode": "III",
"titleAffixCode": "DR"
}
},
"currentStatus": {
"workerStatusId": "970004618963408",
"statusType": "TERMINATED",
"statusReason": "abc - Involuntary",
"effectiveDate": "2021-06-08T00:00:00Z"
},
"links": [
{
"rel": "self",
"href": "https://api.paychex.com/workers/00H2A1IUKAESBXZN4PYS"
},
{
"rel": "communications",
"href": "https://api.paychex.com/workers/00H2A1IUKAESBXZN4PYS/communications"
},
{
"rel": "supervisor",
"href": "https://api.paychex.com/workers/00H2A1IUK72UOFRV3FK1"
}
]
}
],
"links": []
}