Developer Resources


There are several predefined headers that define the control metadata that’s used with each Request/Response.

Request Headers

  • Authorization
    • The access token (see Authentication) can be provided with the authentication type set as Bearer. Example: Authorization: Bearer {access_token}. 

  • X-payx-client-correlationId
    • Contains a unique ID, per request, that you SHOULD generate. It can be used for enforcing idempotency.
    • The X-payx-client-correlationId is also be used for troubleshooting and its use is required for technical support.

Response Headers

  • Content-Type
    • The content type will be set to the vendor media type used in the body of the response.

  • Cache-Control
    • Those resources that have been designated as public have been identified as cacheable resources and will be cached by the Paychex RESTful servers. They may be optionally cached by the client application but must adhere to max-age and ETag cache controls.
    • Those resources that have been designated as private have been identified as cacheable resources any may be cached by the client application. Private resources will not be cached by the Paychex RESTful servers.
    • Cacheable resources that are conditional based use the the max-age (seconds) composite parameter and the Expires header to indicate how long the resource can remain in cache until a new resource representation needs to be fetched. In those scenarios where a resource should not be cached, the RESTful resource will be returned with both the nocache and nostore composite parameters set. When set it is invalid to cache or store the resource for any period of time as its representation is volatile and should be fetched when used.
      Cache-Control:public, max-age=36000Cache-Control:private, max-age=86400Cache-Control:no-cache, no-store

  • Expires
    • When a resource has been determined to be cacheable the Expires header will be set. It is used to indicate the date and time when the resource becomes stale and a new representation needs to be fetched.(e.g. Expires: Mon, 25 Jun 2015 21:31:12 GMT)

  • X-payx-txid
    • A unique identifier which is generated on the Paychex end for each request that is sent in which can used for tracking, tracing, and troubleshooting.

  • ETag
    • This is used for resources that support pagination (see Paging)