Skip to main content

​
Overview

The Paycom 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.
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.

​
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

1

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.
2

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).
3

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.
4

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.)

​
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.
Read-only. The HTTP client only permits GET; write endpoints (punch import, labor-allocation mutations) are intentionally not wired up.

​
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

  • 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.
  • 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.
  • Paycom expects UNIX-second timestamps for date params; the tool converts YYYY-MM-DD automatically, but confirm the window actually contains records.
  • Run Code — process large Paycom result sets (the CSV spillover attachment) with pandas.