> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asteragents.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Paycom

> Connect Paycom to your Agents for read-only access to HR & payroll data

## Overview

The [Paycom](https://www.paycom.com) integration gives your agents **read-only** access to your Paycom HCM data. Agents can query the employee directory, individual employee records, timecard punches, positions, labor allocations, earn codes, and new hires — to build headcount and turnover KPIs, reconcile records, and feed analysis, without ever modifying anything in Paycom.

The integration is read-only by design: the underlying client only exposes `GET`, so agents cannot import punches, edit labor allocations, or change any Paycom data.

<Warning>
  **Paycom only accepts API calls from allow-listed IP addresses.** Before connecting, your Paycom administrator must add Aster's static egress IPs to the API user's IP allow-list (via **User Options > User Access and Security > API Setup > Edit User**). A call from a non-allow-listed IP returns a generic `401` regardless of whether the credentials are correct.
</Warning>

## Prerequisites

* A **Paycom** account with **API access** provisioned by your Paycom representative
* A Paycom API **SID** and **Token**, generated under **User Options > User Access and Security > API Setup**
* Aster's static egress IPs added to the API user's **IP allow-list** in Paycom
* The specific endpoints your agent needs **enabled** in Paycom's **Function Enablement** (sensitive comp/tax/SSN endpoints are off by default and require emailing `automation@paycomonline.com` to approve)
* An Aster **admin** to connect the integration (the connection is shared org-wide)

## Setup Guide

<Steps>
  <Step title="Whitelist Aster's IPs in Paycom">
    Provide Aster's static egress IPs to your Paycom representative (or add them yourself under **API Setup > Edit User > IP Address**). This must be done first, or connection will fail with a `401`.
  </Step>

  <Step title="Get API credentials from Paycom">
    In Paycom, go to **User Options > User Access and Security > API Setup**, edit the API user, and copy the **SID** and **Token**. In **Function Enablement**, enable the read endpoints your agent needs (e.g. Employee Directory, Punch History, Positions, Labor Allocation).
  </Step>

  <Step title="Connect Paycom in Aster Agents">
    Navigate to **Control Hub > Integrations**, locate the **Paycom** card, click **Connect**, and paste the SID and Token. Aster validates them against Paycom and **auto-detects your data center** (OKC / PHX / DFW), echoing back the detected data center and approximate employee count on success.
  </Step>

  <Step title="Add the tool to your agent">
    Edit your agent and enable **Paycom Query**. (This is a private tool — an admin enables it for your org under **Control Hub > Private Tools** first.)
  </Step>
</Steps>

## Available Tools

* **Paycom Query** (`paycom_query`) — Read-only `GET` against any whitelisted Paycom endpoint. Path params go inline (e.g. `api/v1/employee/A001/change`); query params (including ISO dates, auto-converted to the UNIX seconds Paycom expects) go in `params`. Auto-paginates list endpoints; **large result sets spill to a CSV attachment** while the inline payload is truncated to a token budget, so big pulls don't balloon the agent's context.

<Note>
  **Read-only.** The HTTP client only permits `GET`; write endpoints (punch import, labor-allocation mutations) are intentionally not wired up.
</Note>

### Endpoints available to the agent

Non-sensitive reads (enabled by default on most API users):

* **Employees** — `employeedirectory`, `employee/{eecode}`, `employee/{eecode}/change`, `employeeids/employeechanges`, `employee/{eecode}/customfield`
* **Timecards** — `employee/{eecode}/punchhistory`, `employee/{eecode}/punchaudit`, `clockedinoutstatus/{eecode}`
* **New hires** — `newhireids`, `newhire/{id}`
* **Positions** — `positions/detail`, `positions/levels`, `positions/seats`
* **Labor allocation & config** — `cl/laborallocationprofiles`, `cl/category/{catcode}`, `cl/earning`, `cl/locations/{id}`, `cl/establishments/{id}`

Sensitive reads (**blocked by default** in the tool, and disabled in Paycom until HR approves): employee rates by allocation, effective rates, taxes, and the sensitive record (SSN/DOB). The agent must set `allow_sensitive=true` **and** the endpoint must be enabled on the Paycom side.

## Example Prompts

Once connected, agents can answer questions like:

* "How many active employees do we have by department?"
* "List everyone hired in the last 90 days."
* "Show all timecard punches for employee A001 last week."
* "Export the full employee directory for analysis." (the full set spills to a CSV the agent can process in Python)

## Notes & Limitations

* **Read-only** — no writes in this release, by design.
* **IP allow-list required** — calls must egress from a whitelisted IP or Paycom returns `401`.
* **Endpoint enablement** — an un-enabled endpoint returns `413`; sensitive endpoints require Paycom approval.
* **Page size cap** — Paycom hard-caps `pagesize` at 500; the tool auto-paginates to reach larger totals.
* **Rate limits** — most endpoints allow \~10 calls/sec and tens of thousands of calls/day; the tool paginates sequentially to stay well within them.

## Security Considerations

* **Org-level connection** — one admin connects once for the whole organization. The Token is stored server-side and redacted when the connection is read back in the UI.
* **Private tool** — `paycom_query` is gated per-org; enable it only for the org and agents that should touch payroll data.
* **Read-only by construction** — the client cannot mutate your Paycom data.
* **Sensitive data stays off by default** — comp/tax/SSN endpoints require an explicit opt-in and Paycom-side enablement.
* **Rotate credentials** periodically by generating a new Token in Paycom and reconnecting.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection rejected with 401 / 'Api user not found'">
    * Confirm Aster's static egress IPs are on the API user's allow-list in Paycom — this is the most common cause, and the error looks identical to a bad key.
    * Double-check the SID and Token were copied exactly from **API Setup > Edit User**.
    * Confirm the API user is **Active**.
  </Accordion>

  <Accordion title="A query returns 413 (endpoint not enabled)">
    * Enable that endpoint in Paycom under **API Setup > Edit User > Function Enablement**.
    * For sensitive endpoints (rates, taxes, SSN), HR must email `automation@paycomonline.com` to approve access.
  </Accordion>

  <Accordion title="A date filter returns nothing">
    * Paycom expects UNIX-second timestamps for date params; the tool converts `YYYY-MM-DD` automatically, but confirm the window actually contains records.
  </Accordion>
</AccordionGroup>

## Related Tools

* [Run Code](/tools/execute_python) — process large Paycom result sets (the CSV spillover attachment) with pandas.