Connecting ADP Workforce Now

Overview

Background

This article walks through the requirements and steps for connecting the ADP Workforce Now integration to Lumos.

What you are setting up

Lumos connects to ADP Workforce Now using OAuth 2.0 client-credentials. That requires an OAuth app in ADP API Central with the right API products enabled, plus an SSL certificate/key pair. Once configured on the ADP side, four values are copied into the Lumos ADP integration to establish (or re-establish) the connection.

The four values Lumos needs (all originate in ADP): Client ID, Client Secret, SSL Certificate, SSL Key.

Before you start

• Access to ADP API Central for your ADP Workforce Now instance (the account that owns the Lumos OAuth app / project).

• Create an ADP project in API Central used for this integration, this can be named anything

• Access to the Lumos app (Integrations page) to paste the values and reconnect.

• Decide scope, Lumos supports read-only as well as allowing updates to email. Lumos only does what you configure it to do.

Application Scopes

Read (required):

• /hr/workerInformationManagement/workerManagement/workerProfileManagement/worker.read

Write (required for account provisioning and entitlement management):

• /hr/workerInformationManagement/workerManagement/lifecycleManagement/worker.hire

• /hr/workerInformationManagement/workerManagement/lifecycleManagement/worker.terminate

• /hr/workerInformationManagement/workerManagement/lifecycleManagement/worker.rehire

• /hr/workerInformationManagement/workerManagement/workAssignmentManagement/worker.workAssignment.modify

• /hr/workerInformationManagement/workerManagement/communicationManagement/worker.businessCommunication.email.change

Part A — Configure API permissions & APIs in ADP API Central

Done inside your ADP project in API Central. This grants the connector read access to the data it syncs, plus write access to the one field being updated (work email).

A1. Set the API access permissions (edit privileges)

1. Open the permissions / access screen for the Lumos project and review the edit-privilege toggles.

2. Grant view/read privilege for "Status."

3. Grant view/read privilege for "Personal Profile."

4. Confirm "Contact" is included, and ensure edit is granted if you wish to update emails using Lumos. In ADP, Contact is where emails and phone numbers live (check View Details on an employee under Employment / Personal Information). This is the object that allows the work email address to be updated — it is required for writing back updates.

5. Save the permission changes.

A2. Add the required API products

6. Go to the project's APIs section and click "Add more APIs."

7. Add "Applicant Onboarding." Add both variants presented (click Add on each).

8. Add "Custom Fields." Add both variants.

9. Add the Worker / Business Communication email-change APIs. Search "email", then add the "Email change" product (add both it and the entry directly above it). These map to worker.business-communication.email.change.

10. Apply email change to business email only. Personal email flows in from ADP and should not be written back, so only the business-communication variant is needed.

6. Skip anything you don't need (e.g., payroll, benefits, dependents).

7. Save / commit the changes to the project.

⚠ Watch out: The exact list of syncable objects for the connector includes workers, org units, job codes/titles, departments, and custom attributes — confirm those API products are present while you're in this screen.

Part B — Generate the SSL certificate in ADP API Central

The OAuth app authenticates with a certificate/key pair. If you don't have a known-good, currently-active certificate saved, generate a fresh one rather than guessing which old cert is live.

1. Go to Credentials → Manage for the project, then open Manage Certificate.

2. Click "Request Certificate," then Next.

3. Enter a recognizable name / common name so you know which one is current — e.g. "lumos production."

4. Save all three generated artifacts immediately. The Certificate, the private Key, and the CSR (certificate signing request) — these will not be shown again. Store them somewhere secure.

5. Click Next, then Done.

6. Wait for ADP to activate the certificate. New certs go through an approval step on ADP's side. Sometimes it's immediate; sometimes it takes a while before it starts working.

⚠ Watch out: When copying the certificate later, use ADP's own Copy button (API Central → View → Copy). A manual copy can introduce hidden Unicode/odd characters that break the paste into Lumos.

Part C — Collect the four values to hand to Lumos

All four originate in ADP API Central:

Part D — Reconnect the integration in Lumos (handoff)

This is the downstream step where the ADP values are entered. Included so the process is end-to-end.

1. In Lumos, open Integrations and search for "ADP." Select the correct ADP Workforce Now tile.

2. Confirm the Client ID matches ADP (e.g. starts with "4CC") to verify you're pointing at the same project.

3. Paste the Client Secret (use "Show Secret" to verify).

4. Confirm the Account ID is present.

5. Paste the SSL Certificate (the cert copied from ADP's View → Copy) and the SSL Key (the private key).

6. Sanity-check all fields — Client ID, Secret, Certificate — then click "Connect."

For more details, see: https://developers.adp.com/getting-started/key-concepts/troubleshoot-app-integrations-with-adp. Reach out to ADP Support if the generated credentials are not able to access API Central, there are times when support is required.

Capabilities