canonical: https://jentic.com/apis/paylocity.com/paylocity

# Paylocity API

The Paylocity API provides programmatic access to employee payroll and human capital management data for US employers. It covers 32 endpoints spanning employee records, earnings management, pay statements, tax configurations, direct deposit setup, benefits, and sensitive HR data. The API uses OAuth 2.0 client credentials and includes a WebLink staging endpoint for onboarding new hires in bulk.

## For AI agents

Manage employee records, retrieve pay statements, configure earnings and tax withholding, and set up direct deposits for companies using Paylocity payroll.

## Scope

Does not handle time tracking, recruiting, or benefits enrollment - use for payroll data, employee records, and compensation management only.

## Capabilities

- Retrieve detailed pay statements with earnings, deductions, and tax breakdowns by year or check date
- Manage employee earnings configurations including recurring and one-time earning codes
- Configure federal, state, and local tax withholding elections for employees
- Set up and modify direct deposit accounts with split allocations
- Create new employee records with demographics, compensation, and tax data
- Search employees by pay rate ranges or employment status across a company
- Access sensitive employee data including SSN and date of birth through elevated permissions

## Use cases

### Pay Statement Reporting

Retrieve detailed pay statement data for employees including summaries and line-by-line details by year or specific check date. The API returns gross pay, net pay, all earning codes, deductions, and tax withholdings. This powers internal dashboards, employee self-service portals, and annual compensation reporting without manual data exports from the Paylocity UI.

Example prompt: Retrieve the pay statement summary for employee {employeeId} in company {companyId} for the year 2026 via GET /v2/companies/{companyId}/employees/{employeeId}/paystatement/summary/2026

### Employee Onboarding and Data Management

Create new employee records with complete demographic, compensation, tax, and direct deposit information through the API. The WebLink staging endpoint supports bulk imports for organizations hiring at scale. Existing employee records can be updated with PATCH requests covering name changes, address updates, or role transitions.

Example prompt: Create a new employee in company {companyId} via POST /v2/companies/{companyId}/employees with name, hire date, annual salary of $65,000, and federal tax filing status of single

### Tax and Compensation Configuration

Manage all aspects of employee tax withholding including federal, primary state, non-primary state, and local tax codes. The API supports adding new local tax jurisdictions, updating withholding elections, and removing obsolete tax records. Combined with earnings management endpoints, this enables complete compensation lifecycle handling from hire through termination.

Example prompt: Add a new local tax code for employee {employeeId} in company {companyId} via POST /v2/companies/{companyId}/employees/{employeeId}/localTaxes with the jurisdiction code and withholding percentage

### AI Agent Payroll Integration via Jentic

AI agents connect to the Paylocity API through Jentic to retrieve pay data, manage employee records, and configure compensation without implementing OAuth 2.0 client credentials or handling token lifecycle management. Jentic provides intent-based search so agents find operations like 'get pay statement' and receive the complete endpoint schema ready for execution.

Example prompt: Search Jentic for 'retrieve employee pay statement', load the operation schema, and execute it for employee {employeeId} in company {companyId} for the current year

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /v2/companies/{companyId}/employees | Create a new employee record |
| GET | /v2/companies/{companyId}/employees/{employeeId} | Retrieve employee details |
| GET | /v2/companies/{companyId}/employees/{employeeId}/paystatement/details/{year} | Get detailed pay statements for a year |
| GET | /v2/companies/{companyId}/employees/{employeeId}/earnings | List employee earnings |
| GET | /v2/companies/{companyId}/employees/{employeeId}/directDeposit | Get direct deposit configuration |
| PUT | /v2/companies/{companyId}/employees/{employeeId}/primaryStateTax | Update primary state tax |
| POST | /v2/companies/{companyId}/employees/{employeeId}/localTaxes | Add local tax configuration |
| POST | /v2/weblinkstaging/companies/{companyId}/employees/newemployees | Bulk stage new employees via WebLink |

## Key resources

- **Employees** — Create, read, update employee records with demographics and employment data
- **Pay Statements** — Retrieve detailed and summary pay statement data by year or check date
- **Earnings** — Manage recurring and one-time earning codes and amounts
- **Direct Deposit** — Configure bank account routing and deposit allocations
- **Taxes** — Manage federal, state, and local tax withholding configurations
- **Sensitive Data** — Access SSN, date of birth, and other restricted employee information

## Why Jentic

- **Setup:** Wiring Paylocity by hand means running its OAuth 2.0 flow, managing scoped bearer tokens, and finding the right call across dozens of employee and pay endpoints yourself. Through Jentic you install once, import the Paylocity API from the API Directory, store the client credentials once, and your agent calls it.
- **Permission scoping:** Paylocity puts the company and employee ids in the URL path (/v2/companies/{companyId}/employees/{employeeId}), so a rule can pin your agent to one employee: it can read that employee's pay statements and earnings and nothing else. You choose the operations it may call, so writing tax settings or creating employees is not included unless you add them.
- **Credential handling:** Your Paylocity OAuth client id and secret are stored once, encrypted, by your own Jentic One instance and exchanged for scoped tokens at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'get an employee pay statement' or 'read an employee's earnings', and Jentic returns the matching Paylocity operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Paychex External API** — US payroll platform with broader endpoint coverage for checks, jobs, and webhooks
- **Gusto API** — SMB-focused payroll with integrated benefits, tax filing, and compliance
- **BambooHR API** — HR platform for employee records, time-off, and performance beyond payroll

## FAQ

### What authentication does the Paylocity API use?

The Paylocity API uses OAuth 2.0 client credentials flow. You obtain a token by posting your client ID and secret to api.paylocity.com/IdentityServer/connect/token with the WebLinkAPI scope. Through Jentic, OAuth credentials are stored in your Jentic One instance and agents receive scoped tokens automatically.

### Can I retrieve detailed pay statements with the Paylocity API?

Yes. The GET /v2/companies/{companyId}/employees/{employeeId}/paystatement/details/{year} endpoint returns line-item detail including each earning code, deduction, and tax withholding for every check in that year. You can also filter by specific check date using the /{checkDate} path suffix.

### What are the rate limits for the Paylocity API?

Paylocity enforces rate limits per OAuth client. Standard integrations are limited to approximately 5 requests per second with daily quotas based on your subscription. The API returns 429 Too Many Requests when limits are exceeded. Jentic handles rate limiting and retry logic when executing operations.

### How do I add a new employee through the Paylocity API via Jentic?

Search Jentic for 'create a new employee in payroll' to find the POST /v2/companies/{companyId}/employees operation. Jentic returns the full input schema including required fields like firstName, lastName, companyId, and employeeStatus. Execute through Jentic and it handles OAuth token acquisition. Install with pip install jentic.

### Can I manage tax withholding configurations via the API?

Yes. The API provides PUT /v2/companies/{companyId}/employees/{employeeId}/primaryStateTax for state tax, PUT /v2/companies/{companyId}/employees/{employeeId}/nonprimaryStateTax for secondary states, and POST and DELETE operations on /v2/companies/{companyId}/employees/{employeeId}/localTaxes for local jurisdictions.

### Does the Paylocity API support bulk employee imports?

Yes. The POST /v2/weblinkstaging/companies/{companyId}/employees/newemployees endpoint stages multiple new employee records through the WebLink system. This is designed for bulk onboarding scenarios where organizations need to add many employees simultaneously during seasonal hiring or acquisitions.

### Can I limit what my agent is allowed to do with the Paylocity API?

Yes. Because you self-host Jentic One, your own rules decide which Paylocity operations and which OAuth credentials the agent may use. Paylocity places the company and employee ids in the URL path (/v2/companies/{companyId}/employees/{employeeId}), so you can pin an agent to a single employee and grant only read access to that person's pay statements and earnings. Write actions such as updating primaryStateTax, adding local taxes, or creating employees stay off limits unless you explicitly add those operations.