Introduction to ADP RESTful APIs

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:

You can control the results returned by using the following query parameters:

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:

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:

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