Summary
ADP Application Programming Interfaces (APIs) are designed using an event-based pattern for resource management. This pattern separates the act of retrieving resources and modifying them into separate activities along with providing event notifications indicating changes to a resource.
Retrieving Resources
The most common method to retrieve resources through the ADP Representational State Transfer (RESTful) APIs is to do a GET against the resource endpoint. By default, this request returns all resources of a given type, but supports several query parameters to control what's returned.
For example, the resource you are interested in is Worker v2. The request to get all workers is:
https://api.adp.com/hr/v2/workers
You can control the results returned by using the following query parameters:
Parameter | Description |
---|---|
$top | Specifies the upper limit on the number of items to return. |
$skip | Specifies the number of items to skip from the beginning of the list. |
$orderby | Specifies an expression used to order the items to be returned. |
$select | Specifies the properties of the items to include in the response. |
$filter | Specifies an expression that an item must match to be included in a response. |
Another example is that you can do the following:
- Request only the first 10 workers:
GET
https://api.adp.com/hr/v2/workers?$top=10*
- Request that the workers be returned sorted by last name:
GET
https://api.adp.com/hr/v2/workers?$orderby=/person/legalName/familyName1
Modifying Resources
Events, such as requests for modification, are posted to ADP and each event specifies the target of the change and the modification requested. The response to the request lets you know if the requested change was made or rejected.
For example, a Worker v2 used in the previous example, can contain a list of personal email addresses. There are three events defined that enable making changes to a worker's personal email address list. These events are:
- Add Worker Personal Email v1
- Change Worker Personal Email v1
- Remove Worker Personal Email v1
Another scenario would be to add a new email address to a worker. The following post is adding the email address mynewemail@gmail.com to the user with the associate object ID (OID) specified in the event context of the event:
https://api.adp.com/events/hr/v1/worker.personal-communication.email.add
Request payload:
{
"events" : [ {
"serviceCategoryCode" : {
"codeValue" : "hr"
},
"eventNameCode" : {
"codeValue" : "worker.personalCommunication.email.add"
},
"originator" : {
"associateOID" : "G557KMGC6KCSVZRD"
},
"actor" : {
"associateOID" : "G557KMGC6KCSVZRD"
},
"data" : {
"eventContext" : {
"worker" : {
"associateOID" : "G3GMA28TB2SVJ2TF"
}
},
"transform" : {
"eventStatusCode" : {
"codeValue" : "submit"
},
"worker" : {
"person" : {
"communication" : {
"email" : {
"emailUri" : mynewemail@gmail.com
}
}
}
}
}
}
} ]
}
In this case the response shows the email was successfully added. This is indicated by a 201 HTTP response code along with the eventStatusCode and the content in the output section of the event:
{ "events" : [
{
"eventStatusCode" : {
"codeValue" : "complete",
"shortName" : "complete"
},
"data" : {
"eventContext" : {
"worker" : {
"associateOID" : "G39YC8VQ618GBFP9"
}
},
"output" : {
"worker" : {
"person" : {
"communication" : {
"email" : {
"emailUri" : mynewemail@gmail.com
}
}
}
}
}
}
}
]
}
Event Notifications
Applications can receive notifications of changes. All the notifications subscribed to are received at a single API endpoint, shown as follows:
https://api.adp.com/core/v1/event-notification-messages
For more information, please see ADP Event APIs and Notification Guide.