Payroll systems · ADP
ADP RUN
ADP's own documentation covers employees, pay statements, deduction write, bank account write, hours and webhooks through the API. Access: ADP Marketplace partner.
Integration method grade A · field-level docs NOT publicly readable · last verified 2026-09-26 · Deduction Instructions API Guide for RUN Powered by ADP (PDF, marked proprietary)
What the API lets you do
| Question | Answer | Conf | What the documentation says |
|---|---|---|---|
| How do you get API access? | ADP Marketplace partner | D | Partners use the Partner Self-Service Portal for projects, sandbox, mutual-TLS certificate and consent link; 'You will not be able to complete your integration without an executed DPA'. Clients subscribe and consent to the partner app. The RUN API guides are PDFs marked proprietary. Source |
| Can you read employees and pay rates? | Yes — Workers API | D | GET /hr/v2/workers retrieves worker data including hire dates and workAssignments/baseRemuneration ('base or primary pay'). Source |
| Can you read pay statements? | Yes — Payroll Output API | D | GET /payroll/v1/payroll-output/{payruncode} 'includes active and terminated employees' payment information by the payrun period', with earnings, statutory deductions and deduction amounts. Source |
| Can you write a deduction? | Yes — start / change / stop | D | POST worker-general-deduction-instruction.start, .change and .stop for deductions already configured at company level; garnishments are read-only. Source |
| Can you write a direct deposit account? | Yes — pay-distribution.change | D | POST worker.pay-distribution.change adds, updates and deletes direct deposits, with a prenote-bypass flag for partner-verified accounts. Source |
| Can you read W-2s? | Unverified | U | The RUN API catalogue lists no W-2 or tax-statement API. |
| Can you read hours worked? | Write only (Pay Data Input) | D | pay-data-input.add imports timesheet hours and earnings for an open pay period; no worked-time read source was found. Source |
| Does it push change events? | Event notifications | D | 'ADP applications trigger notifications when data is updated'; a known issue says start, change and stop made via the API do not trigger notifications. Source |
| How does an integration authenticate? | OAuth 2.0 + mutual TLS | D | client_credentials tokens from accounts.adp.com; every call must use the mutual SSL certificate. 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/general-deduction returns deductions and garnishments; 'Deductions with the amount of 0 are not yet scheduled.' |
| Deduction write | API (event POSTs) | D | start, change and stop events, each with a /meta call; 'Passing Partial Amount through API is Not Supported'; garnishments cannot be updated. |
| Pre-tax vs post-tax at write | Inherited from code | D | Taxability comes from the chosen code — ADP separates pre-tax and post-tax insurance categories; the request has no taxability field. |
| Amount vs percent | Both; code-dependent | D | 'Deductions can be a flat dollar amount or a percentage', via currencyCode=USD or unitCode=Percent, with distinct codes (e.g. MISC vs MISCP). |
| Effective dating | No date; next payroll | D | 'Newly scheduled deductions are in effect for the next payroll cycle'; a known issue says the API 'cannot set the pay period' — UI only. |
| Retro adjustment | Unverified | U | No retro behaviour in the deduction guide; adjustment runs are mentioned for corrections, not deduction retro. |
| Employer contribution | Modelled as a deduction code | D | Retirement codes include 'Employer Contribution to 401(k) $/%' and 'SEP IRA $ (Employer Paid)'. |
| Code taxonomy shape | Hybrid | D | ADP defines the categories and codes; 'Deduction Categories and deductions are set-up at the company level'. |
| Auth model | OAuth 2.0 + mutual TLS | D | Subscriber access token via client_credentials with the mutual SSL certificate and registered scopes. |
| Data freshness | Near real time; cache lag | D | A known issue reports a delay 'at least longer than 4 minutes' before a change appears in GET; the workaround is a unique preventCache parameter. |
D vendor-documented · U unverified · — not offered. See every payroll system side by side in the Payroll API Capability Matrix.