Summary
The Deduction Instructions Application Programming Interface (API) allows applications to retrieve, start, change, and stop deductions for an employee or contractor.
In RUN Powered by ADP, a deduction is a voluntary amount or percentage, other than taxes, subtracted from an employee's or contractor's pay. The amount can be the result of the following:
- Tax calculation
- Voluntary deduction
- Bank deposit
- Lien
- Benefit plan
Company deductions are taken after taxes and garnishments are calculated. They are usually associated with a benefit or service provided by the employer.
Deductions having a statutory limit, such as a 401(k) and Social Security, stop automatically after the limit is reached.
What's New in this Guide?
In this section, revisions to the Deduction Instruction APIs and this guide will be announced.
June 2020
- Updated the Sequence of Interaction sections in chapters 2, 3, and 4.
- Added the following limitations in Chapter 6 - Known Issues and Limitations:
- Event notification not supported.
- META apis are not returning deduction codes set up at the client level.
Supported Product Version and Customer Base
The Deduction Instructions API is available for RUN Powered by ADP U.S. clients having the Payroll features.
Process Overview
|
Actor |
Task Description |
---|---|---|
1 |
Payroll Practitioner |
Add deductions at the company level. |
2 |
Your system |
|
Required Setup Steps
To start a deduction for a worker, the deduction must be configured at the company level for the client. RUN Powered by ADP supports deductions in the categories listed in the following sections.
Garnishment
Garnishment includes the following:
- Bankruptcy
- Child support
- Federal agency
- Federal student loan
- Federal tax levy
- Creditor
- Medical support
- State student Loan
- State tax levy
- Private support
- Wage assignment
- Employer processing fee
Miscellaneous Deductions
Miscellaneous Deductions includes the following:
- Advance
- Loan
- Miscellaneous
- Miscellaneous %
- Credit union
- Transit and parking pass
- Draw post tax
- Charity
- United way
- Uniform
- Credit union
- Initiation
- Christmas club
- Vacation club
- 529 savings plan
- Meals
- Parking pass pre-tax
- Transit pass pre-tax
- Auto Insurance
- Home Insurance
- PA LST
- Cents per hour
- Paid family leave employee
- Paid family leave ER
- Paid medical leave employee & Paid medical leave ER
Post-Tax Insurances
Post-Tax Insurances includes the following:
- Medical
- Dental
- Life insurance
- Long-term disability
- EE-Medical Savings Account $
- EE-Medical Savings Account %
- AFLAC post-tax
- FSA post-tax $
- Vision
- Dependent care
- Accidental death & dismemberment
- Short-term disability $
- Short-term disability %
- Short-term disability $
- Short-term disability %
- HSA post-tax catch-up $
- HSA post-tax catch-up %
- HSA post-tax catch-up $
Pre-Tax Insurances
Pre-Tax Insurances includes the following:
- Dental pre-tax
- Dependent care pre-tax
- Vision pre-tax
- Blue Cross (pre-tax) $
- Blue Cross (pre-tax) %
- Hospital (pre-tax) $
- Hospital (pre-tax) %
- Medical pre-tax 1
- Short-term disability (pre-tax) $
- Short-term disability (pre-tax) %
- AFLAC pre-tax
- FSA pre-tax $
- Medical pre-tax 2
- Life insurance pre-tax
- Vision pre-tax
- Long-term disability pre-tax
- Dependent care pre-tax
- Accidental death & dismemberment pre-tax
- HSA CAF125 pre-tax $
- HSA CAF125 pre-tax %
- HSA CAF125 pre-tax catch-up $
- HSA CAF125 pre-tax catch-up %
Retirement
Retirement includes the following:
- 401(k) plan $
- 401(k) plan %
- 401(k) catch-up $
- 401(k) catch-up %
- SIMPLE 401(k) $
- SIMPLE 401(k) %
- SIMPLE 401(k) catch-up
- SIMPLE 401(k) catch-up $
- SIMPLE 401(k) non-elective contribution
- SIMPLE IRA non-elective contribution
Voluntary Disability Insurance
Voluntary Disability Insurance includes State voluntary disability plans.
Unions
Unions include the following:
- Union
- Union cents per hour
- Union percentage of gross
- Assessment flat dollar
- Assessment cents per hours
- Assessment percentage of gross
Additional Notes about Deduction Categories
- Deduction Categories and deductions are set-up at the company level and are applicable to all workers within the company.
- Newly scheduled deductions are in effect for the next payroll cycle.
- Deductions can be a flat dollar amount or a percentage of the worker's pay. Deductions which only support the U.S. Dollar (USD) will be named with the $ symbol. Deductions which only support percentage will be named with the % symbol. For more information, see Chapter 3 - Use Case: Starting a Deduction for a Worker.
In addition, clients need to make sure that Pay Type, Pay Rate, and Pay Frequency setup is done for the employee in RUN Powered by ADP. This is completed in the RUN Powered by ADP user interface (UI) by selecting Employees > Directory > Payroll info.
Postman Collection
Postman allows you to import a collection of APIs, created by others, so you can try them out. For more information on Postman, see Making Your First API Call Using Postman.
To download API collections for the Deduction Instruction API from the ADP GitHub library and import them to Postman, go to Deduction Instructions Postman Collection.
Data Dictionary
The Deduction Instructions API exposes the Deductions setup for a worker. To view the data in RUN Powered by ADP, login as a practitioner and select Employee > Earnings Deductions.
RUN Powered by ADP Field Name |
Deductions API Response Location |
Required Field for New Deduction? |
---|---|---|
Deduction |
/payrollInstructions/generalDeductionInstructions/deductionCode/codeValue |
Yes |
Type - Dollar |
/payrollInstructions/generalDeductionInstructions/deductionRate/ currencyCode |
No |
Type - Percentage |
/payrollInstructions/generalDeductionInstructions/deductionRate/ unitCode/codeValue |
Yes |
Amount |
/payrollInstructions/generalDeductionInstructions/deductionRate/ rateValue |
Yes |
Goal amount |
/payrollInstructions/generalDeductionInstructions/deductionGoal/ goalLimitAmount/amountValue |
No |