About ADP
ADP is one of the largest providers of payroll, HR, tax, and benefits administration software, serving organizations through platforms such as ADP Workforce Now, Vantage HCM, GlobalView, and RUN. Connecting ADP to Serval lets your team query worker data and automate employee-lifecycle and payroll-adjacent workflows against ADP’s REST APIs.The ADP integration is in beta. Read Current beta limitation before building workflows on top of it.
What the ADP integration enables
| Capability | Description |
|---|---|
| Worker data access | Query ADP’s Workers API (/hr/v2/workers) and any other REST API enabled for your ADP API client |
| Workflow automation | Call ADP endpoints from Serval workflows via the ADP API request action |
ADP does not use OAuth scopes that you select when connecting. Which APIs your credentials can call — and which fields they return — is governed by the API products and data-access consents enabled for your API client on ADP’s side. Work with your ADP representative to enable the APIs you need.
How ADP authentication works
ADP secures its APIs with OAuth 2.0 client credentials plus mutual TLS (mTLS). The client certificate ADP issued for your API client must be presented on every HTTPS call — including the token request itself. A call made without the certificate is rejected during the TLS handshake, before it ever reaches ADP’s application layer. Connecting ADP to Serval therefore requires four credentials, plus a region:| Credential | What it is |
|---|---|
| Client ID | The identifier of your ADP API client |
| Client Secret | The secret paired with the Client ID |
| mTLS Client Certificate | The PEM certificate ADP issued or registered for this API client (sometimes called the Web Services or mutual-TLS certificate) |
| mTLS Private Key | The PEM private key matching that certificate |
Regions
ADP serves North America and international tenants from different gateways:| Region | Token endpoint | API gateway |
|---|---|---|
| North America | accounts.adp.com | api.adp.com |
| International | accounts.eu.adp.com | api.eu.adp.com |
Current beta limitation
Serval presents your client certificate when validating credentials and when exchanging tokens. However, workflow API requests travel through Serval’s shared integration proxy, which does not yet attach per-integration client certificates. Until that support ships:- The ADP API request workflow action and the built-in health check (<001> Test ADP Connection) report failures even when your connection is configured correctly — ADP’s gateway rejects the call during the TLS handshake.
- Your credentials are still fully verified: Serval performs a real mTLS token exchange against ADP when you connect (and again every time you edit the connection). If your credentials may have changed since connecting, edit and re-save the connection to re-validate them.
ADP configuration
Prerequisites
- An ADP product with API access (for example ADP Workforce Now, Vantage HCM, or GlobalView)
- Either ADP API Central — ADP’s self-service API administration product, available on the ADP Marketplace — or an ADP representative who can provision a custom API integration for you
- Administrator access to API Central, if you’re using the self-service path
Step 1: Get a Client ID and Client Secret
If your organization has ADP API Central: sign in to API Central, create (or open) the API project for this integration, and copy its generated Client ID and Client Secret. If not: your ADP representative can provision an API client for a custom integration and deliver the Client ID and Client Secret to you.Step 2: Get the mutual TLS certificate and private key
ADP issues and registers an X.509 client certificate for each API client. There are two common ways to obtain one:- Generate it in ADP API Central. API Central can create the certificate and key pair for you.
- Bring your own key (CSR flow). Generate a key pair yourself, submit a certificate signing request to ADP (via API Central or your representative), and ADP returns the signed certificate. You keep the private key.
ADP client certificates are valid for two years. Track the expiry date — see Rotating or renewing the certificate for the renewal procedure.
Step 3: Confirm your region and enabled APIs
Confirm with your ADP representative which gateway your organization is served from (North America or International), and that the APIs you plan to call — for example the Workers API — are enabled for your API client. For ADP’s own documentation and API reference, see the ADP developer portal.Serval configuration
Enter your credentials
| Field | Required | Description |
|---|---|---|
| Client ID | Yes | The Client ID of your ADP API client |
| Client Secret | Yes | The Client Secret paired with the Client ID |
| mTLS Client Certificate | Yes | Paste the full PEM certificate, including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines |
| mTLS Private Key | Yes | Paste the full PEM private key matching the certificate, including the BEGIN/END lines |
| CA Bundle | No | Optional PEM bundle to pin the root CAs used to verify ADP’s servers. Leave empty to use the system trust store |
| Region | Yes | North America (default) or International — see Regions |
Save and validate
Click Save. Before storing anything, Serval:
- Parses the certificate and private key, and checks that they match
- Performs a live token exchange against your region’s ADP token endpoint over mTLS (this can take a few seconds)
After connecting, the built-in health check (<001> Test ADP Connection) currently reports a failure even for valid connections — see Current beta limitation. The live validation at save time is the source of truth for your credentials.
Using ADP in workflows
Once connected, call ADP from workflows with the ADP API request action. Pass thepath, method, and optional query, body, and headers — Serval resolves the region-specific host (api.adp.com or api.eu.adp.com) from the connection and injects the bearer token automatically.
ADP does not publish a single consolidated OpenAPI spec, so the action is schema-less: resolve endpoint shapes from the ADP developer portal or the API documentation in ADP API Central. For example, the Workers API is paginated with $top and $skip:
Troubleshooting
”The certificate or private key could not be parsed”
- Paste the complete PEM blocks, including the
-----BEGIN ...-----and-----END ...-----lines - Make sure the private key matches the certificate — a key from a different certificate (or a regenerated one) will fail
- Avoid stray characters or lost line breaks introduced by copy/paste
”ADP rejected the credentials”
- Verify the Client ID and Client Secret are correct and belong to the same API client
- Verify the certificate is the one ADP issued or registered for this API client — a certificate from another project fails the handshake
- Check whether the certificate has expired (ADP certificates are valid for two years):
openssl x509 -enddate -noout -in cert.pem - Confirm you selected the correct region — credentials for one gateway are rejected by the other
Health check fails after a successful connect
Expected during the beta — see Current beta limitation. Your credentials were verified with a live mTLS token exchange when you saved the connection.Rotating or renewing the certificate
- Generate a new certificate (and key) in ADP API Central, or submit a new CSR through your ADP representative
- In Serval, open the ADP connection and edit it
- Paste the new mTLS Client Certificate and mTLS Private Key. Fields you leave untouched keep their stored values, so you don’t need to re-enter the Client ID or Client Secret
- Save — Serval re-validates the new material with a live token exchange before storing it
The optional CA bundle can be replaced on edit but not cleared. To remove a CA bundle entirely, disconnect and reconnect the integration.
Need help? Contact support@serval.com for assistance with your ADP integration.