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.

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

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.

Use Case Description

This use case returns the list of all payroll instruction deductions the requester is authorized to view for a given worker.

API Usage

Application Scope

The canonical URI corresponding to the Deduction Instructions API needs to be added in the Consumer Application Registry (CAR) for the subscription following which a user can access this API and make successful API calls. 

The following canonical needs to be added to your application scope to enable this use case:

• /payroll/payrollManagement/payrollInstructionManagement
• /workerPayrollInstructionManagement/workerPayrollInstructions.read

Supported Actors

Sequence of Interactions

1. Your consumer application makes a request to the ADP API endpoint to GET payroll-instructions for a worker.
2. The ADP API endpoint responds to your consumer application with single worker payroll information.

Responses

API Usage

Scenarios to Start a New Deduction

In the given payload (deductions.start-dollar-amt-http-200-request.json, deductions.start-percent-amt-http-200-request.json), the following is the purpose of the eventContext and transform sections:

• eventContext: A set of keys, identifying the subject. In the payload, the associateID field is present under eventContext. The associateID identifies the subject.
• transform: Provides the values added or changed with respect to the subject keys defined in the eventContext section.

Application Scope

The following canonicals need to be added to your application scope to start a deduction for a worker:

• /payroll/payrollManagement/payrollInstructionManagement
• /workerGeneralDeductionInstructionManagement/ workerGeneralDeductionInstruction.start

Supported Actors

Sequence of Interactions
The following are the steps shown in the previous diagram:

1. Your consumer application makes a request to the ADP API endpoint for the Worker-general-deduction-instruction start meta.
2. Your consumer application makes a request to the ADP API endpoint for the Worker-general-deduction-instruction start API with the payload.
3. The ADP API endpoint responds to the consumer application about the details of the Worker-general-deduction-instruction start.

Responses

You may encounter exceptions outside your common success scenarios. You must account for these exceptions during your initial development.

For more information, see API Common Exceptions and Tips for Handling.

Use Case Description

This use case is used to change the deduction amount or a percentage for a worker's existing deductions.

API Usage

In the given payload (deductions.change-dollar-amt-http-200-request.json), the following is the purpose of the eventContext and transform sections:

• eventContext: A set of keys, identifying the subject. In the payload, the associateID field is present under eventContext. The associateID identifies the subject.
• transform: Provides the values added or changed with respect to the subject keys defined in the eventContext section.

Application Scope

The following canonicals need to be added to your application scope to start a deduction for a worker:

• /payroll/payrollManagement/payrollInstructionManagement
• /workerGeneralDeductionInstructionManagement/workerGeneralDeductionInstruction. change

Supported Actors

Sequence of InteractionsThe following are the steps shown in the previous diagram:

1. Your consumer application makes a request to the ADP API endpoint for the Worker-general-deduction-instruction change meta.
2. Your consumer application makes a request to the ADP API endpoint for the Worker-general-deduction-instruction change API with the payload.
3. The ADP API endpoint responds to the consumer with the details of the Worker-general-deduction-instruction change.

Responses

You may encounter exceptions outside your common success scenarios. You must account for these exceptions during your initial development.

For more information, see API Common Exceptions and Tips for Handling.

API Usage

In the given payload(deductions.stop-dollar-amt-http-200-request.json), the following is the purpose of the eventContext and transform sections:

• eventContext: A set of keys, identifying the subject. In the payload, the associateID field is present under eventContext. The associateID identifies the subject.
• transform: Provides the values added or changed with respect to the subject keys defined in the eventContext section.

Application Scope

The following canonicals need to be added to your application scope to start a deduction for a worker:

• /payroll/payrollManagement/payrollInstructionManagement
• /workerGeneralDeductionInstructionManagement/workerGeneralDeductionInstruction.stop

Supported Actors

Sequence of Interactions
The following are the steps shown in the previous diagram:

1. Your consumer application makes a request to the ADP API endpoint for a Worker-general-deduction-instruction Stop meta.
2. Your consumer application makes a request to the ADP API endpoint for the Worker-general-deduction-instruction Stop API with the payload.
3. The ADP API endpoint responds to the consumer application about the details of the Worker-general-deduction-instruction Stop.

Responses

You may encounter exceptions outside your common success scenarios. You must account for these exceptions during your initial development.

For more information, see API Common Exceptions and Tips for Handling.

Issue: Event notification not supported

Impacted APIs 

Issue Description 

Currently, deduction start and the change and stop APIs don't support event notification.

Suggested Workaround

There are no workarounds available.

US1210765: Missing data validation and limited error handling

Impacted APIs 

Issue Description 

Currently, start and change APIs are accepting negative values for the rateValue field in the request payload.

1. For the Start API, if a Deduction is scheduled for an employee and the practitioner tries to apply the same deduction with a different rateValue, it is allowed by the API.
2. For the Start and Change API, when the rateValue is passed as the following values: (NULL, '0' ) with value type as ($ or % amount), the API stops the deduction.
3. For the Stop API, if we try to stop the deduction which is not scheduled for an employee, the API doesn't throw any error.
4. Currently, the Start API is not responding to any Bad Request when the request payload has the rateValue field (which accepts dollar amount) is passed for the percentage deduction. Similarly, when, in the request payload percent is passed for the deduction in the unitCode field (which is dollar amount deduction).

Suggested Workaround

Build validation logic in your application prior to sending data to RUN

US1210765: Passing Partial Amount through API is Not Supported

Issue Description 

Currently there is no resource supported to pass partial rateValue through the API.

Impacted APIs

Suggested Workaround

There are no workarounds available.

Issue: META APIs are not returning deduction codes set up at the client level

Issue Description 

Deduction start, change, and stop meta response should return deduction codes which are set up at the client level.

Impacted APIs

Suggested Workaround

Currently, the consumer can refer to the Payroll Instruction GET API, which also returns deduction lists eligible for the client. The GET API, /payroll/v1/workers/G3V1NEC2XSVMQDB6/payroll-instructions/general-deduction, not only returns the activated deductions for the employee AOID pass the request end point, it also returns other deductions with the amount of 0. These deductions are set up at client level and automatically reflected for all the employees, but not active. Now if you want to activate them, you will need to use deduction.start.

US1210765: Deduction API can't set the pay period 

Issue Description

Currently, a practitioner can start, change, and stop the deduction, but it cannot set the pay period (from which the deduction should be scheduled). It can be done from the RUN Powered by ADP UI for now.

Impacted APIs 

Suggested Workaround 

There are no workarounds available.