Developer guide to get employee data from ADP Run API

Introduction

This article is a part of a series of HRIS integration articles covering the ADP Run API in depth, and covers the specific use case of using the ADP Run API to get employee data.

Get Employee Data from ADP Run API

Prerequisites

• Obtain OAuth 2.0 credentials (Client ID and Client Secret) from ADP.
• Ensure you have the necessary permissions to access worker data.
• Install Python and the requests library.

API Endpoints

• Get all employees: /hr/v2/workers
• Get a specific employee: /hr/v2/workers/{aoid}

Step-by-Step Guide

1. Get All Employees

import requests

def get_all_employees(access_token):
    url = "https://api.adp.com/hr/v2/workers"
    headers = {
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json"
    }
    
    response = requests.get(url, headers=headers)
    
    if response.status_code == 200:
        return response.json()
    else:
        return response.status_code

2. Get a Specific Employee

def get_employee_by_aoid(access_token, aoid):
    url = f"https://api.adp.com/hr/v2/workers/{aoid}"
    headers = {
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json"
    }
    
    response = requests.get(url, headers=headers)
    
    if response.status_code == 200:
        return response.json()
    else:
        return response.status_code

Common Pitfalls

1. Using incorrect or missing OAuth 2.0 credentials.
2. Not having the right permissions to access worker data.
3. Calling the wrong API endpoint.
4. Ignoring HTTP response codes instead of handling them properly.
5. Letting access tokens expire without refreshing them.

Frequently Asked Questions

1. What format does the ADP Run API return data in?
All responses are in JSON format, making them straightforward to parse in most programming languages.

2. How do I handle pagination when fetching employees?
ADP uses OData parameters for pagination. Use $top to limit results per page and $skip to move through subsequent pages.

3. What should I do if I get a 401 Unauthorized error?
This usually means your access token is invalid or expired. Refresh your token using OAuth 2.0 and retry the request.

4. Can I filter the employee data I retrieve?
Yes. Use the OData $filter parameter to narrow results (e.g., filter by department or employment status).

5. How can I return only specific fields in the response?
Use the OData $select parameter to specify exactly which fields you want, instead of retrieving the entire object.

Knit for ADP Run API Integration

For quick and seamless access to ADP Run API, Knit API offers a convenient solution. By integrating with Knit just once, you can streamline the entire process. Knit takes care of all the authentication, authorization, and ongoing integration maintenance. This approach not only saves time but also ensures a smooth and reliable connection to your ADP Run API.

‍