Payroll systems · ADP
ADP Workforce Now
ADP's own documentation covers employees, pay statements, deduction write, bank account write, hours and webhooks through the API. Access: Partner or paid client program.
Integration method grade A · field-level docs publicly readable · last verified 2026-09-10 · Deduction Instruction API Guide for ADP Workforce Now
What the API lets you do
| Question | Answer | Conf | What the documentation says |
|---|---|---|---|
| How do you get API access? | Partner or paid client program | D | Requires a developer agreement with ADP; consumers are ADP API Central clients or ADP Marketplace partners (via Partner Self-Service and a Marketplace Technical Advisor). Source |
| Can you read employees and pay rates? | Yes — Workers API | D | GET /hr/v2/workers and /hr/v2/workers/{aoid}; a separate Workers – Compensation Management API is listed. Source |
| Can you read pay statements? | Yes — Pay Statements API | D | GET /payroll/v1/workers/{aoid}/organizational-pay-statements returns gross, net, earnings, deductions and YTD, with a statement image endpoint. The run-level Payroll Output API is 'limited for use by Marketplace Partner's only'. Source |
| Can you write a deduction? | Yes — Deduction Instruction API | D | POST /events/payroll/v2/worker-general-deduction-instruction.start, .change and .stop. Source |
| Can you write a direct deposit account? | Yes — Pay Distributions API | D | POST /events/payroll/v1/worker.pay-distribution.change changes direct deposit; GET /payroll/v2/workers/{aoid}/pay-distributions reads it. Source |
| Can you read W-2s? | Unverified | U | The WFN catalogue and inventory list no W-2 or tax-statement API; Tax Statements APIs appear only for other ADP products. US Tax Profiles are withholding elections, not documents. |
| Can you read hours worked? | Yes — team time cards | D | GET /time/v2/workers/{aoid}/team-time-cards?$expand=dayEntries; POST /events/time/v2/time-entries.modify uploads time entries. Source |
| Does it push change events? | Yes — queue or webhook | D | Event notifications (e.g. worker.hire) are polled from a subscriber queue or pushed to a webhook endpoint, subscribed through API Central or the Marketplace Technical Advisor. Source |
| How does an integration authenticate? | OAuth 2.0 + mutual TLS | D | Mutual SSL with a CSR signed by the ADP CA; access tokens via client_credentials over the mutual-TLS connection. Source |
Deduction write, in detail
For benefits, HSA/FSA and 401(k) integrations. 1 of 10 fields are unverified — no public source states the answer. Compare every system on the deduction write detail page.
| Field | Value | Conf | Note — and what a correct answer needed |
|---|---|---|---|
| Deduction read | Yes — API | D | GET /payroll/v1/workers/{aoid}/payroll-instructions returns deductions, supports asOfDate, and can return future-dated and inactive deductions. Post-run actuals come from the separate Payroll Data Output APIs. |
| Deduction write | API | D | Deduction Instruction API, as start / change / stop events at /events/payroll/v2/worker-general-deduction-instruction.* |
| Pre-tax vs post-tax at write | Not assertable on write | D | The API handles only the Pre-tax and Post-tax categories, and a pre-tax code cannot be created programmatically: the client completes an ADP authorization form and ADP sets the code up. The write selects an existing code and inherits its treatment. Direct Deposit, School District Tax, Medicare Surtax and Liens are explicitly out of scope. |
| Amount vs percent | Both — resolved by code number | D | One field, deductionRate/rateValue, is labelled AMOUNT / PERCENT. Codes 81 through 96 are treated as percentages, all other codes as flat amounts. deductionRate/unitCode exists in the schema and is marked "Not Displayed", so the payload is not self-describing. |
| Effective dating | Yes — effectiveDateTime | D | Required on start and change. Known issue US1395531: the GET response returns the field as effectiveDateDate rather than effectiveDate under workAssignmentStatus, with no workaround available. |
| Retro adjustment | Not supported via API | D | Known issue US1395538: the goal ACCRUED and ADJUSTMENT fields are not supported from the API, no workaround. US1390613: the write payload uses goalBalanceAmount where the meta response specifies GoalAccruedAmount, no workaround. |
| Employer contribution | No contribution object | D | Recorded only via a custom calculation an ADP account manager must build, multiplying the employee deduction by -1.00 to produce an earnings code. The earning is added to the paycheck, taxed, and removed, so the employee never receives it. |
| Code taxonomy shape | Company-defined | D | Consumers must validate a code against the meta codeList before building a write payload. Known issue US1294444: a newly added Post-tax code with frequency OTO does not return in that codelist. |
| Auth model | Unverified | U | Not established from the deduction guide. ADP documents authentication in a separate guide we have not yet assessed; we will not assert an auth model we have not read. |
| Data freshness | Post-run, no stated SLA | D | The guide directs integrators to the Payroll Data Output APIs after each payroll job, or to an ADP Report, or to a payroll register file. No latency is stated for any of the three. |
D vendor-documented · U unverified · — not offered. See every payroll system side by side in the Payroll API Capability Matrix.