> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/integrations/catalog/paychex.md).

# Paychex

Connect to Paychex Flex to work with payroll and HR data: list the people at a company, read one worker's full record, start a new hire, list the earnings and deductions a company has configured, and pull payroll checks for a pay period.

### Connectors

Choose the connector that matches your authentication method. The options below use the names shown in StackAI.

| Connector | Authentication |
| --------- | -------------- |
| Paychex   | Credentials    |

#### Paychex

Connect to Paychex Flex to read your people, pay components and payroll checks, and to start new hires. Uses the client ID and secret of a Connected Application that a Flex Super Admin or Security Admin creates under Company Settings > Connected Applications, so access is limited to the data levels chosen there.

**Set up in Paychex**

1. Prepare the Paychex account or service that the workflow will access. Grant access to the required resources and operations.
2. **Client ID:** The API key of a Paychex Flex Connected Application. A Flex Super Admin or Security Admin creates it under Company Settings > Connected Applications, naming the app and choosing which data it may reach.

**Set up in StackAI**

1. Open **Settings → Connections**, add a connection, and select **Paychex**.
2. Enter the credentials and connection details in the fields below.
3. Save the connection and check its connection status. Select this saved connection when configuring an action or feature that uses it.

**Connection fields**

| StackAI field | Required | What to enter                                                                                                                                                                                                                                                             |
| ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Client ID     | Yes      | The API key of a Paychex Flex Connected Application. A Flex Super Admin or Security Admin creates it under Company Settings > Connected Applications, naming the app and choosing which data it may reach. [Provider instructions](https://developer.paychex.com/client). |
| Client Secret | Yes      | The secret paired with that client id. Paychex shows it once at creation; regenerating the application invalidates the previous secret. [Provider instructions](https://developer.paychex.com/client).                                                                    |

#### Verify the connection

Check that the connection is healthy. Then run a read operation against a resource the connected account can access. A successful connection check confirms authentication; it does not guarantee permission for every action.

If access is denied, check the credential or OAuth permissions, the selected account or environment, and access to the specific resource. Update expired credentials or reconnect after permissions change.

### Use an action

1. Add the required **Paychex** action to the workflow.
2. Select a connection when the action requests one.
3. Complete the required fields. Use the reference picker when a value comes from another workflow step.
4. Run the workflow and inspect the action’s output. Check the result before using it in a later step.

### Actions

#### List Employees

List people at a Paychex company by name and worker ID; excludes sensitive fields by default.

**Required permissions:** `read:company_people`.

**Inputs**

| Field                        | Type            | Required | Description                                                                                                                                             |
| ---------------------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Company                      | select (string) | Yes      | The Paychex company whose people you want to list. Only companies these credentials can reach are shown. Options load from the selected connection.     |
| Worker type                  | select (string) | No       | Employees (W2) by default. Choose contractors (1099) or both. Available values: Employees (W2), Independent contractors (1099), All. Default: EMPLOYEE. |
| Include personal identifiers | boolean         | No       | Off by default. Turn on only if you need Social Security number, date of birth, sex and ethnicity in the results. Default: false.                       |
| Include contact details      | boolean         | No       | Add work email, phone and address to each person. Default: false.                                                                                       |
| Max results                  | integer         | No       | Most people to return. Minimum: 1. Maximum: 200. Default: 25.                                                                                           |
| Start at                     | integer         | No       | Continue a previous listing from where it stopped. Default: 0.                                                                                          |
| Page ETag                    | string          | No       | Paste the Page ETag from the previous call so the roster does not shift between pages.                                                                  |

**Outputs**

| Field                         | Type          | Description                                           |
| ----------------------------- | ------------- | ----------------------------------------------------- |
| Workers                       | object\_array | The matching people at this company.                  |
| Next offset                   | integer       | Pass back as Start at to fetch more people.           |
| Page ETag                     | string        | Pass back as Page ETag with the next offset.          |
| Total people                  | integer       | How many people match in total at this company.       |
| Includes personal identifiers | boolean       | Whether the returned rows carry personal identifiers. |

#### Get Worker

Read one person's full Paychex record: demographics, employment, job, organization and supervisor.

**Required permissions:** `read:workers`.

**Inputs**

| Field                           | Type            | Required | Description                                                                                                                         |
| ------------------------------- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Company (for the person picker) | select (string) | No       | Pick a company to load its people into the picker below. Not part of the request itself. Options load from the selected connection. |
| Person                          | select (string) | Yes      | The person whose full record you want. Options load from the selected connection.                                                   |
| Include personal identifiers    | boolean         | No       | Off by default. Turn on only if you need Social Security number, date of birth, sex and ethnicity. Default: false.                  |

**Outputs**

| Field                         | Type    | Description                                              |
| ----------------------------- | ------- | -------------------------------------------------------- |
| Worker ID                     | string  | The person's Paychex worker id.                          |
| Employee ID                   | string  | The payroll number your company assigned.                |
| Name                          | string  | The person's name.                                       |
| Worker type                   | string  | Employee (W2) or independent contractor (1099).          |
| Status                        | string  | Whether the person is active, in progress or terminated. |
| Hire date                     | string  | When the person was hired.                               |
| Job title                     | string  | The person's job title.                                  |
| Organization                  | string  | The department or unit the person belongs to.            |
| Supervisor                    | string  | Who this person reports to.                              |
| Social Security number        | string  | Only present when personal identifiers were requested.   |
| Date of birth                 | string  | Only present when personal identifiers were requested.   |
| Sex                           | string  | Only present when personal identifiers were requested.   |
| Ethnicity code                | string  | Only present when personal identifiers were requested.   |
| Includes personal identifiers | boolean | Whether the record carries personal identifiers.         |

#### Add Worker

Create a new hire in Paychex as an in-progress worker, ready to be finished in Paychex Flex. The new record is not payable until you complete it there.

**Required permissions:** `write:company_people`.

**Inputs**

| Field                    | Type            | Required | Description                                                                                                                                                     |
| ------------------------ | --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Company                  | select (string) | Yes      | The Paychex company to add this person to. Companies these credentials cannot reach are marked in the list. Options load from the selected connection.          |
| First name               | string          | Yes      | The new hire's first name.                                                                                                                                      |
| Last name                | string          | Yes      | The new hire's last name.                                                                                                                                       |
| Worker type              | select (string) | Yes      | Whether this person is an employee (W2) or an independent contractor (1099). Available values: Employee (W2), Independent contractor (1099). Default: EMPLOYEE. |
| Middle name              | string          | No       | The new hire's middle name.                                                                                                                                     |
| Employee ID              | string          | No       | Your own payroll number for this person, if you assign them.                                                                                                    |
| Hire date                | date            | No       | The date this person's status takes effect.                                                                                                                     |
| Employment type          | string          | No       | Full time, part time or whatever your company uses. Leave blank to let Paychex decide.                                                                          |
| Add personal identifiers | boolean         | No       | Turn on to also send date of birth and ethnicity code. Social Security number is never sent from here; add it in Paychex Flex. Default: false.                  |
| Date of birth            | date            | No       | Only if you must set it now.                                                                                                                                    |
| Ethnicity code           | string          | No       | Only if your company records this for EEO reporting.                                                                                                            |
| Correlation ID           | string          | No       | Your own reference for this create, echoed back by Paychex. Generated for you if left blank.                                                                    |

**Outputs**

| Field             | Type    | Description                                                   |
| ----------------- | ------- | ------------------------------------------------------------- |
| Worker ID         | string  | The new person's Paychex worker id.                           |
| Employee ID       | string  | The payroll number now on the record.                         |
| Name              | string  | The name Paychex recorded.                                    |
| Worker type       | string  | Employee (W2) or independent contractor (1099), as recorded.  |
| Status            | string  | Expected to be in progress: the record still needs finishing. |
| Status reason     | string  | Why the record is in that status.                             |
| Ready for payroll | boolean | False until the record is completed in Paychex Flex.          |
| Correlation ID    | string  | The reference sent with this create.                          |

#### List Pay Components

List the earnings and deductions a Paychex company has set up, or the ones assigned to one person.

**Required permissions:** `read:company_people`, `read:workers`.

**Inputs**

| Field         | Type            | Required | Description                                                                                                                                      |
| ------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| Company       | select (string) | No       | The Paychex company whose pay components you want. Not needed if you pick a person instead. Options load from the selected connection.           |
| Person        | select (string) | No       | Leave empty for the company's whole catalogue, or pick a person to see only what is assigned to them. Options load from the selected connection. |
| Effect on pay | string          | No       | Narrow to one kind of component, for example deductions only.                                                                                    |
| As of date    | date            | No       | Show the components that were in effect on this date.                                                                                            |
| Max results   | integer         | No       | Most components to return. Minimum: 1. Maximum: 200. Default: 25.                                                                                |
| Start at      | integer         | No       | Continue a previous listing from where it stopped. Default: 0.                                                                                   |
| Page ETag     | string          | No       | Paste the Page ETag from the previous call so the list does not shift between pages.                                                             |

**Outputs**

| Field          | Type          | Description                                                            |
| -------------- | ------------- | ---------------------------------------------------------------------- |
| Pay components | object\_array | The matching pay components.                                           |
| Next offset    | integer       | Pass back as Start at to fetch more components.                        |
| Page ETag      | string        | Pass back as Page ETag with the next offset.                           |
| Scope          | string        | Whether these are the company's catalogue or one person's assignments. |

#### List Checks

List the paychecks for a Paychex pay period. Leave the pay period empty and the most recent finished one is used.

**Required permissions:** `read:company_people`.

**Inputs**

| Field       | Type            | Required | Description                                                                                        |
| ----------- | --------------- | -------- | -------------------------------------------------------------------------------------------------- |
| Company     | select (string) | Yes      | The Paychex company whose checks you want. Options load from the selected connection.              |
| Pay period  | select (string) | No       | Leave empty to use the most recent finished pay period. Options load from the selected connection. |
| Max results | integer         | No       | Most checks to return. Minimum: 1. Maximum: 200. Default: 25.                                      |
| Start at    | integer         | No       | Continue a previous listing from where it stopped. Minimum: 0. Default: 0.                         |
| Page ETag   | string          | No       | Paste the Page ETag from the previous call so the list does not shift between pages.               |

**Outputs**

| Field            | Type          | Description                                  |
| ---------------- | ------------- | -------------------------------------------- |
| Checks           | object\_array | The payroll checks in this pay period.       |
| Next offset      | integer       | Pass back as Start at to fetch more checks.  |
| Page ETag        | string        | Pass back as Page ETag with the next offset. |
| Pay period used  | string        | Which pay period these checks came from.     |
| Pay period dates | string        | The dates the pay period covers.             |

### Important behavior

Actions that create, update, send, or delete data can change the connected service. Review their inputs before running them. A retry can repeat an operation; consider this when configuring retries for actions that change data.

The catalog lists the fields and capabilities available in the supplied provider definition. Availability can also depend on your deployment and organization’s Feature Access settings.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/integrations/catalog/paychex.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
