Write-back · reference
Can you push a deduction to ADP Workforce Now through the API, or do you have to use a file?
Through the API — ADP documents deduction start, change and stop events for Workforce Now — but the API cannot create pre-tax codes, cannot model an employer contribution, cannot adjust retroactively, and reading the resulting actuals back requires a different API, a report, or a file after all.
By Eli Wilson · Published
The API works. The question is worth asking anyway, because the answer has more edges than a yes.
What the API does
ADP documents deduction writes as events rather than resource updates:
worker-general-deduction-instruction.start, .change and .stop, each paired with a /meta
endpoint that returns the valid codelist for that tenant. Reads come from
GET /payroll/v1/workers/{aoid}/payroll-instructions, which supports an asOfDate parameter
and can return future-dated and inactive deductions.
Required on write: effectiveDateTime, the deduction itemID from the codelist, and
deductionRate/rateValue.
What it does not do
This is the useful part of the answer.
| Cannot | Detail |
|---|---|
| Create a pre-tax code | Client completes an authorization form; ADP sets it up and notifies them |
| Model an employer contribution | No object. An ADP account manager builds a ×-1.00 calculation producing an earning |
| Adjust retroactively | US1395538: goal ACCRUED and ADJUSTMENT fields unsupported, no workaround |
| State its own unit | rateValue is AMOUNT / PERCENT; codes 81–96 are percent, others amount |
| Handle several categories | Direct Deposit, School District Tax, Medicare Surtax and liens are out of scope |
| Guarantee code discovery | US1294444: new post-tax OTO codes absent from the codelist, no workaround |
And a file may still appear
ADP’s guide offers three ways to retrieve what payroll actually did after a run: the Payroll
Data Output APIs, an ADP report the client builds pulling PayDate, Deduction Code,
Deduction Amount and employee name, or asking the client to provide a payroll register.
So the honest shape is: API for the write, and possibly a report or a file for the reconciliation. Products that treat the write as the whole integration discover this at the first month-end.
Dated evidence table
| Documented evidence | ADP documents the three event endpoints with practitioner roleCode, the required write fields, asOfDate on read, the three post-run retrieval routes, the authorization-form requirement for pre-tax, the ×-1.00 contribution mechanism, and known issues US1294444, US1390613, US1395531 and US1395538. Checked 2026-09-10; guide last modified 2022-09-22. |
| Strongest example | ADP’s own recommendation to obtain a payroll register from the client for reconciliation — a file, in the documentation for the API. |
| What remains unproven | Everything about live behaviour and latency. Whether the four documented known issues still apply; Chapter 1 states one Chapter 8 limitation was later removed, so the list is not current. |
The scorecard
- Is the write an API call? Yes, event-based.
- Is the read of actuals an API call? Partly — a separate API, or a report, or a file.
- Is code setup in scope? No. Budget onboarding time for the employer’s practitioner.
- Are the known issues published? Yes, which is more than most vendors do — read Chapter 8 before estimating.
- Which ADP product is it? Confirm explicitly. Workforce Now, RUN, Vantage, Enterprise HR and Next Gen are separate contracts with separate guides.
Frequently asked
- Do I have to do anything before the first write?
- Yes. The client must ensure the deduction codes your application uses are set up in ADP Workforce Now, with frequency configured as either OTO for one-time or EPR for every payroll, plus accumulators. That configuration applies to all workers and is not something the API does.
- Is one-time different from recurring?
- Yes, and it is configured on the code rather than chosen at write time — frequency OTO is one-time, EPR is every payroll or process. Note the documented gap: a new post-tax code with OTO frequency does not appear in the meta codelist, per known issue US1294444, with no workaround.
Source limits
Not verified hands-on; we have written nothing to an ADP tenant. We have not established ADP's authentication model, which is documented separately and which we have not read, so we cannot say what obtaining practitioner-scoped credentials involves in practice. Latency between a successful write and the deduction appearing in a payroll run is not documented and not measured. This is Workforce Now only — RUN, Vantage, Enterprise HR and Next Gen have their own separate deduction guides.
Sources checked
| Source | Publisher | Document date | We checked |
|---|---|---|---|
| Deduction Instruction API Guide for ADP Workforce Now | ADP | 2022-09-22 | 2026-09-10 |
| Deduction Instruction API Guide for ADP Workforce Now — Chapter 8, Known Issues | ADP | 2022-09-22 | 2026-09-10 |
Wrong or out of date? payrolldataspecs@gmail.com — corrections are free. How claims are scored: methodology.