CHAPTER 2

Use Case: Retrieving Payroll Instructions (Payroll Instructions API)

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

/payroll/v1/workers/{aoid}/ payroll-instructions

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.
If the user wants to retrieve payroll instructions for only one position, the user can make use of the GET /payroll/v1/workers/{aoid}/payroll-instructions/{payroll-instruction-id}.
The API is called by passing the {payroll-instruction-id} of the particular position.

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:

  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.

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.
Each deduction has one item ID generated.

/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.

  • True indicates active status.
  • False indicates Inactive status.

/payrollInstructions/garnishmentInstructions

Not Displayed

 

/payrollInstructions/garnishmentInstructions/itemID

Not Displayed

Indicates the garnishment item ID.
Each garnishment has one itemID generated.

/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.
Values are ActiveComplete, and Inactive.

/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

CityStateZIP

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

payroll.instructions- aoid-200. response.json

 

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

deductionsWithGoal-asOfDate-200.response.json

 

200 OK

Retrieves any specific deduction passing deduction itemID.

 

NA

Specificdeduction-itemId-200.response.json

 

200 OK

Retrieves all the inactive deductions until the current effectiveDate.

 

NA

Inactivedeductions-currentdate-200.response.json

 

200 OK

Retrieves all the inactive deductions until the future effectiveDate.

 

NA

Inactivedeductions-futuredate-200.response.json

 

200 OK

Verifies the response when the employee does not have any deduction.

 

NA

emtpy-deductions-200.response.json

 

200 OK

Verifies the response for future date when the employee does not have any deductions.

 

NA

asOfDate-empty-200.response.json

 

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

Invalid-ItemID-400.response.json

 

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:
Exception in the requestHTTP 404 Not Found"}

NA

Invalid-associate-400.response.json

 

To update deductions for a given worker AOID using the POST API (as described in Use Case 2: Using the General Deduction Instruction Start APIUse 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