--- title: "In Progress Workers" method: POST path: "/companies/{companyId}/workers" tags: ["Company"] --- # In Progress Workers `POST /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) Add one or more workers to a specific company that your application has access to. Workers will be added with an IN_PROGRESS status assigned to them and will need to be completed in Flex. Required fields are givenName, familyName, & workerType (when adding multiple workers at a time you will need to also include a "workerCorrelationId" data element on each worker, that will be used as an identifier in our responses). For more information on IN_PROGRESS workers, including how to send an invite for the worker to add their information in Flex, [see the Worker page](https://developer.paychex.com/resources/worker) in Developer Resources. A worker's federal tax elections will be generated and defaulted automatically to withheld with 0 deductions/income and a filing status of single/married filing separately. Upon successfully posting a new in-progress worker, the response will generate a new workerId. This ID can then be used in subsequent calls to update existing worker properties like federal taxes, or add more details to the worker's communications, direct deposit, compensation, and state taxes. ## Path parameters - `companyId` string, required ## Request body - 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 ## Response `201` successful operation - object - `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 - `207`: Multi-status - `400`: Required field invalid (API-48) - `401`: Unauthorized - `403`: User doesn't have access to this endpoint (API-2), Client has been end dated (API-68) - `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)