Company

In Progress Workers

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 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.

post/companies/{companyId}/workers

Request

Base URL
https://api.paychex.com
Auth
none declared
TypeScript
https://skmtc.dev/paychex/apis/external-api/docs/companies/:companyId/workers/post.ts
A function with typed inputs. Its response is checked against the schema.

Path parameters

companyIdstring required

The id assigned to the company that workers are being requested for.

Request body

workerIdstring

The unique identifier associated with this worker representation.

employeeIdstring

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.

birthDatestring date-time

The workers date of birth. It cannot be greater than today's date.

sex'MALE' | 'FEMALE' | 'NOT_SPECIFIED'

Disclaimer:This parameter is not visible in Flex for the client. This data field cannot be PATCHED for ACTIVE workers.

hireDatestring date-time

The date which the worker was hired. It cannot be PATCHED for ACTIVE workers.

clockIdstring

The clock ID of the worker that can be an identification for other systems.

seniorityDatestring date-time

The workers seniority date. This data field cannot be POSTED or PATCHED.

profileImageURLstring

The workers profile image url. This data field cannot be POSTED or PATCHED.

laborAssignmentIdstring

The workers home labor assignment.

jobIdstring

The workers home job.

locationIdstring

The workers location. When POSTING or PATCHING this field the organization must also be present.

workerCorrelationIdstring

Id that you define which is used for error handling/responses.This data field is used while POSTING multiple IN_PROGRESS workers

Example request

{
  "workerId": "00Z5V9BTIHRQF2CF7BTH",
  "employeeId": "3052",
  "employmentType": "NON_EXEMPT",
  "sex": "MALE",
  "hireDate": "2015-06-15T00:00:00Z",
  "clockId": "4321",
  "name": {
    "familyName": "JONES",
    "middleName": "H",
    "givenName": "INDIANA",
    "preferredName": "Indi",
    "preferredLastName": "Jan",
    "pronoun": "He/him/his",
    "qualificationAffixCode": "Jr",
    "titleAffixCode": "Dr."
  },
  "seniorityDate": "2020-05-20T00:00:00Z",
  "profileImageURL": "https://cdn.url/flexworkerphotos/wrkr0ad1b60a-45cc-4bbb-b5gc-299a832ce111.jpg",
  "legalId": {
    "legalIdValue": "995886885"
  },
  "laborAssignmentId": "970001557863345",
  "jobId": "970001557916904",
  "locationId": "970001701620675",
  "job": {
    "jobTitleId": "00DWS906IMW2JSH8AQJ8",
    "title": "Archaeologist",
    "startDate": "2010-01-01T00:00:00Z",
    "endDate": "2016-12-31T00:00:00Z"
  },
  "organization": {
    "organizationId": "970000055981384",
    "name": "2 Division B",
    "number": "2",
    "level": "Level 2"
  },
  "supervisor": {
    "workerId": "00H2A1IUJ4IPERJ589YE",
    "name": {
      "familyName": "JONES",
      "middleName": "H",
      "givenName": "INDIANA",
      "preferredName": "Indi",
      "preferredLastName": "Jan",
      "pronoun": "He/him/his",
      "qualificationAffixCode": "Jr",
      "titleAffixCode": "Dr."
    }
  },
  "currentStatus": {
    "workerStatusId": "00DWS906IMW2JSH8AQJ9",
    "statusReason": "HIRED"
  },
  "communications": [
    {
      "communicationId": "00Z5V9BTINBT97UMERCA",
      "type": "STREET_ADDRESS",
      "usageType": "BUSINESS",
      "streetLineOne": "Mike St",
      "streetLineTwo": "Sulley Ln",
      "city": "ANAHEIM",
      "postalCode": "92802",
      "countrySubdivisionCode": "CA",
      "countryCode": "US"
    }
  ]
}

Response

successful operation

Example response

{
  "content": {
    "workerId": "00Z5V9BTIHRQF2CF7BTH",
    "employeeId": "3052",
    "employmentType": "NON_EXEMPT",
    "sex": "MALE",
    "hireDate": "2015-06-15T00:00:00Z",
    "clockId": "4321",
    "name": {
      "familyName": "JONES",
      "middleName": "H",
      "givenName": "INDIANA",
      "preferredName": "Indi",
      "preferredLastName": "Jan",
      "pronoun": "He/him/his",
      "qualificationAffixCode": "Jr",
      "titleAffixCode": "Dr."
    },
    "seniorityDate": "2020-05-20T00:00:00Z",
    "profileImageURL": "https://cdn.url/flexworkerphotos/wrkr0ad1b60a-45cc-4bbb-b5gc-299a832ce111.jpg",
    "legalId": {
      "legalIdValue": "995886885"
    },
    "laborAssignmentId": "970001557863345",
    "jobId": "970001557916904",
    "locationId": "970001701620675",
    "job": {
      "jobTitleId": "00DWS906IMW2JSH8AQJ8",
      "title": "Archaeologist",
      "startDate": "2010-01-01T00:00:00Z",
      "endDate": "2016-12-31T00:00:00Z"
    },
    "organization": {
      "organizationId": "970000055981384",
      "name": "2 Division B",
      "number": "2",
      "level": "Level 2"
    },
    "supervisor": {
      "workerId": "00H2A1IUJ4IPERJ589YE",
      "name": {
        "familyName": "JONES",
        "middleName": "H",
        "givenName": "INDIANA",
        "preferredName": "Indi",
        "preferredLastName": "Jan",
        "pronoun": "He/him/his",
        "qualificationAffixCode": "Jr",
        "titleAffixCode": "Dr."
      }
    },
    "currentStatus": {
      "workerStatusId": "00DWS906IMW2JSH8AQJ9",
      "statusReason": "HIRED"
    },
    "communications": [
      {
        "communicationId": "00Z5V9BTINBT97UMERCA",
        "type": "STREET_ADDRESS",
        "usageType": "BUSINESS",
        "streetLineOne": "Mike St",
        "streetLineTwo": "Sulley Ln",
        "city": "ANAHEIM",
        "postalCode": "92802",
        "countrySubdivisionCode": "CA",
        "countryCode": "US"
      }
    ]
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.