Getting Started

Installation

Install the ADP API Client using pip:

pip install adpapi

Setting Up Credentials

ADP requires an OAuth 2.0 client ID/secret plus a mutual-TLS certificate and key file. The recommended approach is to load credentials from environment variables:

# .env
CLIENT_ID=your_client_id
CLIENT_SECRET=your_client_secret
CERT_PATH=certificate.pem   # optional, defaults to certificate.pem
KEY_PATH=adp.key            # optional, defaults to adp.key

from dotenv import load_dotenv
from adpapi import AdpApiClient, AdpCredentials

load_dotenv()
credentials = AdpCredentials.from_env()

You can also pass credentials directly:

credentials = AdpCredentials(
    client_id="your_client_id",
    client_secret="your_client_secret",
    cert_path="/path/to/certificate.pem",  # optional
    key_path="/path/to/adp.key",           # optional
)

Your First Request

Use AdpApiClient as a context manager (recommended) so the underlying HTTP session is always closed cleanly:

with AdpApiClient(credentials) as client:
    results = client.call_endpoint(
        endpoint="/hr/v2/workers",
        select=["workers/person/legalName/givenName", "workers/person/legalName/familyName1"],
        masked=True
    )
print(results)

call_endpoint automatically handles pagination — it keeps fetching pages until the API signals there are no more results, then returns all records as a flat List[Dict].

Fetching a Single Worker by ID

When you already have a specific resource ID, use call_rest_endpoint instead:

with AdpApiClient(credentials) as client:
    results = client.call_rest_endpoint(
        endpoint="/hr/v2/workers/{associateOID}",
        associateOID="G3349PRDL000001",
        select=["workers/person/legalName"]
    )

You can also pass a list of IDs to fetch multiple workers in a batch:

with AdpApiClient(credentials) as client:
    results = client.call_rest_endpoint(
        endpoint="/hr/v2/workers/{associateOID}",
        associateOID=["G3349PRDL000001", "G3349PRDL000002", "G3349PRDL000003"]
    )

Parallel Batch Requests

When fetching many resources by ID, use the max_workers parameter to issue requests in parallel. This can yield up to ~10x throughput improvement compared to sequential fetching:

aoid_list = ["G3349PRDL000001", "G3349PRDL000002", "G3349PRDL000003", ...]

with AdpApiClient(credentials) as client:
    # Fetch 50 workers across 10 threads ~10x faster than sequential
    results = client.call_rest_endpoint(
        endpoint="/hr/v2/workers/{associateOID}",
        max_workers=10,
        associateOID=aoid_list
    )

With max_workers=1 (the default), requests are made sequentially. Increasing max_workers sends that many requests concurrently using a thread pool. A good starting value is 10.

Choosing the Right Method

Scenario	Method
List/search records with OData filters or pagination	call_endpoint
Fetch a specific resource by ID	call_rest_endpoint
Batch-fetch several known IDs	call_rest_endpoint with a list
Fast parallel batch fetch	call_rest_endpoint with a list + max_workers

Next Steps

• How-To Guides — filtering, logging, and other common tasks
• API Reference — full parameter documentation
• Concepts — authentication flow, token lifecycle, and more

Logging Configuration

Source code in src/adpapi/logger.py

def configure_logging():
    logger = logging.getLogger("adpapi")
    logger.setLevel(logging.DEBUG)

    formatter = logging.Formatter("%(asctime)s - %(levelname)s - %(message)s")

    # File handler
    file_handler = logging.FileHandler("app.log", mode="w")
    file_handler.setLevel(logging.DEBUG)
    file_handler.setFormatter(formatter)
    logger.addHandler(file_handler)

    # Console handler
    console_handler = logging.StreamHandler()
    console_handler.setLevel(logging.DEBUG)
    console_handler.setFormatter(formatter)
    logger.addHandler(console_handler)