Codes · comparison
Can you pull an employer's deduction code list out of a payroll system through the API, or do you have to ask them?
Yes on ADP, Paylocity, Gusto and UKG, and both ADP and Paylocity explicitly instruct integrators to discover codes at runtime rather than hardcode them — but ADP documents a hole where one-time post-tax codes do not appear in the list at all.
By Eli Wilson · Published
Yes — on every system whose specification we could read, there is a way to enumerate the employer’s codes. The vendors want you to use it: both ADP and Paylocity explicitly tell integrators not to hardcode.
Where the list lives
| System | Discovery mechanism | Caveat |
|---|---|---|
| Paylocity | GET /companies/{companyId}/deductions and /earnings | Docs instruct using these instead of hardcoding |
| ADP Workforce Now | The deductionCode/codeList collection in the event meta response | Must validate before a write; documented gap for OTO post-tax codes |
| Gusto | The supported benefit type list | Fixed vendor taxonomy, not per-employer codes |
| UKG Pro | Deduction Code API at /configuration/v1/deductions | Configuration endpoint; shape not read in full |
| Bindbee | Payroll-codes read endpoint | Passthrough of the provider’s own codes |
| Rippling, isolved, Paychex, Paycom | Not publicly determinable | No readable specification |
ADP’s instruction, and its hole
ADP’s guide is direct: your consumer application needs to validate that the deduction code
being processed is returned in the codeList collection before building the payload for the
next call. Discovery is not optional; it is part of the documented write procedure.
Which makes known issue US1294444 significant rather than trivial. A newly added Post-tax
code with frequency OTO does not return in that codelist, and ADP states there is no
workaround. So the mandated validation step can fail for a code that legitimately exists —
and the guidance offers nothing to do about it.
Paylocity’s is the most complete
Company-level code endpoints return DeductionCodeDto records carrying code,
description, checkStubDescription, calculationCode, amount, rate, frequency,
payPeriodMinimum, payPeriodMaximum, annualMaximum, w2Box, exemptTaxes,
blockedTaxes, isActive, benefitType, priority, and a nested type object. That is
enough to build a mapping table without asking the employer anything — with the exception of
tax treatment, which sits on the nested detType.
Dated evidence table
| Documented evidence | Paylocity documents both company-level code endpoints and instructs discovery over hardcoding. ADP mandates codeList validation and documents US1294444 with no workaround. UKG documents a deduction-code configuration endpoint. Bindbee documents payroll-codes reads. Checked 2026-09-10. |
| Strongest example | ADP simultaneously requiring codeList validation and documenting that a class of code is absent from the codelist — the mandated check cannot always succeed. |
| What remains unproven | Field-level completeness of any of these responses, permissioning effects, inactive-code handling, and whether the ADP gap still exists four years after the guide was last modified. |
The scorecard
- Is there a company-level code endpoint, or only a fixed vendor list? Per-employer codes need discovery; fixed taxonomies need mapping.
- Does the response carry tax treatment? Usually only via a nested type. Plan for the extra hop.
- Does it carry the calculation type? Paylocity’s
calculationCodetells you whether the code is flat or percentage. ADP’s equivalent is a code-number range, not a field. - What are the documented gaps? Ask for the known-issues list, in writing. ADP publishes one; most vendors do not.
- What is your fallback when a code is missing? Fail the onboarding visibly. Writing to a default is how a deduction ends up on the wrong plan.
Frequently asked
- Does the list include inactive codes?
- Paylocity's DeductionCodeDto carries an isActive boolean, which implies inactive codes are returned and must be filtered. ADP's payroll-instructions read can return inactive deductions on a worker. Whether the company-level code lists include inactive entries we did not confirm.
- What is the ADP OTO gap exactly?
- Known issue US1294444: when a new deduction code of Post Tax type is added with deduction frequency OTO (one-time), the newly added code does not return in the General Deduction start/change/stop API meta response codelist. ADP states there is no workaround, so discovery cannot see a code you may need to write to.
Source limits
Not verified hands-on — we have called none of these endpoints. We have not confirmed what fields come back in practice, whether the lists are complete for inactive codes, or whether pagination or permissioning limits what a given credential sees. The ADP OTO gap is as documented in a guide last modified 2022-09-22 and may since have been fixed; ADP's own Chapter 1 notes a different limitation was removed, so the known-issues list is not fully current.
Sources checked
| Source | Publisher | Document date | We checked |
|---|---|---|---|
| Pay Setup — Deductions & Earnings | Paylocity | — | 2026-09-10 |
| Deduction Instruction API Guide for ADP Workforce Now — Chapter 8, Known Issues | ADP | 2022-09-22 | 2026-09-10 |
| Gusto Embedded Payroll — benefits reference | Gusto | — | 2026-09-10 |
| UKG Pro HCM API reference | UKG | — | 2026-09-10 |
| Get Payroll Codes | Bindbee | — | 2026-09-10 |
Wrong or out of date? payrolldataspecs@gmail.com — corrections are free. How claims are scored: methodology.