Making Your First API Call Using Postman

Overview

This guide provides an overview of using Postman to make your first Application Programming Interface (API) call to ADP.

What's New in this Guide?

July 2020

Updated the following: 

• Uniform Resource Locator (URL) in the Installing and Preparing Postman section
• Various steps under all sections
• ADP endpoint information
• Screen captures under all sections

Prerequisite

You need to have the following ready before making your first API call:

• Client ID and Client Secret - If you don't have this information, contact your client representative.
• Certificate Signing Request (CSR) - For more detailed information, see Generating a Certificate Signing Request.

Installing and Preparing Postman

1. Install Postman from https://www.postman.com/downloads/.
2. Using the following steps, add your ADP issued certificate file and your .KEY file (created as part of the CSR process) into Postman for each of the environments you are using. You can use the instructions found at https://learning.postman.com/docs/sending-requests/certificates/.
   • Click Settings from the menu.
     
     
      
   • Complete the following instruction twice. Once with accounts.adp.com as the Host and once with api.adp.com as the Host. 
     If you are connecting to a UAT instance, the Host is uat-accounts.adp.com and uat-api.adp.com, respectively.
   • Click Certificates and enter the Host, CRT file (certificate) and KEY file. Then, click Add.
     
     
     
     

   • On the Settings page, turn the SSL certificate verification on.

     If you're not prompted to select a Secure Sockets Layer (SSL) certificate and this is your first request in this Postman session, you should make sure your SSL certificate is installed correctly. After you have selected the proper certificate, you won't be prompted again for a certificate until you start a new Postman session. If you know your SSL certificate is installed correctly, close Postman, open the Google Chrome browser, and try your request again. 

     
     

3. If needed, import the ADP APIs.
   Postman allows you to store a collection of APIs and share them with others. ADP will continue to share sample collections on GitHub.
   For example, you can find the ADP Workforce Now collection by clicking here. When at the location, download the file and click Import to import the list file.

   

Making Your First Call

Requesting a Bearer Token

Each request to one of ADP's APIs needs to be accompanied by an Authorization header containing a bearer token issued by the ADP Security Token Service.

1. Create a new POST call to https://accounts.adp.com/auth/oauth/v2/token. If you have downloaded one of the ADP collections available on GitHub, you may have pre-built calls that do much of this work for you.
2. Open the Headers tab to expose the headers and add a Content-Type header with the Value of application/x-www-form-urlencoded.
   
   
    
3. Open Body, and enter the keys as shown in the following screen capture (using your own API Client ID and Secret).
   
   

   If you are connecting to a UAT environment, the URL for this call is https://uat-accounts.adp.com/auth/oauth/v2/token.

   If your POST request is successful, you'll receive an HTTP 200 from the server with your token in the body of the response. Copy the access_token value. 
   
   
    
4. You'll receive an Access Token in the response, which is valid for 1 hour. The same can be used to make API calls by adding the following header: 
   Authorization: Bearer {accessToken}

Making an API Call with Your Bearer Token

If you already have an API collection, you can select an API from a collection. The following sample shows selecting the GET HR - Worker (List) API and making the first call.

1. Open the HR > Worker (List) request and click Headers to expose the headers.

2. Paste your bearer token into the Authorization header and click Send.
   
   

   Remember to leave the Bearer and a space to the left of your token. Since Postman is a browser-based application, the browser caching mechanism will save responses to the cache. To ensure that changes you make in ADP applications are reflected in Postman, we recommend placing a cache-buster into the query string between each request.
   For example, preventCache=timestamp, where timestamp is a unique value such as the current time. You won't need to do this when you're building your application because browser-based caching won't come into play.

If your request was successful, you'll receive an HTTP 200 message from the server within a few records. The following sample shows a response of the GET HR - Worker (List) API request:

Frequently Encountered Errors and Resolutions

Received an HTTP 401 Error when trying to authenticate with ADP's Security Token Service

Error

An HTTP 401 error is returned from the ADP Security Token Service when you fail to provide valid credentials in the request header.

Resolution

Take the following troubleshooting steps before contacting your ADP Representative for assistance:

• Make sure you have base-64 encoded in your Open Authorization 2 (OAuth2) Client ID and Client Secret before sending them to the Authorization header.
• Make sure you are also base-64 encoding the colon (:) between your OAuth2 Client ID and Client Secret.
• Make sure there is a space between Basic and your base-64 encoded credentials.
• Make sure you are including your ADP-issued Secure Socket Layer (SSL) Certificate in the request.

Received an HTTP 401 Error from other APIs

Error

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.

Resolution

Take the following troubleshooting steps before contacting your ADP Representative for assistance:

• Make sure you have added an Authorization header to your request along with the bearer token you fetched from the ADP Security Token Service.
• Make sure you have a space between the Bearer and the token you are using in the Authorization header.
• 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 resubmitting your request should resolve the issue.

Received an HTTP 403 Error

Error

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.

Resolution

First, confirm that you haven't made a mistake in the request Uniform Resource Indicator (URI). If the request URI is correct, contact your ADP Representative to request access to the URI in question.

Other Useful Links

• API Common Exceptions and Tips for Handling
• Sample Postman collection: https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/ADP%20WFN%20APIs.postman_collection.json

Using the Postman Collection

1. Navigate to https://github.com/adpllc/marketplace-sample-payloads/tree/master/wfn.
2. Copy the entire JavaScript Object Notation (JSON), which is highlighted as follows:
   
   
    
3. Select Postman > Import Tab > Paste Raw Text.
   
   
    
4. Click Import.