Developer Center

Our API infrastructure utilizes consistent terminology and labeling

Workers

Endpoint: https://api.paychex.com/companies/{companyId}/workers

Verbs supported: GET & POST

GET: Array of workers (employee and contractor) who are associated with a specific company that your application has been granted access to. Currently workers that exist within Paychex Flex payroll that have a givenName, familyName, and legalID will be available.  Future enhancements will allow workers from other Paychex systems. GET on this resource supports paging and is recommended for obtaining 100 workers at a time for larger clients.

POST: Add one or more workers to a specific company that your application has been granted access to. These workers will be added with an IN_PROGRESS status assigned to them.  In_Progress workers will pre-populated within Paychex Flex and will require someone to complete them to be fully available with the Flex platform.  Paychex Flex UI will hold a majority of validation, rules, and enforced required fields based on the clients configuration.  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). Optionally you can include a workers communications object within the worker.  Once generated the IN_PROGRESS worker can have their communications, Compensation and Federal Taxes POSTed and PATCHed using the generated workerId.

Request:

Element NameTypeDescription
companyId stringThe id assigned to the company that workers are being requested for.

Response:

VerbProfileDescription
GEThttp://api.paychex.com/profiles/workers/v1Default workers profile.
GEThttp://api.paychex.com/profiles/workers_communications/v1Workers profile that will also include the workers communications.

Endpoint: https://api.paychex.com/companies/{companyId}/workers?givenname={givenName}&familyname={familyName}&legallastfour={legalLastFour}

Verbs supported: GET

GET: Array of workers (employee and contractor) which match the search criteria.

Request:

Element NameTypeDescription
companyId stringThe id assigned to the company that workers are being searched for.
givenNamestringThe given or first name of the workers to search for.
familyNamestringThe family or last name of the workers to search for.
legalLastFourstringThe last 4 digits of the workers federal level taxpayer id number of the worker to search for.

Response:

VerbProfileDescription
GEThttp://api.paychex.com/profiles/workers/v1Default workers profile.
GEThttp://api.paychex.com/profiles/workers_communications/v1Workers profile that will also include the workers communications.

Endpoint: https://api.paychex.com/companies/{companyId}/workers?from={searchStartDate}&to={searchEndDate}

Verbs supported: GET

GET: Array of workers (employee and contractor) that have a creation date between the start date and end date that fall into the search range provided. A date example is 2017-02-13T12:48:00Z

Request:

Element NameTypeDescription
companyId stringThe id assigned to the company that workers are being searched for.
searchStartDatedateThe beginning of the search date range using for when the worker was created.
searchEndDatedateThe ending of the search date range using for then the worker was created.

Response:

VerbProfileDescription
GEThttp://api.paychex.com/profiles/workers/v1Default workers profile.
GEThttp://api.paychex.com/profiles/workers_communications/v1Workers profile that will also include the workers communications.

Endpoint: https://api.paychex.com/companies/{companyId}/workers?employeeId={employeeId}

Verbs supported: GET

GET: Find a worker by their employee ID.

Request:

Element NameTypeDescription
companyId stringThe id assigned to the company that workers are being searched for.
employeeIdstringThe assigned workers employee ID.

Response:

VerbProfileDescription
GEThttp://api.paychex.com/profiles/workers/v1Default workers profile.
GEThttp://api.paychex.com/profiles/workers_communications/v1Workers profile that will also include the workers communications.

 

Endpoint: https://api.paychex.com/workers/{workerId}

Verbs supported: GET & PATCH

GET: Information about a unique worker (employee and contractor) that your application has been granted access to. Currently workers that exist within Paychex Flex payroll will be available, future enhancements will make workers from other Paychex systems available.

PATCH: Update a unique worker (employee and contractor) that your application has been granted access to modify.

Request:

Element NameTypeDescription
workerId stringThe id assigned to the worker which workers are being requested for.

Response:

VerbProfileDescription
GEThttp://api.paychex.com/profiles/worker/v1Default worker profile.
GEThttp://api.paychex.com/profiles/worker_communications/v1Worker profile that will also include the workers communications.

Response

Profile: Worker

The representational state of a person who is classified as a worker. A worker is an exempt or non-exempt employee or contractor.
Element NameTypeDescriptionNon In-Process Supports PATCHIn-Process Supports PATCH
workerIdstringThe unique identifier associated with this worker representation.  
employeeIdstringThe workers employee identification information.xx
clockIDstringThe clock ID of the worker that can be an identification for other systems.xx
workerTypestringThe type of worker.
  • EMPLOYEE
  • CONTRACTOR
  
employmentTypestringThe type of employment for the worker.
  • FULL_TIME
  • PART_TIME
xx
exemptionTypestringThe Overtime classification of the worker.
  • EXEMPT
  • NON_EXEMPT
 x
hireDatedateThe date which the worker was hired. x
birthDatedateThe workers Date of Birth.xx
sexstring
  • MALE
  • FEMALE
  • UNKNOWN
  • NOT_SPECIFIED
 x
ethnicityCodestringA code classifying a person on the basis of their ethnicity. Ethnicity pertains to having common racial, cultural, religious, or linguistic characteristics. Ethnicity classifications may be relevant under government labor or fair employment practice regulations. For example, under U.S. record keeping rules for federal contractors employers may require reporting of data with respect to whether or not a person is of "Hispanic or Latino" ethnicity, a classification which encompass persons of Mexican, Puerto Rican, Cuban, Central or South American, or other Spanish culture or origin, regardless of race.
  • HISPANIC_OR_LATINO
  • WHITE_NOT_OF_HISPANIC_ORIGIN
  • BLACK_OR_AFRICAN_AMERICAN
  • NATIVE_HAWAIIAN_OR_OTHER_PACIFIC_ISLAND
  • AMERICAN_INDIAN_OR_ALASKAN_NATIVE
  • TWO_OR_MORE_RACES
  • ASIAN_OR_PACIFIC_ISLANDER
  • **Note: Company Admins can add to this list so new items can become available
 x
nameobjectInformation about the workers name.xx
currentStatusobjectThe workers employment status information.x 
legalIdobjectThe workers legal tax identification information. x
organizationobjectThe organization which the worker is part of.xx
jobobjectThe workers current job/position information.xx
supervisorobjectThe workers supervisor's information. x

 

Object Components:

name: Data elements of a workers name.

Element NameTypeDescription
givenNamestringThe given or first name of a worker. For an independent contractor that is a company rather than an individual, the name of the company.
middleNamestringA subordinate given name, or initial representing that name, of a worker.
familyNamestringThe family or last name of a worker.
titleAffixCodestringA title indicating rank (Sargent), profession (Reverend, Doctor), or marital status (Miss, Mrs) used by a worker.
qualificationAffixCodestringA qualifier to the name of a worker, indicating generation.
preferredNamestringThe name that the worker prefers to go by; also known as a "nickname"

currentStatusStatus of the worker at this point in time.

Element NameTypeDescription
workerStatusIdstringThe unique identifier associated with this status representation.
statusTypestringThe workers current status.
  • ACTIVE
  • INACTIVE
  • TERMINATED
  • TRANSFERRED
  • PENDING
  • IN_PROGRESS
statusReasonstringThe detailed reason of the workers current status.
  • Active Status Reasons:
    • HIRED
    • RETURN_TO_WORK
    • REHIRED
    • ACTIVATE_EMP
    • BEGIN_CONTRACT
    • RESUME_CONTRACT
    • ACTIVATE_IC
  • Inactive Status Reasons:
    • DISABILITY
    • INACTIVATE
    • JURY_DUTY
    • ADOPTION_LEAVE
    • EDUCATION_LEAVE
    • FAMILY_LEAVE
    • MATERNITY_LEAVE
    • MEDICAL_LEAVE
    • MILITARY_LEAVE
    • PATERNITY_LEAVE
    • SEASONAL_EMPLOYMENT
    • CONTRACT_ON_HOLD
    • STUDENT_ON_BREAK
    • WORK_IS_SLOW
    • CUSTOM_UNKNOWN: At this time the API does not support the custom reasons that can be configured for a company
  • Terminated Status Reasons:
    • TERMINATION
    • DISCHARGED
    • RESIGNED
    • RETIRED
    • DECEASED
    • PEO_SERVICES_CANCELLED
    • TERMINATE_CONTRACT
  • Transferred Reasons:
    • EMPLOYEE_TRANSFER
  • Pending Employment Status Reasons:
    • PENDING_HIRE
    • PENDING_REHIRE
    • PENDING_CONTRACT
  • In Progress Employment Status Reasons:
    • PENDING_HIRE
    • PENDING_SYNC
effectiveDatedateDate that this status has started for the worker.

legalId: Legal information associated with a worker.

Element NameTypeDescription
legalIdValuestringThe federal level taxpayer id number that the worker has provided
legalIdTypestringA value that identifies the type of taxpayer identification number provided.
  • SSN: Social Security Number - 9 digit number
  • SIN: Social Insurance Number
  • FEIN: Federal Employer Identification Number (EIN)
  • SSNLast4: Last 4 digits of the Social Security Number

organization: Organization that the worker is assigned to.

Element NameTypeDescription
organizationIdstringUnique ID for the organization within the company that the worker is assigned to.
namestringThe name of the organization that that the worker is assigned to.

job: Job title that the worker is assigned to.

Element NameTypeDescription
jobTypeIdstringUnique ID for that job within the company that the worker is assigned to.
titlestringThe name of the title that the worker is assigned to.

supervisor: Data elements of a worker's supervisor's name.

Element NameTypeDescription
workerIdstringThe unique identifier associated with the supervisor's representation.
nameobjectInformation about the supervisors name.

Error Codes

Errors which are specific for a resource.

CodeHTTP StatusMessageResolution
API-11400This {elementName} - {requestedValue} is already in use.Please enter a valid value.
API-12400The birthdate cannot be after today's date.Enter a valid birthdate.
API-3400Invalid e-mail address format.An e-mail address must be in the format example@domain.ext.
API-14401Invalid phone number format.The phone number must be 10 digits, including the area code. If using a country code, it must also be the correct number of digits.
API-15401Invalid address format.An address consists of a street address, up to two lines, or PO Box, plus city, state, and ZIP code. The ZIP, extension, and delivery point are optional.
{
  "metadata": {
    "contentItemCount": 5,
    "pagination": {
      "offset": 5,
      "limit": 5,
      "itemCount": 56
    }
  },
  "content": [
    {
      "workerId": "00Z5V9BTIHRQF2CF7BTH",
      "employeeId": "3052",
      "workerType": "EMPLOYEE",
      "employmentType": "FULL_TIME",
      "exemptionType": "NON_EXEMPT",      
      "birthDate": "1899-07-01T00:00:00Z",
      "clockId": "4321",      
      "sex": "MALE",
      "ethnicityCode": "WHITE_NOT_OF_HISPANIC_ORIGIN",
      "hireDate": "2015-06-15T00:00:00Z",
      "name": {
        "familyName": "JONES",
        "middleName": "H",
        "givenName": "INDIANA",
        "preferredName": "Indi",
        "qualificationAffixCode": "Jr",
        "titleAffixCode": "DR"
      },
      "legalId": {
        "legalIdType": "SSN",
        "legalIdValue": "333221111"
      },
      "currentStatus": {
        "workerStatusId": "00DWS906IMW2JSH8AQJ9", 
        "statusReason": "HIRED",
        "statusType": "ACTIVE",
        "effectiveDate": "2015-06-15T00:00:00Z"
      },
      "job": {
        "jobTitleId": "00DWS906IMW2JSH8AQJ8",
        "title": "Archaeologist"
      },
      "organization": {
        "organizationId": "970000055981384",
        "name": "2 Division B"
      },
      "supervisor": {
        "workerId": "00H2A1IUJ4IPERJ589YE",
        "name": { 
            "familyName": "Scott",
            "givenName": "Willie"
      },
      "links": [
        {
          "rel": "self",
          "href": "https://api.paychex.com/workers/00Z5V9BTIHRQF2CF7BTH"
        },
        {
          "rel": "communications",
          "href": "https://api.paychex.com/workers/00Z5V9BTIHRQF2CF7BTF/communications"
        },
        {
          "rel": "supervisor",
          "href": "https://api.paychex.com/workers/00H2A1IUJ4IPERJ589YE"
        }
      ]
    }
  ],
  "links": [
    {
      "rel": "self",
      "href": "https://api.paychex.com/companies/00Z5V9BTI8J2FCGESC05/workers?offset=5&limit=5"
    },
    {
      "rel": "next",
      "href": "https://api.paychex.com/companies/00Z5V9BTI8J2FCGESC05/workers?offset=10&limit=5"
    },
    {
      "rel": "prev",
      "href": "https://api.paychex.com/companies/00Z5V9BTI8J2FCGESC05/workers?offset=0&limit=5"
    }
  ]
}