How to write deductions and earnings to ADP Workforce Now

Key takeaways

• ADP Workforce Now splits payroll writes across two APIs: Payroll Data Input for a pay cycle's batch, and Deduction Instruction for standing deductions.
• Payroll Data Input only accepts entries while the payroll cycle is in Entering Payroll Information or Correcting Input, with a recommended batch of 100 rows.
• Deduction Instruction starts, changes, and stops general deductions against an effective date, so an accepted instruction keeps running until another one changes it.
• Deductions managed by ADP benefit enrollment are read-only through the API until payroll deductions are suspended for that plan.
• The earning code you write drives the FLSA regular-rate calculation used for overtime, so a miscoded bonus is a pay-accuracy bug, not a label problem.

Writing to ADP Workforce Now looks like one integration problem. It's two.

One API writes what happens in this pay cycle. The other sets what happens every cycle from now on, until something tells it to stop. Send a recurring benefits deduction through the wrong one and it either disappears after one paycheck or never starts, and you find out from an employee, not an error response.

ADP documents the two paths in separate guides, and the constraints that block a go-live sit past the field tables. This page lays out which path fits which use case, what each requires, how each runs, and the limits worth knowing before you build.

Which write path do you need?

The deciding question: does this pay item exist for one pay cycle, or should it persist until someone changes it?

A one-time bonus belongs in Payroll Data Input because it shouldn't still be there next cycle. A new HSA election belongs in Deduction Instruction because it should run every cycle until the employee changes it. Benefits elections also carry their own persistence rules before you reach ADP: under the IRS cafeteria plan rules (IRC §125), a pre-tax election generally holds for the plan year unless a qualifying change in status occurs.

If your integration writes anything a benefits platform would call an election, coverage change, or contribution rate, you want Deduction Instruction, the path behind writing benefits deductions back to payroll. If it writes a one-off adjustment to a specific run, you want Payroll Data Input.

Prerequisites before you write

Both paths share the same foundation, per ADP's guides:

• API Central access and a registered application. Calls authenticate with OAuth 2.0 client credentials plus an ADP-issued certificate for mutual TLS, and each use case's canonical scope has to be added to your application in ADP's Consumer Application Registry.
• A practitioner. Both APIs document the practitioner as the supported actor.
• Payroll menu access for Payroll Data Input. The API user needs access to Process > Payroll > Pay Data or Process > Payroll > Payroll Dashboard.

Payroll Data Input has one more setup requirement ADP lists as a known limitation: the client must have a Memo Code of 5 and an Hours & Earnings Code of T created for each active company. For the auth setup end to end, see our guide to ADP Workforce Now API architecture and authentication.

How each path writes

Payroll Data Input: one cycle's batch

Payroll Data Input sends entries into a pay data batch for a payroll cycle: earnings, deductions, reimbursements, hours, and related pay data. Per ADP's guide:

1. Check the cycle status. The request only processes while the payroll cycle is in Entering Payroll Information or Correcting Input.
2. Build the batch. Reference each employee and the earning or deduction codes you're writing. ADP recommends batches of 100 rows.
3. Map to ADP's codes, not the client's template. The API doesn't use pay data templates the client built in the UI, so a mapping built around a template has to be rebuilt against the codes.
4. Confirm before the cycle closes. Nothing carries forward, and the API doesn't support event notifications, so verify the batch landed.

PTO hours go through the same path, using the hours and earnings codes the client configured, and piece-rate workers can be paid by rate and pieces. Some Paydata columns aren't handled by the API at all; ADP lists them in the guide's appendix and points to file import as the workaround.

Deduction Instruction: standing deductions

Deduction Instruction behaves like configuration, not a transaction. Per ADP's guide, you:

1. Choose start, change, or stop. Each is its own operation: start adds a deduction, change updates the amount, stop ends an active one.
2. Set the effective date. Every instruction applies from its effective date.
3. Let it run. An accepted instruction persists across cycles until a later one changes or stops it.

Two field-level details matter for a build: deduction codes 81 through 96 carry percentages, while other codes carry amounts, and each employee has up to nine deduction goals, each tied to one deduction.

Constraints and go-live traps

These are the limits ADP documents as hard requirements:

• Benefit-managed deductions are read-only. Where ADP benefit enrollment manages a deduction, the API can't change it until payroll deductions are suspended for that benefit plan, at plan level by ADP or per employee by a practitioner.
• Deduction status can't be toggled. The API can't set a deduction Active or Inactive; use stop instead.
• Goal Accrued and Adjustment fields aren't writable through the API.
• Garnishment details are separate. They're returned only for clients who use ADP's Wage Garnishment Processing Service, so confirm with ADP before routing garnishment orders through this general deductions path.

Two more limits come from law, not ADP, and both raise the stakes on what you write.

The earning code you attach to a payment isn't just a label. Under the FLSA regular-rate rules (29 CFR 778.208), nondiscretionary bonuses generally have to be included in the rate used to compute overtime. Write a bonus under the wrong earning code and you may have changed an overtime calculation, the kind of error payroll teams find months later in an audit.

The cafeteria plan rules cut the other way for deductions: a pre-tax election generally holds for the plan year absent a qualifying change, so "just write the new deduction" is rarely the whole story for a mid-year benefits change.

Reducing the complexity: an integration layer

Two write paths, a cycle-status window, a benefits suspension rule, and code mapping per client: that's one ADP Workforce Now integration for one employer. A benefits platform with many ADP customers repeats it for each, and again for every other payroll system its customers run.

That's the case for treating payroll write-back as infrastructure. Bindbee's ADP Workforce Now connector writes employee payroll runs carrying earnings and deductions by code, and reads the customer's payroll codes first so each write uses a code that exists in that employer's configuration, per the write a payroll deduction guide. Every write takes an idempotency key, so a retry doesn't post a deduction twice.

Bindbee connects to ADP Workforce Now as one of 102+ HRIS, payroll, ATS, and benefits systems through one API, with each customer authorizing the connection through whatever the source system supports. It syncs each connection every 24 hours by default, adjustable on request.

Whichever way you build, avoid the mistake this page opened with: treating ADP Workforce Now as one write target instead of two. See how Bindbee connects to ADP Workforce Now, or how the unified API handles the write side.

Frequently asked questions

What's the difference between ADP's Payroll Data Input API and the Deduction Instruction API?

Payroll Data Input writes entries into a pay data batch for one payroll cycle, and nothing carries forward. Deduction Instruction starts, changes, or stops a general deduction against an effective date, and it persists across cycles until another instruction changes it.

When does ADP process a Payroll Data Input request?

Only while the payroll cycle is in Entering Payroll Information or Correcting Input. ADP also lists a setup requirement: the client needs a Memo Code of 5 and an Hours & Earnings Code of T created for each active company.

Why can't I change a deduction through the Deduction Instruction API?

If ADP benefit enrollment manages the deduction, it's read-only through the API until payroll deductions are suspended for that benefit plan. The API also can't set a deduction Active or Inactive; use a stop instruction instead.

Why does the earning code I write matter for pay accuracy?

The earning code decides how a payment is treated under the FLSA regular-rate rules used for overtime. Nondiscretionary bonuses generally have to be included in the regular rate, so a miscoded earning can change an overtime calculation, not just a label.