ADP Developer Resources

Summary

ADP Workforce Now enables users to create a Pay Data batch for a payroll cycle to include the following:

Earnings
Deductions
Reimbursements
Reportable Earnings and Benefits
Temporary Cost Number
Temporary Department Number
Allocations

The Payroll Data Input Application Programming Interface (API) enables you to build a data connector application for clients to transmit data that is sourced in your application to a specific Pay Data batch in ADP Workforce Now.

What's New in this Guide?

In this section, revisions to the Payroll Data Input API and this guide will be announced.

May 2020

The following information was revised in this guide:

In Chapter 1 - About this Guide, the following was revised:
- Added a schema location for Rate Code in Regular and Overtime Earning Inputs Data Dictionary.
- Added codeList APIs for Temporary Cost Number and Temporary Department Number in Temporary Cost Number, Temporary Department Number, and Allocation Data Dictionary section.
- Updated the APPEND functionality in the Pay Data Input API Postman Collection.
In Chapter 2 - Use Case: Adding Entries in a Pay Data Patch, the following was revised:
- Added negative test cases on rate code along with GitHub links in the Responses section.
- Updated the responses for meta API in the API Usage section.
Added Chapter 3 - Use Case: Appending Entries to an Existing Pay Data Batch
In Chapter 5 - Known Issues and Limitations:
- Added Issue: Meta Call is not giving any codeList details for ratecodes
- Added Issue: Event notification is not supported
- Added US1719297: Update Pay Data Input API to reflect the true batch name

In Chapter 6 - Appendixes the following was moved from Chapter 1 - About this API:

Appendix A: Pay Data Types Handled by the Payroll Data Input API
Appendix B: Pay Data Fields Not Handled by the Payroll Data Input API

Process Overview

The following table illustrates how clients use your data connector application, which is built using the Payroll Data Input API.

	Actor	Task Description
1	Payroll Practitioner	Selects the company code, employees, and file numbers to be imported.
2	Payroll Practitioner	Enters a batch number and initiating the Pay Data import.
3	Your application	Automatically creates a new batch and imports Pay Data in ADP Workforce Now.
4	Payroll Practitioner	Reviews the import result on the ADP Workforce Now Paydata page.
5	Payroll Practitioner	Takes actions to balance and adjust, as needed. Note: To keep your data in sync with what's on the Paydata page in ADP Workforce Now, data must be adjusted in your data connector application.

Required Setup Steps

Setup Pages in ADP Workforce Now

The Payroll Data Input API supports all earning and deduction codes, including the earning and deduction codes added by clients. Clients need to make sure the codes and numbers used by your data connector application are added and configured in ADP Workforce Now by selecting Setup > Tools > Validation Tables > Payroll > Paydata.

The following table lists the records in your data connector application and how they correspond to the fields on the Paydata page in ADP Workforce Now.

Records in Your Data Connector Application	Fields on the Paydata Page in ADP Workforce Now
Hours and Earnings Codes	Hours and Earning Codes
Deduction Code	Deductions
Temporary Cost Number	Cost Number
Temporary Department Number	Department

Grid Template Setup in ADP Workforce Now

The column names appearing on the Pay Data Batch page in ADP Workforce Now should be set up under GRID TEMPLATE SETUP in Process > Payroll > Paydata >Grid Template SetUp > ADP Basic Paydata.

The following columns should be present under the Selected Fields of the Grid Template page. If not present, move the fields under Available Fields to Selected Fields.

Regular Hours
OverTime Hours
Regular earnings
OverTime Earnings
Memo
Other Earnings
Other Hours
Temporary Department
Temporary Cost Number
Allocations Position Number
Pay #
- Must be the United States, Canada (AutoPay), or cross border clients.
- Due to a limitation, the client must have a Memo Code of 5 and Hours & Earnings Code of T created for each of their active companies. Within the ADP Workforce Now UI, select Setup > Tools > Validation Tables > Paydata > Hours & Earnings Codes and Setup > Tools > Validation Tables > Paydata > Memo. If the parameter autoGenerateMemoCode=false is used, Memo Code 5 and Earning Code T are not required.

The column name will not display on the Pay Data Batch page if they are not set up on the Grid Template page.

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 Payroll Data Input API from the ADP GitHub library and import them to Postman, go to the Paydata Input Modify Postman Collection.

Before You Begin Using the Payroll Data Input API\

The following sections document the requirements for using the Payroll Data Input API.

Client Requirements

The client must meet the following requirements:

API User Requirements

The API user making the request must be assigned to a profile having the following permissions:

ADP Workforce Now menu access: Process > Payroll > Pay Data
Payroll and People Access: View and edit access to target company codes

Payroll Cycle Requirements

To process the API request, the payroll cycle status must be either Entering Payroll Information or Correcting Input, otherwise the request will cause an error.

Employee Requirements

Before including any employee in the API request, make sure the employee is in an ADP Workforce Now paid position.

Data Dictionary

Batch and Employee Information Data Dictionary

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 Workforce Now.

Schema Location	Field Name	Business Rules	Notes
/eventContext/payrollGroupCode/codeValue	Company Code	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		To retrieve the value for an employee, use GET workers.
/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.

Regular and Overtime Earning Inputs Data Dictionary

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 Workforce Now.

Code R is reserved for Regular Earnings and O is reserved for Overtime Earnings.

Schema Location	Paydata Page Location	Notes
/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/earningInputs/earningCode/codeValue	NA	The Earning Code.
/payDataInput/payeePayInputs/payrollProfilePayInputs/payInputs/earningInputs/rateCode	Rate Code
/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/earningInputs/rate/rateValue	Temp Rate	The Temp Rate associated with the Earning Code.
/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/earningInputs/rate/currencyCode	NA	The Currency Code.
/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/earningInputs/numberOfHours	Reg Hours for code R O/T Hours for code O	The Hours associated with the Earning Code.
/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/earningInputs/earningsAmount/amountValue	Reg Earnings	The Amount associated with the Earning Code.
/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/earningInputs/earningsAmount/currencyCode	NA	The Currency Code.
/payDataInput/payeePayInputs/payrollProfilePayInputs/payInputs/earningInputs /earnedPayPeriodWeekNumber	FLSA WorkWeek	Indicates whether the hours entered for employees are for week 1 or week 2.

Processing Rules

Based on the values included in the payload, ADP Workforce Now will process data according to business rules. ADP Workforce Now has the following out of box earning codes:

R = Regular Earning
O = Overtime Earning

The following table outlines various input combinations and process results.

	Common Use	/rate/ rateValue	/numberOfHours	/earnings Amount/ amountValue	Displayed on Paydata Page When Request is Processed Successfully:					Notes
					Reg Hours	O/T Hours	Temp Rate	Reg Earnings	O/T Earnings
1	Send in Hours for Regular Earning	Null	Not Null	Null	Not Null	Null	Null	Null	Null
2	Send in Hours for Overtime Earning	Null	Not Null	Null	Null	Not Null	Null	Null	Null
3	Send in Temp Rate and Hours for Regular Earning	Not Null	Not Null	Null	Not Null	Null	Not Null	Null	Null	Used for Hourly Employee only (Pay Profile > Regular Pay Rate = Hourly). The Temp Rate will be used to replace the Regular Rate on the employee record.
4	Send in Temp Rate and Hours for Overtime Earning	Not Null	Not Null	Null	Null	Not Null	Not Null	Null	Null	Used for Hourly Employee only (Pay Profile > Regular Pay Rate = Hourly). The Temp Rate will be used to replace the Overtime Rate. You cannot submit a Temp Rate for Regular Hours and another Temp Rate for the Overtime hours for the same file number in the same batch.
5	Send in Amount for Regular Earning	Null	Null	Not Null	Null	Null	Null	Not Null	Null	Used for Salaried / Daily Employee only (Pay Profile > Regular Pay Rate = Salary or Daily).
6	Send in Amount for Overtime Earning	Null	Null	Not Null	Null	Null	Null	Null	Not Null	Used for Salaried / Daily Employee only (Pay Profile > Regular Pay Rate = Salary or Daily).
7	Send in both Hours and Amounts for Regular Earning	Null	Not Null	Not Null	Not Null	Null	Null	Null	Null	The AmountValue will be disregarded.
8	Send in both Hours and Amounts for Overtime Earning	Null	Not Null	Not Null	Null	Not Null	Null	Null	Null	The AmountValue will be disregarded.

Coded Hours and Earnings Data Dictionary

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 Workforce Now.

Schema Location	Field Name	Notes
/payDataInput/payeePayInputs /payrollProfilePayInputs/payInputs /earningInputs/earningCode/codeValue	Various, depends on the Earning	The Earning Code Value.
/payDataInput/payeePayInputs /payrollProfilePayInputs/payInputs /earningInputs/earningsAmount/amountValue	Amount	The Earning Amount Value.
/payDataInput/payeePayInputs /payrollProfilePayInputs/payInputs / earningInputs/earningsAmount/currencyCode	Not Displayed	The Currency Code.
/payDataInput/payeePayInputs /payrollProfilePayInputs/payInputs / earningInputs/rate/rateValue	Rate	The Rate associated with the earning.
/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/ earningInputs/rate/currencyCode	Not Displayed	The Currency Code.
/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/ earningInputs/numberOfHours	Hours	The Hours associated with the earning.

Processing Rules

Based on values included in the payload, ADP Workforce Now will process data according to business rules. The following table outlines various input combinations and processing results.

	Common Use	/rate/rateValue	/numberOfHours	/earningsAmount /amountValue	Displayed on Paydata Page When Request is Processed Successfully	Notes
1	Send in Hours for client configured Hours and Earnings Field type: Other Hours	Null	Not Null	Null	Data sent from /numberOfHours is displayed under Other Hours - (code).	If data is sent from rateValue and amountValue, they are disregarded.
2	Send in Amount for client configured Hours and Earnings Field type: Other Hours	Null	Null	Not Null	Data sent from /amountValue is displayed under Other Earnings - (code).	If data is sent from rateValue and numberOfHours, they are disregarded.
3	Send in Hours, Rate, and Amount for client configured Hours and Earnings Field type: Hours/Earnings Field value: 3	Null	Not Null	Null	Data sent from /numberOfHours is displayed under Other Hours - (code).	If data is sent from rateValue and amountValue, they are disregarded.
4	Send in Hours, Rate, and Amount for client configured Hours and Earnings Field type: Hours/Earnings Field value: 4	Null	Null	Not Null	Data sent from /amountValue is displayed under Other Earning - (code).	If data is sent from rateValue and numberOfHours, they are disregarded.

Deductions Data Dictionary

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 Workforce Now.

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	Rate	The Rate associated with the deduction code.
/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/deductionInputs/deductionRate/currencyCode	Not Displayed	The Deduction Currency Code.
/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/deductionInputs/deductionRate/baseUnitCode /codeValue	Use the value from meta
/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/deductionInputs/configurationTags/tagCode	Use the value from meta
/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/deductionInputs/configurationTags/tagType /dataTypeCode	Use the value from meta
/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/deductionInputs/configurationTags/tagValue	Use the value from meta

Processing Rules

The value in Rate must be part of the payload to post a deduction adjustment or deduction entry.

Memo Data Dictionary

Using the resources listed in the following table, memo data sent through the Payroll Data Input API eliminates the need to enter this data manually in ADP Workforce Now.

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	Code	Use the value from the meta.
/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/memoInputs/memoAmount	NA
/payDataInput/payeePayInputs/payrollProfilePayInputs/payInputs/memoInputs/memoAmount/amountValue	Amount
/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/memoInputs/memoAmount/currencyCode	NA

Temporary Cost Number, Temporary Department Number, and Allocation Data Dictionary

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 Workforce Now using the Paydata page.

POST	Schema Location	Field Name	Notes
Temporary Cost Number	/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/payAllocation	Not Displayed
Temporary Cost Number	/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/payAllocation/allocationID	Not Displayed	allocationID:2 – Indicates the Cost Number
Temporary Cost Number	/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/payAllocation/allocationTypeCode	Not Displayed
Temporary Cost Number	/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/payAllocation/allocationTypeCode/codeValue	Temporary Cost Number	Use codeList API to get values API: /codelists/hr/v3/worker-management/cost-numbers/WFN/1
Temporary Cost Number	/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/payAllocation/allocationTypeCode/shortName	Not Displayed
Temporary Department Number	/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/payAllocation	Not Displayed
Temporary Department Number	/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/payAllocation/allocationID	Not Displayed	allocationID:3 – Indicates the Department Number.
Temporary Department Number	/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/payAllocation/allocationTypeCode	Not Displayed
Temporary Department Number	/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/payAllocation/allocationTypeCode/codeValue	Temporary Department	Use codelist API to get values API: /codelists/hr/v3/worker-management/departments/WFN/1
Temporary Department Number	/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/payAllocation/allocationTypeCode/shortName	Not Displayed
Allocation (ALA)	/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/payAllocation	Not Displayed
Allocation (ALA)	/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/payAllocation/allocationID	Not Displayed	allocationID:1 – Indicates the Allocations
Allocation (ALA)	/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/payAllocation/allocationTypeCode	Not Displayed
Allocation (ALA)	/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/payAllocation/allocationTypeCode/codeValue	ALA Position
Allocation (ALA)	/payDataInput/payeePayInputs/payrollProfilePayInputs /payInputs/payAllocation/allocationTypeCode/shortName	Not Displayed

Working with Temporary Cost Number, Temporary Department Number, and Allocations in ADP Workforce Now

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 within ADP Workforce Now.

Setting the Temporary Cost Number in ADP Workforce Now

On the Paydata page, select Insert > Column.
On the Insert Column window, select the Paydata list. Select the Temporary Cost Number position.
Click Done.
Add a column. Under the new column, enter a value for an employee.

The allocationID:2 value in the payload indicates the Temporary Cost Number. To create the batch with Temporary Cost Number, ADP Workforce Now should have the Labor Distribution and Allocations set to Cost Number using the following steps:

Select Setup > Payroll > Company Options. Select the company code and click Labor Distribution.
Set the Labor Distribution to Cost Number.
Select Setup > Payroll > Company Options. Select the company code and click Allocations.
Set Allocations to Cost Number.

Setting the Temporary Department Number in ADP Workforce Now

On the Paydata page, select Insert > Column.
On the Insert Column window, select the Paydata list. Select the Temporary Department Number position.
Click Done.
Add a column. Under the new column, enter a value for an employee.

The allocationID:3 value in the payload indicates the Temporary Department Number. To create the batch with Temporary Department Number, ADP Workforce Now should have the Labor Distribution and Allocations set to Department Number using the following steps:

Select Setup > Payroll > Company Options. Select the company code and click Labor Distribution.
Select Setup > Payroll > Company Options. Select the company code.
Click Allocations.

Setting the Allocations in ADP Workforce Now

On the Paydata page, select Insert > Column.
On the Insert Column window, select the Paydata list. Select Allocations Position Number.
Click Done.
Add a column. Under the new column, enter a value for an employee.

The allocationID:1 value in the payload indicates Allocation positions for Cost Number and Department Number.

Select Setup > Payroll > Company Options.
Select either Cost Number or Department as the Allocation method your company uses to allocate employee hours and earnings.
Select the Automatic Allocation by Percentage 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.
Select Manual Posting of Allocation in Paydata to allow your company to distribute an employee's hours and earnings to multiple departments or cost numbers through postings in paydata.

The following conditions for allocations in the payload exist based on your selections in steps 3 and 4:

When both Automatic Allocation by Percentage and Manual Posting of Allocation are checked, it takes values from 1-99 and "".
When only Automatic Allocation by Percentage is checked, it takes the values as "" and 1.

When only Manual Posting of Allocation is checked, it takes values from 2-99 and "".

When using the Allocation positions, the employee should have allocations set up under People > Employment > Employment Profile > Corporate Groups > Allocations and either use Temporary Cost Number or Temporary Department Number.

Processing Rules

Based on values included in the payload, ADP Workforce Now processes data according to business rules. The following table outlines the various input combinations and processing results.

	Common Use	/payAllocation/ allocationID	/payAllocation/ allocationTypeCode/ codeValue	Displayed on the Paydata Page When Request is Processed Successfully:	Notes
1	Send in Temporary Cost Number.	2	001000 (Any value which is set up in the Validation table for Cost Number)	Data sent from the following is displayed under Temporary Cost Number: /allocationTypeCode /codeValue	The values sent in allocationTypeCode should be set up in the Validation table for Cost Number before being used. Otherwise, the result is an error.
2	Send in Temporary Department Number.	3	002000 (Any value which is set up in the Validation table for Department)	Data sent from the following is displayed under Temporary Department Number: /allocationTypeCode /codeValue	The values sent in allocationTypeCode should be set up in the Validation table for Department before used. Otherwise, the result is an error.
3	Send in Allocation for Cost Number with both Automatic and Manual set up in Company Options.	1	"" and 1-99	Data sent from /allocationTypeCode /codeValue is displayed under ALA Position	When Automatic and Manual is set up, it takes values as "" and 1-99.
4	Send in Allocation for Department Number with both Automatic and Manual set up in Company Options.
5	Send in Allocation for Cost Number with only Automatic set up in Company Options.		"" and 1		When Automatic is set up, it takes values as "" and 1.
6	Send in Allocation for Department Number with only Automatic set up in Company Options.
7	Send in Allocation for Cost Number with only Manual set up in Company Options.	1	"" and 2-99	Data sent from /allocationTypeCode /codeValue is displayed under ALA Position	When Manual is set up, it takes values as "" and 2-99.
8	Send in Allocation for Department Number with only Manual set up in Company Options.