ADP Marketplace REST API Job Aid

Introduction
This job aid was created to assist developers who are tasked with implementing solutions that utilize ADP® APIs. The content
was developed based on the most frequently asked questions from client developers.
To use our APIs, you should have a basic familiarity with software development, HTTP, RESTful web services, JSON and
OAuth. In addition to the content provided within this document, you will need to review the materials located on the ADP
Developer Community web site. The ADP Developer Community web site contains a wealth of information regarding ADP’s
suite of APIs and how to use them. One thing to note about the community, however, is that it is used by ADP partners as well
as our valued clients and references APIs and features across a wide range of ADP systems of record.
The ADP Developer Community references APIs and features that may not be available for all ADP applications. For this
reason, we recommend that you reference the product-specific API Data Dictionaries along with this document and other
sample materials your ADP representative has provided to you regarding ADP APIs.
Table of Contents
A. Filtering capabilities on GET Workers V2 collections ..................................................................2
B. Pagination on GET Workers V2 collections ...................................................................................4
C. Use ODATA $select.............................................................................................................................4
D. Reading event notifications...............................................................................................................4
E. Search for workers using POST /events/hr/v1/worker.read ........................................................5
F. Caching mechanisms for APIs .......................................................................................................15
G. Masking/Unmasking capabilities for APIs ....................................................................................16
H. Validating your ADP Marketplace API access .............................................................................16
I. Getting started with Developer Libraries from the ADP Developer Portal .............................17
J. How to push payroll data elements with Pay Data Input-Add API ...........................................17
K. Errors Troubleshooting FAQs.........................................................................................................19

ADP, the ADP logo and Always Designing for People are trademarks of ADP, Inc. Page 1
 ADP Marketplace REST API Job Aid

A. Filtering capabilities on GET Workers V2 collections

Corresponding API Call
JSON Element
Field

workers/workerStatus/statusCode/codeValue Employment GET

Status (i.e. /hr/v2/workers?$filter=workers/workerStatus/status
Active, Inactive, Code/codeValue%20eq%20'xxxxxx'
etc.)

workers/workAssignments/jobCode/codeValu Job Code GET

e /hr/v2/workers?$filter=workers/workAssignments/jo
bCode/codeValue%20eq%20'xxxxxx'

workers/workAssignments/homeOrganization Cost Number GET

alUnits/nameCode/codeValue /hr/v2/workers?$filter=workers/workAssignments/h
omeOrganizationalUnits/nameCode/codeValue%2
0eq%20'xxxxxx'

workers/workAssignments/homeOrganization Company Code GET

alUnits/nameCode/codeValue /hr/v2/workers?$filter=workers/workAssignments/h
omeOrganizationalUnits/nameCode/codeValue%2
0eq%20'xxxxxx'

workers/workAssignments/assignedOrganizat Department ID GET

ionalUnits/nameCode/codeValue /hr/v2/workers?$filter=workers/workAssignments/a
ssignedOrganizationalUnits/nameCode/codeValue
%20eq%20'xxxxxx'

workers/workAssignments/homeWorkLocatio Reporting GET

n/nameCode/codeValue Location /hr/v2/workers?$filter=workers/workAssignments/h
omeWorkLocation/nameCode/codeValue%20eq%2
0'xxxxxx'

workers/workAssignments/assignedWorkLoc Job Location GET

ations/nameCode/codeValue /hr/v2/workers?$filter=workers/workAssignments/a
ssignedWorkLocations/nameCode/codeValue%20e
q%20'xxxxxx'

workers/workerDates/originalHireDate Employment
Hire Date GET
/hr/v2/workers?$filter=workers/workerDates/original
HireDate%20eq%20'yyyy-mm-dd'

or GET
/hr/v2/workers?$filter=workers/workerDates/original
HireDate%20le%20'yyyy-mm-dd'

or GET
/hr/v2/workers?$filter=workers/workerDates/original
HireDate%20ge%20'yyyy-mm-dd'

ADP, the ADP logo and Always Designing for People are trademarks of ADP, Inc. Page 2
 ADP Marketplace REST API Job Aid

Corresponding API Call

JSON Element
Field

or GET
/hr/v2/workers?$filter=workers/workerDates/original
HireDate%20lt%20'yyyy-mm-dd'

or GET
/hr/v2/workers?$filter=workers/workerDates/original
HireDate%20gt%20'yyyy-mm-dd'

workers/workerDates/rehireDate Employment GET

Rehire Date
/hr/v2/workers?$filter=workers/workerDates/rehire
Date%20eq%20'yyyy-mm-dd'
Or GET
/hr/v2/workers?$filter=workers/workerDates/rehire
Date%20le%20'yyyy-mm-dd'

or GET
/hr/v2/workers?$filter=workers/workerDates/rehire
Date%20ge%20'yyyy-mm-dd'

or GET
/hr/v2/workers?$filter=workers/workerDates/rehire
Date%20lt%20'yyyy-mm-dd'

or GET
/hr/v2/workers?$filter=workers/workerDates/rehire
Date%20gt%20'yyyy-mm-dd'

workers/workerDates/terminationDate Employment GET

Termination
/hr/v2/workers?$filter=workers/workerDates/termin
Date
ationDate%20eq%20'yyyy-mm-dd'

or GET
/hr/v2/workers?$filter=workers/workerDates/termin
ationDate%20le%20'yyyy-mm-dd'

or GET
/hr/v2/workers?$filter=workers/workerDates/termin
ationDate%20ge%20'yyyy-mm-dd'

ADP, the ADP logo and Always Designing for People are trademarks of ADP, Inc. Page 3
 ADP Marketplace REST API Job Aid

Corresponding API Call

JSON Element
Field

or GET
/hr/v2/workers?$filter=workers/workerDates/termin
ationDate%20lt%20'yyyy-mm-dd'

or GET
/hr/v2/workers?$filter=workers/workerDates/termin
ationDate%20gt%20'yyyy-mm-dd'

B. Pagination on GET Workers V2 collections

• GET /hr/v2/workers?$skip=9&$top=10 → starts with record offset 10, and returns the next 10
employees
• The maximum records returned without pagination is 2500. Do not use a pagination window
greater than 2500 records.

C. Use ODATA $select

• Applies to ADP Vantage HCM, HR Anytime, and Enterprise HR version 5.04.03.1 and higher.
• GET hr/v2/workers/{aoid}?$select=workers/workerID/idValue,workers/person/legalName →
Request objects (each separated by a comma) that should be included in the result sets
• The object should be referenced by the JSON canonical path → e.g. workers/person/legalName

D. Reading event notifications

• A client’s event notifications queue is based on a First-in First-out (FIFO) model.
• The event at the top of the queue will be returned every time the GET Event-Notification-Messages
API is invoked by the consuming application, until the application specifically calls the Delete Event
Notification, in which case that event is removed from the queue and the next one in-line is moved
to the top.
• The same process will need to be repeated again until no more messages are in the queue:
a. GET event notification in order to read the next notification inline.
b. After processing the read event notification accordingly, call the Delete the read event
notification API so the next available notification is now available to be read.
• The full details on how to use the GET Event-Notification-Messages and DELETE Event-
Notification-Messages are covered in this document from the developers.adp.com portal.
• Important: The event notification queue enforces the following technical constraints:
ADP, the ADP logo and Always Designing for People are trademarks of ADP, Inc. Page 4
 ADP Marketplace REST API Job Aid

a. The queue’s size limit (i.e. maximum number of notifications) is 50k distinct notifications. b.
A single notification can’t exceed 104600000 bytes.

E. Search for workers using POST /events/hr/v1/worker.read

• Applies to ADP Vantage HCM, HR Anytime, and Enterprise HR version 5.04.04 and higher.
• Using the POST /events/hr/v1/worker.read, an application can search securely for a specific worker,
or a list of workers, that matches some selection criteria using the following query parameters.
Since this is a POST API, the query parameters are sent in the message body, and not in the URL,
and thus they’ll be encrypted through the established SSL channel:
o Employee’s ID
o Employee's SSN (full or partial)
o Employee’s Payroll File Number
o Employee's First Name
o Employee's Middle Name
o Employee's Last Name
o Employee's date of birth in yyyy-mm-dd format
o Employee’s Paygroup Code
o Employee’s Department Code
o Employee’s Work Location Code
o Employee’s Job Code
o Employee’s Manager ID
o Employee’s Job Code long name
o Employee’s Status code
o Employee’s Status Reason code

• The returned result set will contain the full name of the employee, his/her legal status, and ADP’s
associated AOID required for any subsequent API call (e.g. GET /hr/v2/workers/{associatedOID}
a. Supported query parameters
1. Searching with Empl ID
{
"events": [
{
"data": {
"transform": {
"queryParameter": " workerID/idValue eq '12345'"

}
}
ADP, the ADP logo and Always Designing for People are trademarks of ADP, Inc. Page 5
 ADP Marketplace REST API Job Aid

]
}

2. Searching with full SSN (no dashes to be sent)

{
"events": [
{
"data": {
"transform": {
"queryParameter": "person/governmentIDs(0)/idValue eq '111223333'"

}
}
}
]
}
3. Searching with partial SSN (leading 0s)
{
"events": [
{
"data": {
"transform": {
"queryParameter": "person/governmentIDs(0)/idValue eq '000004X2X'"

}
}
}
]

ADP, the ADP logo and Always Designing for People are trademarks of ADP, Inc. Page 6
 ADP Marketplace REST API Job Aid

4. Searching with payroll file number

{
"events": [
{
"data": {
"transform": {
"queryParameter": "workAssignments/payrollFileNumber eq '345671'"

}
}
}
]
}

5. Searching with first-name

{
"events": [
{
"data": {
"transform": {
"queryParameter": "person/legalName/givenName eq 'Jack'"

}
}
}

ADP, the ADP logo and Always Designing for People are trademarks of ADP, Inc. Page 7
 ADP Marketplace REST API Job Aid

]
}

6. Searching with middle-name

{
"events": [
{
"data": {
"transform": {
"queryParameter": "person/legalName/middleName eq 'John'"

}
}
}
]
}
7. Searching with last-name
{
"events": [
{
"data": {
"transform": {
"queryParameter": "person/legalName/familyName eq ‘Smith'"

}
}
}

ADP, the ADP logo and Always Designing for People are trademarks of ADP, Inc. Page 8
 ADP Marketplace REST API Job Aid

]
}

8. Searching with date of birth

{
"events": [
{
"data": {
"transform": {
"queryParameter": "person/birthDate eq '19X0-01-04'"

}
}
}
]
}
9. Searching with paygroup code
{
"events": [
{
"data": {
"transform": {
"queryParameter": "workAssignments/payrollGroupCode eq 'MCB'"

}
}
}
ADP, the ADP logo and Always Designing for People are trademarks of ADP, Inc. Page 9
 ADP Marketplace REST API Job Aid

]
}

10. Searching with department code

{
"events": [
{
"data": {
"transform": {
"queryParameter": "workAssignments/assignedOrganizationalUnits/nameCode/codeValue eq
'ACT01’"
}

}
}
]
}
11. Searching with work location code
{
"events": [
{
"data": {
"transform": {
"queryParameter": "workAssignments/assignedWorkLocations/nameCode/codeValue eq
'GA01'"
}

}
ADP, the ADP logo and Always Designing for People are trademarks of ADP, Inc. Page 10
 ADP Marketplace REST API Job Aid

]
}

12. Searching with job code

{
"events": [
{
"data": {
"transform": {
"queryParameter": "workAssignments/jobCode/codeValue eq 'PM01'"

}
}
}
]
}

13. Searching with job code long name

{
"events": [
{
"data": {
"transform": {
"queryParameter": " workAssignments/jobCode/longName eq ' Sr. Trainer'"

}
}

ADP, the ADP logo and Always Designing for People are trademarks of ADP, Inc. Page 11
 ADP Marketplace REST API Job Aid

]
}

14. Searching with manager’s Empl ID

{
"events": [
{
"data": {
"transform": {
"queryParameter": " workAssignments/reportsTo/workerID/idValue eq '74412'"

}
}
}
]
}

15. Searching with status code

{
"events": [
{
"data": {
"transform": {
"queryParameter": " workers/workerStatus/statusCode/codeValue eq 'A'"

}
}
}
]
}
ADP, the ADP logo and Always Designing for People are trademarks of ADP, Inc. Page 12
 ADP Marketplace REST API Job Aid

16. Searching with status reason code

{
"events": [
{
"data": {
"transform": {
"queryParameter": " workers/workerStatus/reasonCode/codeValue eq 'TER'"

}
}
}
]
}

17. Combining supported search parameters with ‘and’ operator

{
"events": [
{
"data": {
"transform": {
"queryParameter": "person/legalName/familyName eq ‘Smith' and
person/governmentIDs(0)/idValue eq '000001X3X'"
}

}
} ]}

18. Combining supported search parameters with ‘or’ operator

ADP, the ADP logo and Always Designing for People are trademarks of ADP, Inc. Page 13
 ADP Marketplace REST API Job Aid

"events": [
{
"data": {
"transform": {
"queryParameter": "person/legalName/familyName eq ‘Smith' or
person/governmentIDs(0)/idValue eq '000001X3X'"
}

}]}

b. The expected response for POST /events/hr/v1/worker.read

{
"events": [
{
"data": {
"output": {
"workers": [
{
"associateOID": "G3GK78ZXB56J9ZHN",

"workerID": {
"idValue": "016607"
},
"person": {
"governmentIDs": [
{
"itemID": "SSN",

"idValue": "78X6X1X3X"
}

ADP, the ADP logo and Always Designing for People are trademarks of ADP, Inc. Page 14
 ADP Marketplace REST API Job Aid

],
"legalName": {
"givenName": "Jack",

"middleName": "John",

"familyName1": "Smith",

"formattedName": "Smith, Jack J."

}
},
"workerStatus": {
"statusCode": {
"codeValue": "A",
"longName": "Active"
}
},
"links": [
{
"href": "/hr/v2/workers/G3GK78ZXB56J9ZHN",

"rel": "self"
}
]
}
]
}
}
}]}

F. Caching mechanisms for APIs

ADP, the ADP logo and Always Designing for People are trademarks of ADP, Inc. Page 15
 ADP Marketplace REST API Job Aid

• Currently the GET /hr/v2/workers/{associatedOID} API (the single worker API) gets cached following a
24 hours rule: this means that the GET /hr/v2/workers/{associatedOID} is cached for 24 hours after the
first response is retrieved from the DB. All other APIs’ responses are not cached.
• In the event your integration needs to by-pass the GET /hr/v2/workers/{associatedOID} 24 hour cache
at any time, the following header needs to added to the API call:
o If-None-Match = any randomly generated value can be sent as a value

G. Masking/Unmasking capabilities for APIs

• By default, the following APIs provide these mentioned sensitive personal information masked in the
JSON responses
o GET /hr/v2/workers/{associatedOID}
▪ SSN and SIN (for CA workers)
▪ Date of birth
o GET /payroll/v2/workers/{associateoid}/pay-distributions
▪ Bank Routing Number
▪ Account Number
• In order to receive these values unmasked in the corresponding API responses, the ‘masked=false’
parameter needs to be sent as part of the ‘Accept’ header when invoking the API as shown below:
o Accept: Application/Json;masked=false

H. Validating your ADP Marketplace API access

• Once you’ve created your PFX Certificate and have been issued your OAuth2 Client ID and Client
Secret, you’re ready to make your first API call. You’ve probably already decided on what
technology stack you’ll be using for the middleware you’ll write that uses the ADP APIs and, since
these are RESTful APIs, you’re free to write your middleware using any technology you want,
including Java, .Net, Node.js, and others.

• Before starting the development effort, you can validate your API access by executing these 2
cURL command lines: the first one is to get the access token and the second one will make a GET
workers API call using the received access token
• Depending if it’s UAT or PROD, the right URLs will have to be used
a) For UAT access validation (Does not apply to Enterprise HR.)

1st command line: curl -v --cert <your_cert>.pfx:<your_cert_password> --user

"clientid:clientsecret" --data "grant_type=client_credentials" https://uat-
accounts.adp.com/auth/oauth/v2/token

2nd command line: curl -v --cert <your_cert>.pfx:<your_cert_password> -H "Accept:

application/json" -H "Authorization: Bearer <your_access_token_from_previous_command>"
https://uat-api.adp.com/hr/v2/workers?$top=5

b) For PRD access validation (For Enterprise HR, both P and Q databases use PRD.)
ADP, the ADP logo and Always Designing for People are trademarks of ADP, Inc. Page 16
 ADP Marketplace REST API Job Aid

1st command line: curl -v --cert <your_cert>.pfx:<your_cert_password> --user

"clientid:clientsecret" --data "grant_type=client_credentials"
https://accounts.adp.com/auth/oauth/v2/token

2nd command line: curl -v --cert <your_cert>.pfx:<your_cert_password> -H "Accept:

application/json" -H "Authorization: Bearer <your_access_token_from_previous_command>"
https://api.adp.com/hr/v2/workers?$top=5

I. Getting started with Developer Libraries from the ADP Developer Portal
• The ADP Developer portal has pre-built libraries to connect to ADP’s products through APIs and
consume workforce data (link here).
• Upon choosing the preferred language library, you’ll need to get the version that is provided to
‘Build a Data Connector Application’
• You’ll be forwarded to a page with a link to the GitHub repo containing the source code to use.
You’ll need to update the code with your connection’s specification:
a) Signed ADP Certificate
b) Client ID
c) Client Secret
d) Depending on the library you might need to specify the OAuth2 grant type to be used →
client_credentials
e) Update the token URL to
(i) https://uat-accounts.adp.com/auth/oauth/v2/token for UAT access
(ii) https://accounts.adp.com/auth/oauth/v2/token for PRD access
f) Update the API root URL to
(iii) https://uat-api.adp.com for UAT access
(iv) https://api.adp.com for PRD access

J. How to push payroll data elements with Pay Data Input-Add API

• The Pay Data Input Add API will allow the creation of payroll data elements in the currently open
Vantage pay period for the impacted pay group. It has to be one API call per unique pay group.
• The payroll data elements that can be covered by the Pay Data Input Add API are the following
a) Regular and overtime hours, as well as any exception hours like vacation or sick time
b) One time earnings/payments like sales commissions or spot-on bonuses
c) Tax information and deduction contributions to be overridden in the pay period. Tax
information is only available in ADP Vantage HCM, not Enterprise HR or HR Anytime.
• It is important to know in advance the various payroll data elements’ codes to be used in the Pay
Data Input Add API request (please refer to the data dictionary for details).
ADP, the ADP logo and Always Designing for People are trademarks of ADP, Inc. Page 17
 ADP Marketplace REST API Job Aid

• As shown in the sequential diagram below, invoking the Pay Data Input API will create a batch and
the response will contain the batch-ID created. The consuming service will need to keep invoking
the call-back API afterwards to verify if the batch has been processed or not. Currently, the below
feature of call back URI is only available in ADP Vantage HCM, not Enterprise HR or HR Anytime.
Note: Batch validation is not available for Enterprise HR or HR Anytime. This means that these
clients will not have a way to check if the batch has run to success. There is plan to implement this
feature in a future release.

a) If the batch has been completed with or without errors, the service consumer will receive a
response with
▪ return code = 200
▪ the confirmMessage/resourceMessages/processMessages/processMessages/
idValue will have one of the following values
• success
• warnings
• failed
b) If the batch is still in-process or queued, the service consumer will need to make another call
to verify if the batch is still being processed or not
▪ return code = 202
▪ Retry-after header with value 60 secs
▪ the confirmMessage/resourceMessages/processMessages/processMessages/
idValue will have one of the following values
• processing
• queued

ADP, the ADP logo and Always Designing for People are trademarks of ADP, Inc. Page 18
 ADP Marketplace REST API Job Aid

K. Errors Troubleshooting FAQs

• How do I resolve HTTP 401 errors when trying to authenticate with ADP’s Security Token
Service?

An HTTP 401 error is returned from the ADP Security Token Service when you fail to provide valid
credentials in the request header. Please follow the suggested troubleshooting steps mentioned in
section I (see above) before contacting your ADP Representative for assistance.

• How do I resolve HTTP 401 errors when invoking an API?

ADP, the ADP logo and Always Designing for People are trademarks of ADP, Inc. Page 19
 ADP Marketplace REST API Job Aid

An HTTP 401 error is returned from APIs other than the ADP Security Token Service when you fail to
provide a valid bearer token in the request header. Please take these suggested troubleshooting steps
before contacting your ADP Representative for assistance:

i) Check to make sure you have added an Authorization header to your request along with the bearer
token you fetched from the security token service.
ii) Check to make sure you have a space between “Bearer” and the token you are using in the
Authorization header.
iii) Check the body of the response for an “expired token” message. If that message is present in the
response, fetching a fresh bearer token and re-submitting your request should resolve the issue.
• How do I resolve HTTP 403 errors?

An HTTP 403 error is returned from the server when the bearer token you provided is valid but you are
not authorized to access the resource you have requested. First, confirm that you have not made a
mistake in the request URI. If the request URI is correct, please contact your ADP Representative to
request access to the URI in question.

• How do I resolve HTTP 503 errors?

An HTTP 503 error is generally returned from the server when it’s offline going through either a
scheduled or unscheduled maintenance (e.g. version upgrade, hot fix, etc.). The best suggested
approach is to implement a retry mechanism and re-invoke the requested API(s) after 1 hour. Please
contact your ADP representative to inquiry on the dates of the scheduled maintenance windows.

• How do I resolve HTTP 504 errors?

An HTTP 504 error is returned from the server when it can’t process the request in a timely manner,
resulting in a ‘Time-Out’. The best suggested approach is to implement a retry mechanism and re-
invoke the requested API, with the same filter values if used, after that the 504 response is received.
Please contact your ADP representative if more than 3 consecutive 504s occur for the same API call.

• I can’t see the compensation elements returned in the Workers APIs, is something missing?

If the /hr/v2/workers or /hr/v2/workers/{associatedOID} APIs are not returning any of the compensation data
elements (e.g. pay period salary, annual rate, etc.), then it’s most probably due to the fact that the ‘View
Compensation Fields for Practitioners’ security setting is not turned on for the provisioned API
system user. Please contact your ADP representative helping you with the API integration in order to
turn on this security profile.

• I’m getting an error back when my application submits a new hire through POST
events/hr/v1/worker.hire

If the events/hr/v1/worker.hire returns a 400 error code back, then it probably means that some of the
elements from the request are invalid according to the ADP application’s business logic rules.

ADP, the ADP logo and Always Designing for People are trademarks of ADP, Inc. Page 20
 ADP Marketplace REST API Job Aid

In order to identify the element(s) from the request that are causing the error, you’ll need to identify the
error message code number returned in the below JSON objects from the response, and cross-check
them with the possible root cause from the attached form.
/confirmMessage/resourceMessages/processMessages/userMessage/codeValue

API Job Aid_Message

Codes_090718.xlsx

Update History (after Sept. 2018)

Date Description of Changes
6/2/2021 Updated sample SSN and DOBs to conform to GSO Standards (Pages: 6,9,13,14)
8/4/20 Various updates.
10/10/19 Updated Page 4 to update a hyperlink and correct typo in developers.adp.com reference.
11/28/18 Correction to token URL section. Incorrect values noted.
9/28/18 Republished version that incorporates Enterprise HR.

ADP, the ADP logo and Always Designing for People are trademarks of ADP, Inc. Page 21