--- title: "Company Workers" method: GET path: "/companies/{companyId}/workers" tags: ["Company"] --- # Company Workers `GET /companies/{companyId}/workers` ## Request - Base URL: `https://api.paychex.com` - URL: `https://api.paychex.com/companies/{companyId}/workers` - Auth: none declared - TypeScript: (a function with typed inputs; its response is checked against the schema) Array of workers (employee and contractor) for all of the companies who are associated with a specific company that your application has been granted access to. The combination of query parameters to be used with this endpoint are as follows: 1. givenname, familyname, legallastfour 2. from, to (start date, end date) 3. employeeid 4. locationid 5. offset, limit (paging). Note: Paging and filtering attributes cannot be applied together. ## Path parameters - `companyId` string, required ## Query parameters - `givenname` string - `familyname` string - `legallastfour` string - `employeeid` string - `from` string - `to` string - `locationid` string ## Response `200` successful operation - object - `metadata` MetadataResource - `contentItemCount` integer - `pagination` PaginationMetadataResource - `offset` integer - `limit` integer - `itemCount` integer - `total` integer - `content` WorkerResource - `workerId` string: The unique identifier associated with this worker representation. - `employeeId` string: The workers employee identification information. - `workerType` 'EMPLOYEE' | 'CONTRACTOR' | 'INDEPENDENT_CONTRACTOR': The type of worker. This data field cannot be PATCHED.NOTE: An IN_PROGRESS worker cannot be POSTED with a value of CONTRACTOR. - `employmentType` 'FULL_TIME' | 'PART_TIME': The type of employment for the worker. - `exemptionType` 'EXEMPT' | 'NON_EXEMPT': The Overtime classification of the worker.This data field cannot be PATCHED for ACTIVE workers. - `birthDate` string, date-time: The workers date of birth. It cannot be greater than today's date. - `sex` 'MALE' | 'FEMALE' | 'NOT_SPECIFIED' - `ethnicityCode` '(blank)' | 'HISPANIC_OR_LATINO' | 'WHITE_NOT_OF_HISPANIC_ORIGIN' | 'BLACK_OR_AFRICAN_AMERICAN' | 'NATIVE_HAWAIIAN_OR_OTHER_PACIFIC_ISLAND' | 'ASIAN' | 'AMERICAN_INDIAN_OR_ALASKAN_NATIVE' | 'TWO_OR_MORE_RACES' | 'PREFER_NOT_TO_ANSWER': Disclaimer:This parameter is not visible in Flex for the client. This data field cannot be PATCHED for ACTIVE workers. - `hireDate` string, date-time: The date which the worker was hired. It cannot be PATCHED for ACTIVE workers. - `clockId` string: The clock ID of the worker that can be an identification for other systems. - `name` NameResource: Data elements of a workers name. - `familyName` string: The family or last name of a worker. - `middleName` string: A subordinate given name, or initial representing that name, of a worker.
NOTE: More than one char is not allowed and returns an error.
A full middle name can be added directly via Paychex Flex only at this time. - `givenName` string: The given or first name of a worker. For an independent contractor that is a company rather than an individual, the name of the company. - `preferredName` string: The first name that the worker prefers to go by - `preferredLastName` string: The last name that the worker prefers to go by - `pronoun` string: The pronoun that the worker prefers to go by. This data field cannot be POSTED. - `qualificationAffixCode` string: A qualifier to the name of a worker, indicating generation. - `titleAffixCode` string: A personal title that comes before an individual's name in a formal address (such as Dr., Prof., Rev., Mr.). - `seniorityDate` string, date-time: The workers seniority date. This data field cannot be POSTED or PATCHED. - `profileImageURL` string: The workers profile image url. This data field cannot be POSTED or PATCHED. - `legalId` LegalIdResource: The workers legal tax identification information. This data field cannot be PATCHED for ACTIVE workers. - `legalIdType` 'SSN' | 'FEIN': A value that identifies the type of taxpayer identification number provided. SSN: Social Security Number - 9 digit number , FEIN: Federal Employer Identification Number (EIN) - `legalIdValue` string: The federal level taxpayer id number assigned to a business - `laborAssignmentId` string: The workers home labor assignment. - `jobId` string: The workers home job. - `locationId` string: The workers location. When POSTING or PATCHING this field the organization must also be present. - `job` JobTitleResource: The state representation of allowed worker job titles configured for the company. - `jobTitleId` string: The unique identifier associated with this job titles representation. - `title` string: The name of the title. - `startDate` string, date-time: Date when this job is available to be assigned to a worker. - `endDate` string, date-time: Date when this job is no longer available to be assigned to a worker. - `links` Link[] - `rel` string - `href` string - `hreflang` string - `media` string - `title` string - `type` string - `deprecation` string - `profile` string - `name` string - `organization` OrganizationResource: The state representation of Organizations within a company. - `organizationId` string: The unique identifier associated with this organizations representation. - `name` string: The name of the organization. - `number` string: The number assigned to the organization. - `level` string: The level number within the organizational structures hierarchy. - `links` Link[] - `rel` string - `href` string - `hreflang` string - `media` string - `title` string - `type` string - `deprecation` string - `profile` string - `name` string - `supervisor` SupervisorResource: The workers supervisor information. Supervisor cannot be a TERMINATED or IN_PROGRESS worker. - `workerId` string: The supervisor Id - `name` NameResource: Data elements of a workers name. - `familyName` string: The family or last name of a worker. - `middleName` string: A subordinate given name, or initial representing that name, of a worker.
NOTE: More than one char is not allowed and returns an error.
A full middle name can be added directly via Paychex Flex only at this time. - `givenName` string: The given or first name of a worker. For an independent contractor that is a company rather than an individual, the name of the company. - `preferredName` string: The first name that the worker prefers to go by - `preferredLastName` string: The last name that the worker prefers to go by - `pronoun` string: The pronoun that the worker prefers to go by. This data field cannot be POSTED. - `qualificationAffixCode` string: A qualifier to the name of a worker, indicating generation. - `titleAffixCode` string: A personal title that comes before an individual's name in a formal address (such as Dr., Prof., Rev., Mr.). - `currentStatus` Status: The workers employment status information. This data field cannot be POSTED or PATCHED for an IN_PROGRESS worker. - `workerStatusId` string: The unique identifier associated with this status representation. - `statusType` 'ACTIVE' | 'INACTIVE' | 'TERMINATED' | 'PENDING' | 'IN_PROGRESS': The workers current status. - `statusReason` string: The detailed reason of the workers current status. - `communications` CommunicationResource[]: Worker Communications. This data field cannot be updated for worker endpoint. - `communicationId` string: The unique ID associated with communication - `type` 'STREET_ADDRESS' | 'PO_BOX_ADDRESS' | 'PHONE' | 'MOBILE_PHONE' | 'FAX' | 'EMAIL' | 'PAGER': A set of communication types classifying an instruction that the customer, requester, or subject must comply with in order for the screening to go forward. NOTE: PHONE and EMAIL type supports BUSINESS and PERSONAL usage type only.MOBILE_PHONE, FAX and PAGER supports BUSINESS usage type only.This data field cannot be PATCHED. - `usageType` 'PERSONAL' | 'BUSINESS' | 'HOME' | 'WORK' | 'LOCATION_STREET_ADDRESS' | 'MAILING_ADDRESS': A code classifying a designated use associated with a contact method. For example, whether a telephone or email address is one for business communications or one primarily for personal use.This data field cannot be PATCHED. - `dialCountry` string: The country dialing code for a communication number. - `dialArea` string: The area dialing code for a communication number. - `dialNumber` string: The communication number, not including country dialing or area dialing codes. - `dialExtension` string: The extension of the associated communication number. - `uri` string: The mailto address as specified in RFC2368 . - `streetLineOne` string: The street address line one - `streetLineTwo` string: The street address line two - `postOfficeBox` string: The postal office box. This data field cannot be PATCHED. - `city` string: The city name - `postalCode` string: The zip-code - `postalCodeExtension` string: The zip-code extension - `countrySubdivisionCode` string: The state code (ISO 3166 subdivision code) - `countryCode` string: The country code (ISO 3166 alpha-2) - `workerCorrelationId` string: Id that you define which is used for error handling/responses.This data field is used while POSTING multiple IN_PROGRESS workers - `links` Link[] - `rel` string - `href` string - `hreflang` string - `media` string - `title` string - `type` string - `deprecation` string - `profile` string - `name` string ## Other responses - `400`: Missing query parameters (API-42), Missing query parameter (API-49), Invalid query parameter combination (API-40) - `401`: Unauthorized - `403`: User doesn't have access to this endpoint (API-2), Client has been end dated (API-68) - `404`: Invalid resource ID (API-7), No existing worker found matching search criteria (API-43) - `405`: Unsupported method type (API-59) - `406`: Unsupported Accept header - `500`: Internal Server Error. --- [API](https://skmtc.dev/paychex/apis/external-api.md) - [All operations](https://skmtc.dev/paychex/apis/external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/paychex/apis/external-api/revisions/07161d3e073f?raw)