The Deduction Instruction Application Programming Interfaces (APIs) are used to do the following:
- Start, stop, or change the payroll deduction setup for a worker.
- View all deduction instructions of a worker.
- Retrieve and send employee deductions to ADP (commonly used by Benefits Solutions).
- Capture taxable employer contributions.
Deductions are now supported for Canadian and Cross Border clients. There is no change in request payload or the ADP Workforce Now user interface (UI).
Access tokens need to be used based on the following clients:
- United States (U.S.)
- Cross Border
What's New in this Guide?
In this section, we will announce any new revisions to the Deduction Instructions API and this guide.
About Deduction Categories
Currently, the ADP Workforce Now Deduction Instruction API only handles the Pre-tax and Post-tax deduction categories, which are defined as follows:
- Pre-tax – When you select the Pre-tax deduction category, select and complete an authorization form to request ADP to set up your Pre-tax Deduction Code. After you complete the form, ADP will set up your deduction and notify you when it's ready to use. Use the Pre-tax deduction category to set up Deduction Codes for the following:
- Medical plans
- Cafeteria 125 plans
- 401(k) plans
- Tax grids
- Special compensation
- Other similar deductions
- Post-tax – Used to set up Deduction Codes for the following:
- Union Dues
- Form W-2 (this displays by law)
- Special Compensation
- Benefit Plan
- Other similar deductions
Deduction Codes could also be used to record and report on the Employer Contribution. For this type of deduction, the client practitioner will need to work with an ADP account manager or client service representative (depends on the service model) to create a special calculation that takes the employee deduction *-1.00, resulting in an earnings code. In other words, a negative deduction amount results in added earnings into the employee's paycheck, which is taxed and removed. Therefore, the employee does not actually receive the money.
The Deduction Instruction APIs do not currently handle the following categories:
- Direct Deposit – Used to set up Deduction Codes for employee direct deposits. You must set up the Direct Deposit feature on the Company Options page or you cannot select this deduction category.
- School District Tax – Used to set up Deduction Codes for employees only in the state of Ohio. If a school district tax deduction was already set up for your company, this deduction category is not displayed (there is only one school district tax code per company).
- Medicare Surtax – Used to set up Deduction Codes for the Medicare Surtax for High Wage Earners, an employee tax that was approved by the United States Supreme Court on June 28, 2012. This tax is assessed at 0.9% of Medicare Subject Wages over $200,000 effective January 1, 2013. Medicare Surtax is reported separately on Form W-2 and Form 941. There is no employer tax component. If a Medicare Surtax deduction was already set up for your company, this deduction category is not displayed (there's only one Medicare Surtax Deduction Code per company). This code is never assigned to an employee. It's used when you adjust manual checks.
- Liens (Tax Levy, Garnishment, Support Order, Bankruptcy) – Used to set up Deduction Codes for employee liens. Displayed only for clients who use ADP's Wage Garnishment Processing Service (WGPS). If your client does not use WGPS, they can set up liens as an employee deduction or you can call your ADP service team to set up WGPS for your company.
Additional Information for Integration
You may want to retrieve actual deductions resulted after the payroll run. The following are options you and the client could use:
- API based integration – Your application could use the Payroll Data Output APIs to retrieve payroll output data and get the deduction information for each employee after each payroll job.
- ADP Reporting – If the client has an ADP Report, the client could create a report to pull in PayDate, Deduction Code, Deduction Amount, and EE Name. This is an existing process that people use to work with benefit vendors to check and balance payments to benefit vendors. Do the following:
- Log into the ADP Workforce Now user interface (UI) as a practitioner.
Select Reports > All Reports > Sample.
There is a Benefit Deductions report where clients should be able to specify the Deduction Codes for the plans in which they are interested.
- File base integration – Ask the client to provide a payroll register.
Required Setup Steps
After your client acquires your data connector application, they need to make sure the Deduction Codes used by your application are set up in ADP Workforce Now.
When setting up Deduction Codes in ADP Workforce Now, the following also need to be configured. Afterwards, the configuration will apply to all workers.
- Frequency – Could be set to one of the following:
- OTO - One Time Offer
- EPR - Every Payroll or Process
- Accumulators – Used to accumulate the amounts for a Deduction Code. You can setup accumulators that are cleared several different times. For example, there is an accumulator for:
- Year to Date
- Quarter to Date
- Several others, as needed
For Deduction Codes 81 through 96, the value is shown as a percentage. For Deduction Codes other than 81 through 96, the value is shown as an amount. Therefore, your application should be built similarly.
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.