Use Case Description
This use case returns the list of all available payroll instructions the requester is authorized to view for a given worker.
This API exposes values found in the ADP Workforce Now UI by selecting People > Pay > Pay Profile > Deductions. You must provide the Associate Organization ID (AOID) of the desired worker in the AOID Uniform Resource Identifier (URI) parameter.
To retrieve the ADP worker's unique Associate Object Identifier (AOID), your application can first retrieve all workers using GET /hr/v2/workers and creating the mapping between the two systems.
For more details, see the Worker Information Management API Guide.
API Usage
|
Method |
URI |
Description |
Note |
|---|---|---|---|
|
GET |
Returns the list of all active payroll instructions for an employee until the current effective date. |
ADP Workforce Now supports workers with multiple positions. When a worker has multiple positions, the Payroll Instructions API returns all active deductions and garnishments for all payroll file numbers for a given worker. Use the GET Workers API to retrieve employee position status. |
|
|
GET |
/payroll/v1/workers/{aoid}/payroll-instructions/{payroll-instruction-id} |
Returns deductions based on the pay-distribution-id. TIP: When an associate has more than one position, each position has a unique payrollGroupCode and payrollFileNumber. The user can retrieve all the payroll instructions for all positions. |
IMPORTANT: Currently, this functionality is not working for Canada and cross border clients. |
|
GET |
/payroll/v1/workers/{aoid}/payroll-instructions ?asOfDate={YYYY-MM-DD} |
Returns the list of all active deductions of an employee until the effective date provided in the asOfDate parameter. |
|
|
GET |
/payroll/v1/workers/{aoid}/payroll-instructions ?Inactive=true |
Returns the list of all active and inactive deductions for an employee until the current effective date. |
IMPORTANT: Currently, this functionality is not working for Canada and cross border clients. |
|
GET |
/payroll/v1/workers/{aoid}/payroll-instructions ?asofDate={YYYY-MM-DD}&Inactive=true |
Returns the list of all active and inactive deductions for an employee until the effective date provided in the asOfDate parameter. |
|
Parameter 'Inactive=true' returns both Inactive and active deductions. There is a similar behavior in the UI.
Application Scope
The canonical URI corresponding to the API needs to be added in the Consumer Application Registry (CAR) for the subscription following which a user can access the Deduction Instruction 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
| Request Parameter roleCode Value | Usage |
|---|---|
| practitioner | Retrieves payroll instructions as a practitioner. A practitioner can view, start, stop, or change a deduction. A system user is considered a practitioner. |
Request Header Parameters
None, in addition to the ADP standard header parameters.
Sequence of Interactions
The following are the steps shown in the previous diagram:
- Your consumer application makes a request to the ADP API endpoint to GET payroll-instructions for a worker.
- The ADP API endpoint responds to your consumer application with single worker payroll information.
Data Dictionary
The fields listed in the following table can be found in the ADP Workforce Now UI by selecting People > Pay > Deductions.
|
Payroll API Response Location |
Field Name |
Note |
|---|---|---|
|
/payrollInstructions/generalDeductionInstructions |
Not Displayed |
|
|
/payrollInstructions/generalDeductionInstructions/itemID |
Not Displayed |
Indicates the deduction Item ID. |
|
/payrollInstructions/generalDeductionInstructions/ deductionCode/codeValue |
Deduction Code |
Indicates the Deduction Code. |
|
/payrollInstructions/generalDeductionInstructions /deductionRate/rateValue |
Deduction Amount |
Indicates the deduction amount. |
|
/payrollInstructions/generalDeductionInstructions/deductionStartDate |
Effective Date |
Indicates the deduction effective date. |
|
/payrollInstructions/generalDeductionInstructions /deductionGoal/goalID |
Deduction Goal |
Indicates the Goal ID. |
|
/payrollInstructions/generalDeductionInstructions /deductionGoal/goalBalanceAmount/amountValue |
Balance |
Indicates the Goal balance amount. |
|
/payrollInstructions/generalDeductionInstructions /deductionGoal/goalLimitAmount/amountValue |
Deduction Goal Limit |
Indicates the Goal limit amount. |
|
/payrollInstructions/generalDeductionInstructions /inactiveIndicator |
Not Displayed |
Indicates the status of the deduction.
|
|
/payrollInstructions/garnishmentInstructions |
Not Displayed |
|
|
/payrollInstructions/garnishmentInstructions/itemID |
Not Displayed |
Indicates the garnishment item ID. |
|
/payrollInstructions/garnishmentInstructions/workerLien |
Not Displayed |
|
|
/payrollInstructions/garnishmentInstructions/workerLien /itemID |
Not Displayed |
Indicates the workerLien ID. |
|
/payrollInstructions/garnishmentInstructions/workerLien /lienNumber |
Lien Number |
Indicates the worker Lien number. |
|
/payrollInstructions/garnishmentInstructions/workerLien /lienTypeCode/codeValue |
Not Displayed |
Indicates the lien type code. |
|
/payrollInstructions/garnishmentInstructions/workerLien /lienTypeCode/shortName |
Lien Type |
Indicates the lien name. For example, Garnishment. |
|
/payrollInstructions/garnishmentInstructions/workerLien /lienSubTypeCode/codeValue |
Not Displayed |
Indicates the lien code value. |
|
/payrollInstructions/garnishmentInstructions/workerLien /lienSubTypeCode/shortName |
Lien Subtype |
Indicates the lien subtype name. |
|
/payrollInstructions/garnishmentInstructions/workerLien /lienStatusCode/effectiveDate |
Lien Start Date |
Indicates the lien start date. |
|
/payrollInstructions/garnishmentInstructions/workerLien /lienStatusCode/codeValue |
Not Displayed |
|
|
/payrollInstructions/garnishmentInstructions/workerLien /lienStatusCode/shortName |
Lien Status |
Indicates the lien status. |
|
/payrollInstructions/garnishmentInstructions/workerLien /courtOrder/caseNumber |
Case # / Lien ID |
Indicates the Case or Lien ID. |
|
/payrollInstructions/garnishmentInstructions/workerLien /courtOrder/issuingJurisdiction |
Not Displayed |
|
|
/payrollInstructions/garnishmentInstructions/workerLien /courtOrder/issuingJurisdiction/countrySubdivisionLevel1 |
Court Order State |
Indicates the court order state. |
|
/payrollInstructions/garnishmentInstructions/workerLien /courtOrder/issuingJurisdiction/countrySubdivisionLevel1 /subdivisionType |
City, State, ZIP |
Indicates the City, State, and ZIP. |
|
/payrollInstructions/garnishmentInstructions/workerLien /courtOrder/issuingJurisdiction/countrySubdivisionLevel1 /codeValue |
Not Displayed |
|
|
/payrollInstructions/garnishmentInstructions/workerLien /courtOrder/issuingJurisdiction/countrySubdivisionLevel1 /shortName |
Not Displayed |
|
|
/payrollInstructions/garnishmentInstructions/workerLien /courtOrder/lienMaritalStatusCode |
Not Displayed |
|
|
/payrollInstructions/garnishmentInstructions/workerLien /courtOrder/lienMaritalStatusCode/codeValue |
Not Displayed |
|
|
/payrollInstructions/garnishmentInstructions/workerLien /courtOrder/lienMaritalStatusCode/shortName |
Marital Status |
Indicates the marital status. |
|
/payrollInstructions/garnishmentInstructions/workerLien /fullServiceClientIndicator |
Not Displayed |
|
|
/payrollInstructions/garnishmentInstructions/workerLien /allowanceQuantity |
Not Displayed |
|
|
/payrollInstructions/garnishmentInstructions/workerLien /fundsDisbursement |
Not Displayed |
|
|
/payrollInstructions/garnishmentInstructions/workerLien /fundsDisbursement/disbursementFees |
Funds Disbursement Schedule |
Indicates the disbursement fees. |
|
/payrollInstructions/garnishmentInstructions/workerLien /fundsDisbursement/disbursementMessages |
Funds Disbursement Check Stub Messages |
|
|
/payrollInstructions/garnishmentInstructions /garnishmentAmount |
|
|
|
/payrollInstructions/garnishmentInstructions /garnishmentAmount/amountValue |
Deduction Amount |
Indicates the garnishment amount. |
|
/payrollInstructions/garnishmentInstructions /garnishmentStartDate |
Deduction Effective On |
Indicates the garnishment effective date. |
|
/payrollInstructions/payrollFileNumber |
Not Displayed |
|
|
/payrollInstructions/payrollAgreementID |
Not Displayed |
|
|
/payrollInstructions/payrollGroupCode |
Not Displayed |
|
|
/payrollInstructions/payrollGroupCode/codeValue |
Not Displayed |
|
|
/payrollInstructions/payrollGroupCode/shortName |
Not Displayed |
|
|
/payrollInstructions/workAssignmentStatus |
Not Displayed |
|
|
/payrollInstructions/workAssignmentStatus/effectiveDateDate |
Effective Date |
|
|
/payrollInstructions/workAssignmentStatus/codeValue |
Status |
|
Responses
|
Response Code |
Response Condition |
message txt |
GitHub Sample Request Payload |
GitHub Sample Response Payload |
Note |
|---|---|---|---|---|---|
|
200 OK |
Retrieves all the payroll deductions until the current effective date. |
|
NA |
|
|
|
200 OK |
Retrieves all the payroll deductions until the provided asOfDate parameter. |
|
NA |
payroll.instructions- asOfDate-200. response.json200.response.json |
|
|
200 OK |
Retrieves all the payroll deductions until the provided asOfDate parameter. |
|
NA |
|
|
|
200 OK |
Retrieves any specific deduction passing deduction itemID. |
|
NA |
|
|
|
200 OK |
Retrieves all the inactive deductions until the current effectiveDate. |
|
NA |
|
|
|
200 OK |
Retrieves all the inactive deductions until the future effectiveDate. |
|
NA |
|
|
|
200 OK |
Verifies the response when the employee does not have any deduction. |
|
NA |
|
|
|
200 OK |
Verifies the response for future date when the employee does not have any deductions. |
|
NA |
|
|
|
204 No Content |
Verifies the response when the employee does not get paid from ADP Workforce Now. |
|
NA |
NA |
There will not be any response in this case. |
|
400 Bad Request |
Verifies the response when the itemID passed in the URI is invalid. |
|
N/A |
|
|
|
500 Internal Server Error |
Verifies the response when the associate ID passed in the request URI is invalid. |
"userMessage": {"messageTxt": "Label not found, missing following key: |
NA |
|
To update deductions for a given worker AOID using the POST API (as described in Use Case 2: Using the General Deduction Instruction Start API, Use Case 3: Changing a General Deduction Instruction, and Use Case 4: Using the General Deduction Instruction Stop API the payload needs to send a few values. These values can be obtained only by the GET /payroll/v1/workers/{associateoid}/payroll-instructions API. The following values need to be used from the response of the Payroll Instructions API:
- payrollFileNumber
- payrollAgreementID
- itemID
