Overview

This guide provides an overview of using Postman to make your first application programming interface (API) call to ADP.

Intended audience

This document is intended for:

• Architects
• Developers

Prerequisites

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
• Private key

Installing and preparing postman

1. Install Postman from https://www.getpostman.com/apps

2. Using the following steps, add your ADP issued .PEM file and your .KEY file (generated as part of the CSR process) into Postman for the domains. You can use the instructions found at https://www.getpostman.com/docs/postman/sending_api_requests/certificates)

   • Click 'Settings'
     
     

   • Click Certificates, Add Certificates and select the CRT file (certificate) and KEY file, then click Add.
     
     
      

     This step has to repeated for the following Hosts:

     • https://accounts.eu.adp.com

     • https://api.eu.adp.com

     
     
     
      

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

Import the Postman collections 

Postman allows you to store a collection of APIs and share them with others. For example, you can find the collection examples used in this document by clicking here. When at the location, download the file and click Import to import the list file.

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. Please verify if you are granted the permission by the IT department to execute the process below.

1. In Postman, open the token request. To expose the headers, click Headers.
   
   

2. If your POST request is successful, you will receive an HTTP 200 from the server with your token in the body of the response. Copy the access_token value.
   
   
    

3. You will receive an Access Token in 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

The following sample shows selecting the GET HR - Worker (List) API and making the first call.

1. Open feature call request.
2. Paste your bearer token into the Token field and click Send
   
   

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:

HTTP 401 error when trying to authenticate

Error
An HTTP 401 error is returned from the ADP Security Token Service when you fail to provide valid credentials in the request header or missing/incorrect certificate.

Resolution
Take the following suggested 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 Sscret before sending them to the authorization header
• Make sure you are including your ADP-issued SSL Certificate in the request.

HTTP 401 error

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 suggested 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. The Header ‘WWW- Authenticate’ will provide the value ‘Bearer error=’Invalid request’ when this occurs.
• 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

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 have not made a mistake in the request Uniform Resource Indicator (URI). If there quest URI is correct, contact your ADP Representative to request access to the URI in question.

HTTP 404 error

Error
An HTTP 404 error is returned from the server when the URL you provided is invalid.

Resolution
First, confirm that you have not made a mistake in the requested URL. If the requested URL is correct, contact your ADP Representative.