Use Case Description
This use case sends entries to a Pay Data batch. It's commonly used to send the following data from a different system or application to the Pay Data Entry page in ADP Vantage HCM:
- Earnings
- Deductions
- Memo
- Taxes
- Cost Number
- Payroll Department Number
- Allocations
The Client Practitioner can check whether the Pay Data Entry status is successful or not in ADP Vantage HCM by navigating to Process > Utilities > Activity Log and select the following:
- Activity Log Type : HR/Payroll- Process Status
- Required start and end date between which you want to check the logs
Then, the Client Practitioner can check the required log by using the Batch ID generated while doing the Pay Data Input Add API call.
API Usage
|
Method |
Uniform Resource Identifier (URI |
)Description |
GitHub Sample Request Payload |
GitHub Sample Response Payload |
Note |
|---|---|---|---|---|---|
|
POST |
Adds a new pay data batch. |
For more information, see the Responses section below. |
The response payload will display a URI at the end of the payload in the links section. Use this URI to make the async call.
For example:
"href": "/core/v1/operations/payrollManagement/vantage/355075"
This URI can be applied only for the GET Request. |
||
|
GET |
Returns an event metadata.
|
NA |
The sample payload can be built from the meta call. |
||
|
GET |
/core/v1/operations/payrollManagement/vantage/{ID} |
Retrieves a pay data input batch for a specific batch request. |
NA |
For more information, see the Responses section below. |
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 this API and make successful API calls.
The following canonical needs to be added to your application scope in order to enable this use case:
/payroll/payrollManagement/payrollProcessing/payDataInputManagement/pay-data-input.add
Sequence of Interactions
- Your consumer application makes a request for /events/payroll/v1/pay-data-input.add/meta to the ADP API endpoint.
- The ADP API endpoint responds to your consumer application with the meta payload. See the table in the following section.
- Your consumer application processes the meta payload to validate data included in the payload in step 4 and prompts the user to fix any validation issues. Otherwise, compose the payload for the /events/payroll/v1/pay-data-input.add request.
- Your consumer application makes a /events/payroll/v1/pay-data-input.add request to the ADP API endpoint.
- The ADP API endpoint responds to the consumer application concerning the details of /events/payroll/v1/pay-data-input.add.
Responses
You may encounter exceptions outside your common success scenarios. You must account for the following exceptions during your initial development.
For more information, see API Common Exceptions and Tips for Handling.
Developer Note
As this is an asynchronous call, the API request throws only two responses:
- 202 Accepted - Thrown when a pay data batch is sent through request payload and the API call is successful. (A URI is displayed at the end of the response payload using which you can make the async call)
- 200 OK(Async call) - When the import pay data process is successful or failed.
Responses for Adding a New Pay Data Batch
POST /events/payroll/v1/pay-data-input.add
|
Response Code |
Condition |
messageTxt |
GitHub Sample Request Payload |
GitHub Sample Response Payload |
Tips to Handle |
|---|---|---|---|---|---|
| 202 Accepted | Adding a pay data batch with a single associate and the following inputs:
|
NA | ADD-Pay-data-batch-http-202-request.json |
ADD-Pay-data-batch-http-202-response.json |
The response payload will display a URI at the end of the payload in the links section. Use this URI to make the async call.
For example:
"href": "/core/v1/operations/payrollManagement/vantage/355075"
This URI can be applied only for GET Request. |
| 400 Bad Request | Adding allocations earnings, along with taxes. |
{"userMessage": { |
ADD-Pay-data-with-allocations-and-taxes-http-400-request.json | ADD-Pay-data-with-allocations-and-taxes-http-400-response.json |
Responses for Retrieving a Pay Data Input Batch for a Specific Batch Request
GET /core/v1/operations/payrollManagement/vantage/{ID}
|
Response Code |
Condition |
messageTxt |
GitHub Sample Request Payload |
GitHub Sample Response Payload |
Tips to Handle |
|---|---|---|---|---|---|
| 200 OK (Async call) | When the pay data batch is successfully imported or added into ADP Vantage HCM. |
"userMessage": {"codeValue": "0-0","messageTxt": "The 'Import Pay Data' process completed successfully."} |
NA | ADD-Pay-data-batch-http-200-response.json |
The ID can be retrieved from the URI obtained from the 202 Accepted Response payload.
|
| 200 OK (Async call) | When the pay data batch import process failed and did not get added into ADP Vantage HCM. |
"userMessage": {"codeValue": "0-0","messageTxt": "The 'Import Pay Data' process failed."} |
NA | ADD-Pay-data-batch-import-failed-http-200-response.json |
This can be due to any invalid data sent through the payload.
Make sure you send a valid Associate Object ID (AOID), payroll file number, pay group, and other codes (earnings, memos, and so on).
For codes and combinations to be used refer to the meta provided in the
|
Other Scenarios
The following is a list of common scenarios you may want to consider for your application.
The sample responses listed all have the response code of 202 Accepted and 200 OK with the following message: The 'Import Pay Data' process completed successfully.
Data Dictionary
Batch and Employee Information
Using the resources listed in the following table, data sent through the Payroll Data Input API eliminates the need for the user to enter batch and employee information data manually in ADP Vantage HCM.
For the Pay Data Input Add API, either associate OID or Employee ID is required. The user can either pass either one or both in the request payload. When one value is filled automatically, the second value gets updated. This is the reason why the meta dictates that both are mandatory fields.
|
Schema Location |
Field Name |
Business Rules |
Notes |
|---|---|---|---|
|
/data/eventContext/payrollGroupCode/codeValue |
Pay Group
|
Always Required |
A client could have multiple company codes. To create a Pay Data batch, the client needs to select the company code first. |
|
/eventContext/payrollProcessingJobID |
Batch ID |
|
The client needs to assign the batch an ID. The ID doesn't need to be unique, as the system would append system generated characters if the ID is used by an existing batch. |
|
/payDataInput/payeePayInputs/associateOID |
Not Displayed |
Always Required |
To retrieve the AOID value for an employee, use GET workers. |
|
/payDataInput/payeePayInputs/payeeID/idValue |
Employee ID | To retrieve the idValue, use GET workers call and then search for the workerID/idValue. | |
|
/payDataInput/payeePayInputs/ payrollProfilePayInputs /payrollFileNumber |
File # |
|
|
|
/payDataInput/payeePayInputs/ payNumber |
Pay Number |
|
The client needs to assign a payNumber to be used for all entries included in the batch. |
| /data/eventContext/payrollWeekNumber | WorkWeek | Indicates whether the data entered for employees are for week 1 or week 2. |
Regular, Overtime and Temp:Hours & Earning Inputs
Resources in the following table can be accessed in the ADP Vantage HCM UI by selecting Process > Payroll > Pay Data Entry. Then, select the required Pay Group and Pay Batch to find the fields.
Using the resources listed in the following table, regular and overtime earning input data sent through the Payroll Data Input API eliminates the need to enter this data manually in ADP Vantage HCM.
(Developer Note) Code REG is reserved for Regular Hours and Earnings and OTP is reserved for Overtime Hours and Earnings.
|
Schema Location |
ADP Vantage HCM Field Name |
Notes |
|---|---|---|
| /payDataInput/payeePayInputs/payrollProfilePayInputs/payInputs/earningInputs/configurationTags/tagCode | NA | |
| /payDataInput/payeePayInputs/payrollProfilePayInputs/payInputs/earningInputs/configurationTags/tagValues | SHIFT | The shift qualifier code. |
|
/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/earningInputs/earningCode/codeValue |
NA |
The Earning Code. |
| /payDataInput/payeePayInputs/payrollProfilePayInputs/payInputs/earningInputs/modifierCode | NA |
For more information refer META response payload provided in API Usage section |
| /payDataInput/payeePayInputs/payrollProfilePayInputs/payInputs/earningInputs/rateCode/codeValue | RATE CODE | The company rate code. |
|
/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/earningInputs/rate/rateValue |
Temp Rate REG ERNS OTP ERNS
|
The Temp Rate associated with the Earning Code when the modifier code is set to 24 The REG ERNS associated with the Earning Code when the modifier code is set to 1 The OTP ERNS associated with the Earning Code when the modifier code is set to 2
|
|
/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/earningInputs/rate/currencyCode |
NA |
The Currency Code. |
|
/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/earningInputs/numberOfHours |
REG HRS for code REG O/T HRS for code OTP |
The Hours associated with the Earning Code. |
|
/payDataInput/payeePayInputs/payrollProfilePayInputs/payInputs/earningInputs/earnedPayPeriodStartDate |
|
|
| /payDataInput/payeePayInputs/payrollProfilePayInputs/payInputs/earningInputs/earnedPayPeriodEndDate |
Coded Hours and Earnings Data
Resources in the following table can be accessed in the ADP Vantage HCM UI by selecting Process > Payroll > Pay Data Entry. Then select the required, Pay Group and Pay Batch to find the fields.
Using the resources listed in the following table, coded hours and earnings data sent through the Payroll Data Input API eliminates the need to enter this data manually in ADP Vantage HCM.
|
Schema Location |
Field Name |
Notes |
|---|---|---|
| /payDataInput/payeePayInputs/payrollProfilePayInputs/payInputs/earningInputs/configurationTags/tagCode | ||
| /payDataInput/payeePayInputs/payrollProfilePayInputs/payInputs/earningInputs/configurationTags/tagValues | SHIFT | The shift qualifier code. |
| /payDataInput/payeePayInputs/payrollProfilePayInputs/payInputs/earningInputs/modifierCode | NA |
|
| /payDataInput/payeePayInputs/payrollProfilePayInputs/payInputs/earningInputs/rateCode/codeValue | RATE CODE | The company rate code. |
|
/payDataInput/payeePayInputs /payrollProfilePayInputs/payInputs /earningInputs/earningCode/codeValue |
Various, depends on the Earning |
The Earning Code value. |
|
/payDataInput/payeePayInputs /payrollProfilePayInputs/payInputs / earningInputs/rate/rateValue |
"Earning code" ERNS |
The rate value associated with the earning will be displayed in this field. The field name varies according to the Earning code sent through API payload. |
|
/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/ earningInputs/numberOfHours |
"Earning code" HRS |
The Hours associated with the earning. The field name varies according to the Earning code sent through API payload. |
Deductions
Resources listed in the following table can be accessed under Process > Payroll > Pay Data Entry. Then select the required Pay Group and Pay Batch to find the fields.
Using the resources listed in the following table, deductions data sent through the Payroll Data Input API eliminates the need to enter this data manually in ADP Vantage HCM.
|
Schema Location |
Field Name |
Notes |
|---|---|---|
|
/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/deductionInputs/deductionCode/codeValue |
Various, depends on the Deduction |
The Deduction Code. |
|
/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/deductionInputs/deductionRate/rateValue |
DED ONE , DED OVR
|
The Rate associated with the deduction code will be updated in the respective fields
|
|
/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/deductionInputs/configurationTags/tagCode |
|
|
| /payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/deductionInputs/configurationTags/tagValues | Use the value from meta |
Memo
Resources listed in the following table can be accessed in the ADP Vantage HCM UI by selecting Process > Payroll > Pay Data Entry. Then, select the required Pay Group and Pay Batch to find the fields.
Using these resources, memo data sent through the Payroll Data Input API eliminates the need to enter this data manually in ADP Vantage HCM.
|
Schema Location |
Field Name |
Notes |
|
/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/memoInputs |
Various, depends on the Memo. |
The memo-related entries. |
|
/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/memoCode |
MEMO |
|
|
/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/memoCode/codeValue |
|
|
|
/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/memoInputs/memoAmount |
NA |
|
|
/payDataInput/payeePayInputs/payrollProfilePayInputs/payInputs/memoInputs/memoAmount/amountValue |
MEMO |
|
Taxes
Resources listed in the following table can be accessed in the ADP Vantage HCM UI by selecting Process > Payroll > Pay Data Entry. Then, select the required Pay Group and Pay Batch to find the fields.
Using these resources, memo data sent through the Payroll Data Input API eliminates the need to enter this data manually in ADP Vantage HCM.
|
Schema Location |
Field Name |
Notes |
|
/payDataInput/payeePayInputs/payrollProfilePayInputs/payInputs/taxInputs |
Various, depends on the Memo. |
The memo-related entries. |
|
/payDataInput/payeePayInputs/payrollProfilePayInputs/payInputs/taxInputs/taxTypeCode |
FEDERAL TAX (for taxTypeCode 1) STATE TAX (for taxTypeCode 4) LOCAL TAX(for taxTypeCode 5) STATE 2 TAX(for taxTypeCode 7) LOCAL 2 TAX(for taxTypeCode 8) |
|
|
/payDataInput/payeePayInputs/payrollProfilePayInputs/payInputs/taxInputs/taxTypeCode/codeValue |
|
Use the value from meta. |
| /payDataInput/payeePayInputs/payrollProfilePayInputs/payInputs/taxInputs/taxJurisdiction/taxJurisdictionCode | ||
| /payDataInput/payeePayInputs/payrollProfilePayInputs/payInputs/taxInputs/taxJurisdiction/taxJurisdictionCode/codeValue |
STATE TAX CD (for taxTypeCode 4) STATE 2 TAX CD (for taxTypeCode 7) |
Use the value from meta state tax codelist. |
| /payDataInput/payeePayInputs/payrollProfilePayInputs/payInputs/taxInputs/taxJurisdiction/livedInIndicator | ||
| /payDataInput/payeePayInputs/payrollProfilePayInputs/payInputs/taxInputs/taxJurisdiction/workedInIndicator | ||
|
/payDataInput/payeePayInputs/payrollProfilePayInputs/payInputs/taxInputs/taxRate/rateValue |
|
|
|
/payDataInput/payeePayInputs/payrollProfilePayInputs/payInputs/taxInputs/configurationTags |
|
|
| /payDataInput/payeePayInputs/payrollProfilePayInputs/payInputs/taxInputs/configurationTags/tagCode |
FED ACTION (for taxTypeCode 1) ST ACTION (for taxTypeCode 4) LOC ACTION(for taxTypeCode 5) ST2 ACTION(for taxTypeCode 7) LOC2 ACTION(for taxTypeCode 8) |
Use the value from meta. The following options are overrides to existing Taxes:
|
| /payDataInput/payeePayInputs/payrollProfilePayInputs/payInputs/taxInputs/configurationTags/tagValues |
Temporary Cost Number, Temporary Department Number, and Allocation
Resources listed in the following table can be accessed in the ADP Vantage HCM UI by selecting Process > Payroll > Pay Data Entry. Then, select the required Pay Group and Pay Batch to find the fields.
Using the resources listed in the following table, your data connector application can post Temporary Cost Number, Temporary Department Number, and Allocation position details through the Payroll Data Input API. This eliminates the need to enter this data manually in ADP Vantage HCM using the Pay Data Entry page.
|
POST |
Schema Location |
Field Name |
Notes |
|---|---|---|---|
|
Temporary Cost Number |
/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/payAllocation |
Not Displayed |
|
|
|
/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/payAllocation/allocationID |
Not Displayed |
Use the value from meta (CNum codeList).
|
|
|
/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/payAllocation/allocationTypeCode |
Not Displayed |
|
|
|
/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/payAllocation/allocationTypeCode/codeValue |
Temporary Cost Number |
CNum is reserved code for Cost Number. |
|
Temporary Department Number |
/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/payAllocation |
Not Displayed |
|
|
|
/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/payAllocation/allocationID |
Not Displayed |
Use the value from meta (DEPID CodeList).
|
|
Temporary Department Number (Cont.) |
/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/payAllocation/allocationTypeCode |
Not Displayed |
|
|
|
/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/payAllocation/allocationTypeCode/codeValue |
Temp Dept |
DEPID is reserved code for Cost Number. |
|
Allocation (ALA) |
/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/payAllocation |
Not Displayed |
|
|
|
/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/payAllocation/allocationID |
Not Displayed |
Use the value from meta (ALNum CodeList). |
|
|
/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/payAllocation/allocationTypeCode |
Not Displayed |
|
|
|
/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/payAllocation/allocationTypeCode/codeValue |
ALA#
|
ALNum is reserved code for Cost Number. |
Additional Information
Working with Temporary Cost Number, Temporary Department Number, and Allocations
Using the components listed in the table above, sending Temporary Cost Number, Temporary Department Number, and Allocations using the Payroll Data Input API achieves the same result as if the user follows the steps in the following sections:
Setting the Temporary Cost Number
The allocationTypeCode:CNum value in the payload indicates the Temporary Cost Number. To create the batch with Temporary Cost Number, ADP Vantage HCM should have the Labor Distribution and Allocations set to Cost Number using the following steps in the UI:
- Select Setup > Setup Information > Company > Pay Groups > Settings.
- Set the Labor Distribution to Cost Number.
- Set Allocations to Cost Number.
Setting the Temporary Department Number
The allocationTypeCode:DEPID value in the payload indicates the Temporary Department Number. To create the batch with Temporary Department Number, ADP Vantage HCM should have the Labor Distribution and Allocations set to Department Number using the following steps in the UI:
- Select Setup > Setup Information > Company > Pay Groups > Settings.
- Set the Labor Distribution to Cost Number.
- Set Allocations to Cost Number.
Setting the Allocations in ADP Vantage HCM
The value in the payload indicates Allocation positions for Cost Number and Department Number in the ADP Vantage HCM UI:
- Select Setup > Setup Information > Company > Pay Groups > Settings.
- Select either Cost Number or Department as the Allocation method your company uses to allocate employee hours and earnings.
- Select ALA Percent Required to allow your company to distribute an employee's hours and earnings to multiple departments or cost numbers on a regular basis, by percentage. This should total 100 percent.
Pay Data Fields Not Handled by the Payroll Data Input API
Currently, the Payroll Data Input API doesn't handle the following columns on the Paydata page.
| ADP Vantage HCM Field Name | Description |
|---|---|
| Social Security Number | Specifies the Social Security Number (SSN) of the employee. |
| Job | Specifies the job and description of the employee. |
| Cancel Automatic Pay |
Cancels automatic pay for one pay period. This option is not available if Automatic Pay is not selected for the pay group. |
| Tax Frequency |
Specifies the number of weeks in the tax cycle. |
| Special Action |
Adds a special pay action to the pay. |
| FLSA Special Processing Code |
Indicates whether the transaction is processed as Exclude or Compare Rates. |
| Advanced Pay Date |
A wage garnishment pay date that's only available if liens are set up for the pay group. |
| Miscellaneous Hours | Any additional Hours. |
| Miscellaneous Earnings | Any additional Earnings. |
| Taxes Social Security | Add to or replace the tax amount withheld for Social Security. |
| Taxes Medicare |
Add to or replace the tax amount withheld for Medicare. |
| Taxes Medicare Surtax | This amount will add to the normal Medicare Surtax calculation. |
| Taxes SDI |
State disability insurance tax. Use to add to or replace the tax amount that will be calculated based on the employee's permanent tax profile. |
| Taxes FLI | Use to add or replace a Family Leave Insurance (FLI) tax amount for an employee with an SUI code that's FLI applicable and FLI enabled. |
| Taxes MLI | Use to add or replace a Medical Leave Insurance (MLI) tax amount for an employee with an SUI code that's MLI applicable and MLI enabled. |
| Miscellaneous Deductions | Any additional deductions. |
| Cancel DIA-Code | Prevents Deductions In Arrears (DIA) balances from being deducted for the specified deduction code for the employee. |
| Cancel\"ALL\"DIA | Prevents all Deductions In Arrears (DIA) balances from being deducted for the employee. |
| Miscellaneous Memo | Any additional Memo. |
| State Reciprocity Code |
Identifies a method of taxation which incorporates worked-in and lived-in state tax logic. Valid values are 1 - 4. |
| School District Code |
The tax code for a school district. |
| Forecast Weeks | Automatically applies deductions scheduled for subsequent weeks to the employee's current paycheck. |
| Pay check Tax Frequency | Allows you to pay an employee in multiple departments/cost numbers, with multiple pay rates and/or multiple work weeks. |
| Block Direct Deposits | Blocks both full and partial direct deposits. |
| Block Deferred Comp | Blocks deferred compensation deductions including:
|
| Taxes Local Service 1 |
Specifies the local service tax codes if any are setup for client. |
| Taxes Local Service 2 | |
| Total Hours Pay Block | Use to block calculations for total hours worked. This will also block the display of total hours worked on the employee’s pay statement for this pay. |
| Total Hours Pay Override | Use to provide an override value for total hours worked which will be applicable to the entire pay. |
