---
title: "Worker Contacts"
method: POST
path: "/workers/{workerId}/contacts"
tags: ["Worker"]
---

# Worker Contacts

`POST /workers/{workerId}/contacts`

## Request

- Base URL: `https://api.paychex.com`
- URL: `https://api.paychex.com/workers/{workerId}/contacts`
- Auth: none declared
- TypeScript: <https://skmtc.dev/paychex/apis/external-api/docs/workers/:workerId/contacts/post.ts> (a function with typed inputs; its response is checked against the schema)

Add one or more contacts to a worker. A contact may represent a person or entity (organization) but not both. A contact must have at least one communication (telecom, postal, or email). Person contacts can have multiple communications for each communication type (telecom, postal, or email) to support BUSINESS and PERSONAL. Exactly one contact must be marked as primary for each contact type. If one or more contacts are posted for the same contact type, and there are currently no contacts of that type for the worker, the first contact in the list will be made primary unless another in the list is expressly marked as primary. When a new contact is made primary the previous primary contact will be marked as not primary. Use the GET /companies/{companyId}/contacttypes endpoint to get a full list of available contact types and relationship types (used for person contacts).

## Path parameters

- `workerId` string, required

## Request body

- WorkerContactResource
  - `contactId` string: The ID for the workers specific contact.
  - `contactType` ContactTypeResource1: The type of this worker contact. Required for POST contacts.
    - `contactTypeId` string: The ID for specific type of contact. Required for POST contacts.
    - `contactTypeName` string: Enum: "EMERGENCY_CONTACT" The name for specific type of contact.
  - `relationship` RelationshipResource: The relationship for this worker contract. Required for POST contacts.
    - `relationshipId` string: The ID for the workers relationship to contact.
    - `relationWeid` string: The ID for the workers specific relation.
    - `relationshipType` RelationTypeResource1: The relationship type for this worker contact. Required for POST person contacts.
      - `relationshipTypeId` string: ID of worker specific type of relationship with the contact. Required for POST contacts.
      - `relationshipTypeName` string: The name of worker specific type of relationship with the contact. Enum: "Spouse", "Parent", "Sibling", "Child", "Friend", "Domestic Partner", "Other"
    - `primary` boolean: Where to indicate if the contact is selected as Primary, where true = Primary contact and false = not Primary contact.
    - `person` PersonResource: The person associated with this relationship. The relationship must have either a person or entity.
      - `name` NameResource1: Information about the 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. <br />NOTE: Please send in just a single character initial for middleName. <br />If sending in more than one character the name will be truncated the first letter of the middleName. <br /> A full middle name can be entered directly in 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.).
      - `communication` PersonCommunicationResource: The set of communications for this contact. Required for POST contacts.
        - `telecom` TelecomResource[]: The telecom communications for this contact.
          - `communicationId` string: The ID for the workers relationship to contact.
          - `dialCountry` string: The country code. Required for POST contacts.
          - `dialArea` string: The area code. Required for POST contacts.
          - `dialNumber` string: The phone number. Required for POST contacts.
          - `type` string: Enum: "PHONE", "MOBILE_PHONE" Indicates whether or not the number is for a mobile device. Required for POST contacts.
          - `usageType` string: Enum: "PERSONAL", "BUSINESS" A code classifying a designated use associated with a contact method. For example, whether a telephone or email address is one for work communications or one primarily for personal use. This data field cannot be PATCHED. Required for POST contacts.
          - `extension` string: The phone extension.
        - `postal` PostalResource[]: The postal communications for this contact.
          - `communicationId` string: The ID for the workers relationship to contact.
          - `streetLineOne` string: The street address line one. Required for street address. Required for POST contacts.
          - `streetLineTwo` string: The street address line two.
          - `postOfficeBox` string: The postal office box. Required for PO Box with POST contacts.
          - `city` string: The city name. Required for POST contacts.
          - `postalCode` string: The zip-code. Required for POST contacts.
          - `countrySubdivisionCode` string: The state code (ISO 3166 subdivision code). Required for POST contacts.
          - `countryCode` string: The country code (ISO 3166 alpha-2). Required for POST contacts.
        - `email` EmailResource[]: The email communications for this contact.
          - `communicationId` string: The ID for this email communication.
          - `uri` string: The mailto address as specified in RFC2368. Required for POST contacts.
          - `usageType` string: Enum: "PERSONAL", "BUSINESS" A code classifying a designated use associated with a contact method. For example, whether a telephone or email address is one for work communications or one primarily for personal use. This data field cannot be PATCHED. Required for POST contacts.
    - `entity` EntityResource: The organization associated with this relationship. The relationship must have either a person or entity.
      - `entityId` string: The ID for this contact.
      - `entityName` string: The entity name. Required for POST contacts.
      - `communication` EntityCommunicationResource: The set of communications for this contact. Required for POST contacts.
        - `telecom` TelecomResource: The telecom communications for this contact.
          - `communicationId` string: The ID for the workers relationship to contact.
          - `dialCountry` string: The country code. Required for POST contacts.
          - `dialArea` string: The area code. Required for POST contacts.
          - `dialNumber` string: The phone number. Required for POST contacts.
          - `type` string: Enum: "PHONE", "MOBILE_PHONE" Indicates whether or not the number is for a mobile device. Required for POST contacts.
          - `usageType` string: Enum: "PERSONAL", "BUSINESS" A code classifying a designated use associated with a contact method. For example, whether a telephone or email address is one for work communications or one primarily for personal use. This data field cannot be PATCHED. Required for POST contacts.
          - `extension` string: The phone extension.
        - `postal` PostalResource: The postal communications for this contact.
          - `communicationId` string: The ID for the workers relationship to contact.
          - `streetLineOne` string: The street address line one. Required for street address. Required for POST contacts.
          - `streetLineTwo` string: The street address line two.
          - `postOfficeBox` string: The postal office box. Required for PO Box with POST contacts.
          - `city` string: The city name. Required for POST contacts.
          - `postalCode` string: The zip-code. Required for POST contacts.
          - `countrySubdivisionCode` string: The state code (ISO 3166 subdivision code). Required for POST contacts.
          - `countryCode` string: The country code (ISO 3166 alpha-2). Required for POST contacts.
        - `email` EmailResource: The email communications for this contact.
          - `communicationId` string: The ID for this email communication.
          - `uri` string: The mailto address as specified in RFC2368. Required for POST contacts.
          - `usageType` string: Enum: "PERSONAL", "BUSINESS" A code classifying a designated use associated with a contact method. For example, whether a telephone or email address is one for work communications or one primarily for personal use. This data field cannot be PATCHED. Required for POST contacts.

## Response `201`

Successful operation.

- object
  - `content` WorkerContactResource
    - `contactId` string: The ID for the workers specific contact.
    - `contactType` ContactTypeResource1: The type of this worker contact. Required for POST contacts.
      - `contactTypeId` string: The ID for specific type of contact. Required for POST contacts.
      - `contactTypeName` string: Enum: "EMERGENCY_CONTACT" The name for specific type of contact.
    - `relationship` RelationshipResource: The relationship for this worker contract. Required for POST contacts.
      - `relationshipId` string: The ID for the workers relationship to contact.
      - `relationWeid` string: The ID for the workers specific relation.
      - `relationshipType` RelationTypeResource1: The relationship type for this worker contact. Required for POST person contacts.
        - `relationshipTypeId` string: ID of worker specific type of relationship with the contact. Required for POST contacts.
        - `relationshipTypeName` string: The name of worker specific type of relationship with the contact. Enum: "Spouse", "Parent", "Sibling", "Child", "Friend", "Domestic Partner", "Other"
      - `primary` boolean: Where to indicate if the contact is selected as Primary, where true = Primary contact and false = not Primary contact.
      - `person` PersonResource: The person associated with this relationship. The relationship must have either a person or entity.
        - `name` NameResource1: Information about the 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. <br />NOTE: Please send in just a single character initial for middleName. <br />If sending in more than one character the name will be truncated the first letter of the middleName. <br /> A full middle name can be entered directly in 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.).
        - `communication` PersonCommunicationResource: The set of communications for this contact. Required for POST contacts.
          - `telecom` TelecomResource[]: The telecom communications for this contact.
            - `communicationId` string: The ID for the workers relationship to contact.
            - `dialCountry` string: The country code. Required for POST contacts.
            - `dialArea` string: The area code. Required for POST contacts.
            - `dialNumber` string: The phone number. Required for POST contacts.
            - `type` string: Enum: "PHONE", "MOBILE_PHONE" Indicates whether or not the number is for a mobile device. Required for POST contacts.
            - `usageType` string: Enum: "PERSONAL", "BUSINESS" A code classifying a designated use associated with a contact method. For example, whether a telephone or email address is one for work communications or one primarily for personal use. This data field cannot be PATCHED. Required for POST contacts.
            - `extension` string: The phone extension.
          - `postal` PostalResource[]: The postal communications for this contact.
            - `communicationId` string: The ID for the workers relationship to contact.
            - `streetLineOne` string: The street address line one. Required for street address. Required for POST contacts.
            - `streetLineTwo` string: The street address line two.
            - `postOfficeBox` string: The postal office box. Required for PO Box with POST contacts.
            - `city` string: The city name. Required for POST contacts.
            - `postalCode` string: The zip-code. Required for POST contacts.
            - `countrySubdivisionCode` string: The state code (ISO 3166 subdivision code). Required for POST contacts.
            - `countryCode` string: The country code (ISO 3166 alpha-2). Required for POST contacts.
          - `email` EmailResource[]: The email communications for this contact.
            - `communicationId` string: The ID for this email communication.
            - `uri` string: The mailto address as specified in RFC2368. Required for POST contacts.
            - `usageType` string: Enum: "PERSONAL", "BUSINESS" A code classifying a designated use associated with a contact method. For example, whether a telephone or email address is one for work communications or one primarily for personal use. This data field cannot be PATCHED. Required for POST contacts.
      - `entity` EntityResource: The organization associated with this relationship. The relationship must have either a person or entity.
        - `entityId` string: The ID for this contact.
        - `entityName` string: The entity name. Required for POST contacts.
        - `communication` EntityCommunicationResource: The set of communications for this contact. Required for POST contacts.
          - `telecom` TelecomResource: The telecom communications for this contact.
            - `communicationId` string: The ID for the workers relationship to contact.
            - `dialCountry` string: The country code. Required for POST contacts.
            - `dialArea` string: The area code. Required for POST contacts.
            - `dialNumber` string: The phone number. Required for POST contacts.
            - `type` string: Enum: "PHONE", "MOBILE_PHONE" Indicates whether or not the number is for a mobile device. Required for POST contacts.
            - `usageType` string: Enum: "PERSONAL", "BUSINESS" A code classifying a designated use associated with a contact method. For example, whether a telephone or email address is one for work communications or one primarily for personal use. This data field cannot be PATCHED. Required for POST contacts.
            - `extension` string: The phone extension.
          - `postal` PostalResource: The postal communications for this contact.
            - `communicationId` string: The ID for the workers relationship to contact.
            - `streetLineOne` string: The street address line one. Required for street address. Required for POST contacts.
            - `streetLineTwo` string: The street address line two.
            - `postOfficeBox` string: The postal office box. Required for PO Box with POST contacts.
            - `city` string: The city name. Required for POST contacts.
            - `postalCode` string: The zip-code. Required for POST contacts.
            - `countrySubdivisionCode` string: The state code (ISO 3166 subdivision code). Required for POST contacts.
            - `countryCode` string: The country code (ISO 3166 alpha-2). Required for POST contacts.
          - `email` EmailResource: The email communications for this contact.
            - `communicationId` string: The ID for this email communication.
            - `uri` string: The mailto address as specified in RFC2368. Required for POST contacts.
            - `usageType` string: Enum: "PERSONAL", "BUSINESS" A code classifying a designated use associated with a contact method. For example, whether a telephone or email address is one for work communications or one primarily for personal use. This data field cannot be PATCHED. Required for POST contacts.
  - `links` Link1[]
    - `href` string
    - `hreflang` string
    - `title` string
    - `type` string
    - `deprecation` string
    - `profile` string
    - `name` string
    - `templated` boolean

## Other responses

- `400`: The request is invalid (API-4), Invalid email address (API-13), Invalid phone number (API-14), Invalid street address (API-15), Invalid worker status (API-19), Duplicate entry (API-26), Required field missing (API-46), Required field invalid (API-48)
- `401`: Unauthorized (API-102)
- `403`: User doesn't have access to this endpoint (API-2), Client has been end dated (API-68)
- `404`: Invalid resource ID (API-7)
- `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)