Introduction to ADP RESTful APIs

Summary: Outlines how ADP RESTful APIs are used.

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:

GET

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:

POST

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:

GET

https://api.adp.com/core/v1/event-notification-messages

For more information, please see ADP Event APIs and Notification Guide.