Paylocity payroll, punch and earned-wage APIs

Paylocity · Business

Paylocity is the mobile companion to Paylocity's human-capital-management platform, used across the United States by hourly workers, supervisors and payroll administrators. Employees clock in and out, check upcoming shifts, review pay history and draw earned wages before payday; payroll teams track active runs and the cash each run needs. It is the everyday front end to the company's payroll, time and scheduling systems.

As a data source, the app exposes that workforce record as callable data: clock punches with a signed timestamp and geolocation, payroll run totals across gross, net, deductions and taxes, per-bank funding amounts with accountNumberLastFour and totalEft, assigned shifts with position and costCenters, earned-wage payouts carrying a paymentFeeAmount, and year-to-date retirement contributions. openData Studio turns this layer into open data that treasury, workforce-management and benefits integrations use to verify payroll funding, reconcile time against schedules and price early-wage transfers.

Paylocity is the employee and manager companion to Paylocity's US human-capital-management platform: workers clock in, read their schedules, pull pay history and request earned wages, while payroll administrators review in-flight runs and the cash needed to fund them. Behind those screens sits a workforce dataset — signed time punches with geolocation, payroll run totals with gross-to-net breakdowns, per-bank funding amounts, shift rosters and retirement contributions. Treasury, workforce and benefits tools build on it to verify payroll funding, reconcile punches against schedules and quote early-wage payouts.

Screenshots

API surface

The endpoints and request/response examples below are reconstructed from the app's interface — illustrative, not a live capture.

Company login (jwt and gateway token)
POST /v1/auth/login osint
Signs the worker or payroll admin into a company and returns jwt, gatewayToken, refreshToken, sessionId plus the company and user envelopes that every later payroll, punch and schedule call is scoped to.
Auth: Company code plus userName/password, or a PKCE code with codeChallenge, codeChallengeMethod and codeChallengeVerifier. No prior Bearer. The returned jwt is sent as Authorization: Bearer on later calls; gatewayToken is stored on the session.
- jwt
- gatewayToken
- refreshToken
- sessionId
- accessTokenExpiration
- company
- user
- companyCode
- employeeId
- email
- identityKey
```
POST /v1/auth/login HTTP/1.1
Content-Type: application/json

{
  "mode": "password",
  "company": "B1234",
  "userName": "jdoe",
  "password": "******"
}
```
```
{
  "data": {
    "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "gatewayToken": "gwt-8f21c4a0",
    "refreshToken": "rt-c91e2b77",
    "sessionId": "sess-10432",
    "accessTokenExpiration": "2026-09-29T18:40:00Z",
    "company": {"companyCode": "B1234", "companyName": "Acme Manufacturing", "doingBusinessAs": "Acme", "companySet": "prod-us"},
    "user": {"email": "[email protected]", "employeeId": "E-10432", "firstName": "Jane", "lastName": "Doe", "userName": "jdoe", "isSupervisor": false, "identityKey": "idk-77a1"}
  },
  "errors": []
}
```
- reconstructed from the app's sign-in and company-selection flow
- matches the session envelope attached to every payroll, punch and schedule call
Refresh login tokens
POST /v1/auth/token/refresh opendata
Rotates jwt, gatewayToken and refreshToken so the signed-in session stays alive across the accessTokenExpiration window without another password prompt.
Auth: Body carries the refreshToken from POST /v1/auth/login. Replaces the expired jwt without re-entering the password.
- jwt
- gatewayToken
- refreshToken
- sessionId
- accessTokenExpiration
```
POST /v1/auth/token/refresh HTTP/1.1
Content-Type: application/json

{
  "refreshToken": "rt-c91e2b77",
  "company": "B1234"
}
```
```
{
  "data": {
    "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "gatewayToken": "gwt-8f21c4a0",
    "refreshToken": "rt-d02f3c88",
    "sessionId": "sess-10432",
    "accessTokenExpiration": "2026-09-29T22:40:00Z"
  },
  "errors": []
}
```
- reconstructed from the app's silent session renewal flow

User and company context

GET /v1/accounts/{companyId}/context osint

Reloads the signed-in company and user envelope — companyCode, employeeId, supervisor and terminated flags, feature toggles — used to gate payroll, punch and earned-wage screens after a token refresh.

Auth: Authorization: Bearer <jwt> from POST /v1/auth/login. companyId is the companyCode from the login envelope.

company
user
toggles
myPaylocity
companyCode
employeeId
isSupervisor
isTerminated
payType
personId

GET /v1/accounts/B1234/context HTTP/1.1
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

{
  "data": {
    "company": {"companyCode": "B1234", "companyName": "Acme Manufacturing", "doingBusinessAs": "Acme", "companySet": "prod-us"},
    "user": {"email": "[email protected]", "employeeId": "E-10432", "firstName": "Jane", "lastName": "Doe", "userName": "jdoe", "isSupervisor": false, "isTerminated": false, "payType": "hourly", "personId": "P-88120"},
    "toggles": [{"name": "earnedWageAccess", "enabled": true}],
    "myPaylocity": {"enabled": true}
  }
}

reconstructed from the account bootstrap that runs after sign-in and token refresh

Home dashboard

GET /v1/accounts/{companyId}/dashboard opendata

Returns the signed-in home feed: quick-action chips, latest punch state, open tasks, time-off, W-2 filing, retirement and team widgets that the dashboard renders after login.

Auth: Authorization: Bearer <jwt> from POST /v1/auth/login.

quickActions
punch
tasks
timeOff
w2TaxFiling
retirement
socialCarousel
calendar
myTeam

GET /v1/accounts/B1234/dashboard HTTP/1.1
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

{
  "data": {
    "quickActions": {"chips": ["punch", "payHistory", "timeOff"]},
    "punch": {"latestPunchType": "in", "canPunch": true},
    "tasks": {"count": 2},
    "timeOff": {"upcoming": []},
    "w2TaxFiling": {"available": true},
    "retirement": {"hasProfile": true},
    "socialCarousel": {"items": []}
  }
}

reconstructed from the home screen's widget feed

Active payroll runs
GET /v1/accounts/{companyId}/payroll-runs openfinance
Lists the company's in-flight payroll runs — check date, period begin/end, off-cycle flag, pay schedule — that the payroll home screen pages through.
Auth: Authorization: Bearer <jwt> from POST /v1/auth/login. companyId is the signed-in companyCode.
- id
- checkDate
- periodBegin
- periodEnd
- isOffCycle
- payScheduleId
- payFrequency
```
GET /v1/accounts/B1234/payroll-runs HTTP/1.1
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
```
```
{
  "items": [
    {
      "id": "PR-2026-09-25",
      "checkDate": "2026-09-25",
      "periodBegin": "2026-09-08",
      "periodEnd": "2026-09-21",
      "isOffCycle": false,
      "payScheduleId": "PS-WEEKLY",
      "payFrequency": "weekly"
    }
  ]
}
```
- reconstructed from the payroll home screen's run list
Payroll run summary
GET /v1/accounts/{companyId}/payroll-runs/{payrollId}/totals openfinance
Returns headline totals for one payroll run: batch and employee counts, hours, live vs direct-deposit check counts, and cash amounts (gross, net, earnings, deductions, taxes).
Auth: Authorization: Bearer <jwt> from POST /v1/auth/login.
- payrollId
- batchCount
- employeeCount
- hours
- checkCounts
- directDeposit
- live
- cashAmounts
- gross
- net
- earnings
- deductions
- taxes
```
GET /v1/accounts/B1234/payroll-runs/PR-2026-09-25/totals HTTP/1.1
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
```
```
{
  "payrollId": "PR-2026-09-25",
  "batchCount": 3,
  "employeeCount": 412,
  "hours": 16480.50,
  "checkCounts": {"directDeposit": 390, "live": 22},
  "cashAmounts": {"gross": 1854320.11, "net": 1422100.44, "earnings": 1854320.11, "deductions": 210400.20, "taxes": 221819.47}
}
```
- reconstructed from the payroll run detail header totals
Payroll cash requirements
GET /v1/accounts/{companyId}/payroll-runs/{payrollId}/funding openbanking
Shows the cash the company must have on hand to fund a payroll: per-bank EFT and check totals (last-four account) plus liability buckets for direct deposit, tax, agency and payroll.
Auth: Authorization: Bearer <jwt> from POST /v1/auth/login. Payroll-admin session.
- bankingSummary
- accountNumberLastFour
- totalEft
- totalChecks
- liabilities
- directDeposit
- tax
- agency
- payroll
```
GET /v1/accounts/B1234/payroll-runs/PR-2026-09-25/funding HTTP/1.1
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
```
```
{
  "bankingSummary": [
    {
      "name": "Operating - Wells Fargo",
      "accountNumberLastFour": "4421",
      "totalEft": 1385400.12,
      "totalChecks": 36700.32
    }
  ],
  "liabilities": {
    "directDeposit": {"amount": 1385400.12},
    "tax": {"amount": 221819.47},
    "agency": {"amount": 18400.00},
    "payroll": {"amount": 36700.32}
  }
}
```
- reconstructed from the funding review shown to administrators before a payroll run is released

Create a time punch

POST /v1/accounts/{companyId}/employees/{employeeId}/clock-events opendata

Records a clock-in or clock-out for the signed-in employee, with signed timestamp, punch type, optional note, geolocation and cost-center ids — the write side of the punch button.

Auth: Authorization: Bearer <jwt> from POST /v1/auth/login. employeeId is the signed-in worker.

timestamp
type
note
isManual
source
geolocation
costCenterIds
punchId

POST /v1/accounts/B1234/employees/E-10432/clock-events HTTP/1.1
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "timestamp": {"value": "2026-09-29T12:01:04Z", "signature": "sig-aa12"},
  "type": "in",
  "note": "",
  "isManual": false,
  "source": "mobile",
  "geolocation": {"latitude": 41.8781, "longitude": -87.6298},
  "costCenterIds": ["CC-OPS"]
}

{
  "punchId": "PCH-99120",
  "timestamp": "2026-09-29T12:01:04Z",
  "type": "in",
  "isManual": false,
  "source": "mobile"
}

reconstructed from the mobile punch button's write flow

Employee pay periods
GET /v1/accounts/{companyId}/employees/{employeeId}/work-periods opendata
Lists the employee's pay-period windows (startDate, endDate) that the timesheet and punch history screens page by.
Auth: Authorization: Bearer <jwt> from POST /v1/auth/login.
- startDate
- endDate
```
GET /v1/accounts/B1234/employees/E-10432/work-periods HTTP/1.1
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
```
```
{
  "items": [
    {"startDate": "2026-09-08T00:00:00Z", "endDate": "2026-09-21T23:59:59Z"},
    {"startDate": "2026-09-22T00:00:00Z", "endDate": "2026-10-05T23:59:59Z"}
  ]
}
```
- reconstructed from the timesheet and punch-history paging

My schedule shifts

GET /v1/accounts/{companyId}/employees/{employeeId}/roster opendata

Returns the signed-in employee's assigned shifts — id, type, duration, date range, job position and cost centers — behind the My Schedule screen.

Auth: Authorization: Bearer <jwt> from POST /v1/auth/login.

items
id
type
duration
date
position
costCenters
status

GET /v1/accounts/B1234/employees/E-10432/roster HTTP/1.1
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

{
  "items": [
    {
      "id": "SH-44120",
      "type": "shift",
      "duration": {"hours": 8, "minutes": 0},
      "date": {"start": "2026-09-29T13:00:00Z", "end": "2026-09-29T21:00:00Z"},
      "position": {"name": "Line Operator"},
      "costCenters": [{"id": "CC-OPS", "name": "Operations"}],
      "status": "scheduled"
    }
  ]
}

reconstructed from the My Schedule screen

Earned-wage payments
GET /v1/accounts/{companyId}/employees/{employeeId}/wage-advances openfinance
Lists earned-wage transfers the employee has already taken this period — amount, fee, status, transfer time and the payroll date the amount will be deducted.
Auth: Authorization: Bearer <jwt> from POST /v1/auth/login. Feature gated by the earnedWageAccess toggle on the account context.
- paymentId
- paymentDateTimeUtc
- paymentStatus
- paymentAmount
- transferFeeAmount
- payrollDeductionDate
- transferredDateTimeUtc
```
GET /v1/accounts/B1234/employees/E-10432/wage-advances HTTP/1.1
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
```
```
{
  "items": [
    {
      "paymentId": "EWA-70012",
      "paymentDateTimeUtc": "2026-09-24T16:12:00Z",
      "paymentStatus": "completed",
      "paymentAmount": 150.00,
      "transferFeeAmount": 2.99,
      "payrollDeductionDate": "2026-09-25T00:00:00Z",
      "transferredDateTimeUtc": "2026-09-24T16:40:00Z"
    }
  ]
}
```
- reconstructed from the earned-wage history list
Earned-wage payment preview
POST /v1/accounts/{companyId}/employees/{employeeId}/wage-advance-quotes openfinance
Quotes fee and total for an earned-wage transfer of a given amount and speed against a saved payment method, before the employee confirms the payout.
Auth: Authorization: Bearer <jwt> from POST /v1/auth/login.
- paymentMethodId
- paymentTransferSpeed
- paymentAmount
- paymentPreviewId
- paymentFeeAmount
- totalPaymentAmount
- transferByDate
- paymentOption
```
POST /v1/accounts/B1234/employees/E-10432/wage-advance-quotes HTTP/1.1
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "paymentMethodId": 4412,
  "paymentTransferSpeed": "instant",
  "paymentAmount": 125.00
}
```
```
{
  "paymentPreviewId": 88021,
  "paymentAmount": 125.00,
  "paymentFeeAmount": 2.99,
  "totalPaymentAmount": 127.99,
  "transferByDate": "2026-09-29T18:00:00Z",
  "paymentOption": {"code": "instant"}
}
```
- reconstructed from the early-wage confirmation sheet's fee quote step
Retirement contribution profile
GET /v1/accounts/{companyId}/assignments/{assignmentId}/retirement-summary openfinance
Reads the worker's retirement contribution profile from pay history — pre-tax and Roth plans plus year-to-date employee and employer amounts — shown on the retirement card.
Auth: Authorization: Bearer <jwt> from POST /v1/auth/login. assignmentId is the worker's payroll assignment.
- companyId
- assignmentId
- currency
- preTax
- roth
- yearToDateContributions
```
GET /v1/accounts/B1234/assignments/AS-10432/retirement-summary HTTP/1.1
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
```
```
{
  "companyId": "B1234",
  "assignmentId": "AS-10432",
  "currency": "USD",
  "preTax": [{"planName": "401(k)", "percent": 6.0}],
  "roth": [{"planName": "Roth 401(k)", "percent": 2.0}],
  "yearToDateContributions": {"employee": 4200.00, "employer": 2100.00}
}
```
- reconstructed from the retirement card in pay history

Where teams use this data

Payroll cash-funding check
A treasury bot signs in as a payroll admin, lists in-flight runs at GET /v1/accounts/{companyId}/payroll-runs, then reads GET /v1/accounts/{companyId}/payroll-runs/{payrollId}/funding for accountNumberLastFour, totalEft and tax liabilities before releasing the ACH file.
Clock and schedule reconciliation
A workforce system posts punches to POST /v1/accounts/{companyId}/employees/{employeeId}/clock-events and diffs them against GET /v1/accounts/{companyId}/employees/{employeeId}/roster (duration, position, costCenters) for the same pay period from GET /v1/accounts/{companyId}/employees/{employeeId}/work-periods.
Earned-wage payout quote
Before a worker confirms an early wage, the client POSTs paymentAmount and paymentTransferSpeed to /v1/accounts/{companyId}/employees/{employeeId}/wage-advance-quotes and shows paymentFeeAmount plus totalPaymentAmount; prior transfers come from GET .../wage-advances.
Retirement year-to-date card
The benefits screen calls GET /v1/accounts/{companyId}/assignments/{assignmentId}/retirement-summary for preTax, roth and yearToDateContributions and paints them next to the home retirement widget from GET /v1/accounts/{companyId}/dashboard.

Frequently asked questions

How does Paylocity authenticate API calls?

POST /v1/auth/login accepts company, userName and password (or a PKCE code) and returns jwt, gatewayToken, refreshToken and sessionId. Later calls send Authorization: Bearer <jwt>. POST /v1/auth/token/refresh rotates the tokens; GET /v1/accounts/{companyId}/context reloads company, user and feature toggles.

Which payroll amounts are exposed?

GET /v1/accounts/{companyId}/payroll-runs lists in-flight runs (checkDate, periodBegin, periodEnd). GET .../payroll-runs/{payrollId}/totals returns gross, net, earnings, deductions, taxes and live vs direct-deposit check counts. GET /v1/accounts/{companyId}/payroll-runs/{payrollId}/funding adds per-bank totalEft, totalChecks and accountNumberLastFour plus tax and direct-deposit liabilities.

Can workers clock in and read their schedule?

Yes. POST /v1/accounts/{companyId}/employees/{employeeId}/clock-events records a punch with signed timestamp, type and geolocation. Pay-period windows come from GET /v1/accounts/{companyId}/employees/{employeeId}/work-periods. Assigned shifts are GET /v1/accounts/{companyId}/employees/{employeeId}/roster.

Apps similar to Paylocity

ADP Mobile Solutions — ADP's employee companion to its Workforce Now HCM suite, covering payroll, HR, time and talent for mid-market companies and competing with Paylocity on multi-state tax and compliance depth.
Workday — Workday is an enterprise suite that unifies HR, payroll and finance data on one system, aimed at organizations past roughly 1,000 employees.
UKG Pro — UKG is a payroll and HR platform built around scheduling and labor compliance, aimed at mid-market companies in industries like healthcare, retail, hospitality and manufacturing.
Paychex Flex — Paychex Flex bundles payroll, HR and benefits for small US businesses, with published pricing starting at $39 per month plus $5 per employee.
Gusto — Gusto is a US payroll platform with published pricing and unlimited payroll runs, aimed at small businesses of roughly 2 to 200 employees.
Paycom — Paycom is a single-database HCM platform for mid-to-large companies whose Beti feature has employees verify their own paychecks before payroll runs.
Rippling — Rippling unifies HR, IT and payroll in one system for tech-forward companies, automating work like app provisioning for new hires.

More Business apps

Topics

paylocity api
paylocity payroll
paylocity punch
earned wage access
payroll cash requirements
employee schedule api
paylocity login jwt

Need this app's data API integrated?

We deliver scoped integrations for any named app — from USD 500 with source-code handoff, or hosted access billed per call. Tell us the data you need.

NDA + SOW on every engagement
Delivery in 3–7 days
Payment only after acceptance
Work scoped to authorized use

Get a quote

Paylocity payroll, punch and earned-wage APIs

Screenshots

API surface

Company login (jwt and gateway token)

Refresh login tokens

User and company context

Home dashboard

Active payroll runs

Payroll run summary

Payroll cash requirements

Create a time punch

Employee pay periods

My schedule shifts

Earned-wage payments

Earned-wage payment preview

Retirement contribution profile

Data categories

Where teams use this data

Payroll cash-funding check

Clock and schedule reconciliation

Earned-wage payout quote

Retirement year-to-date card

Frequently asked questions

Apps similar to Paylocity

More Business apps

ADP Mobile Solutions

Box

CryptoRush: Crypto Simulator

Google Ads

Topics

Need this app's data API integrated?

Paylocity payroll, punch and earned-wage APIs

Screenshots

API surface

Company login (jwt and gateway token)

Refresh login tokens

User and company context

Home dashboard

Active payroll runs

Payroll run summary

Payroll cash requirements

Create a time punch

Employee pay periods

My schedule shifts

Earned-wage payments

Earned-wage payment preview

Retirement contribution profile

Data categories

Where teams use this data

Payroll cash-funding check

Clock and schedule reconciliation

Earned-wage payout quote

Retirement year-to-date card

Frequently asked questions

Related apps

Apps similar to Paylocity

More Business apps

ADP Mobile Solutions

Box

CryptoRush: Crypto Simulator

Google Ads

Topics

Need this app's data API integrated?