Skip to main content
This article covers the Direct API connector for ADP Workforce Now. You authenticate with an OAuth app you configure in ADP API Central (Client ID and Client Secret) plus an SSL certificate and key pair, rather than through Merge.

​
After this article

You will be able to connect ADP Workforce Now to Lumos so ADP worker records, organizational units, and job codes sync into Lumos, and use ADP as a source of user data.

​
Capabilities

Sync means Lumos reads the data. Provision means Lumos can write it. Provisioning is optional and follows what you configure in ADP. The read scope covers all syncing. The write scopes cover account lifecycle and entitlement management, and the business email update is the active write path today.

​
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 and key pair. Once the ADP side is configured, you copy four values into the Lumos ADP integration to establish or re-establish the connection. All four originate in ADP: Client ID, Client Secret, SSL Certificate, and SSL Key.

​
Required plan and roles

  • ADP access: access to ADP API Central for your ADP Workforce Now instance, using the account that owns the OAuth app or project used for Lumos.
  • An ADP project: create a project in API Central for this integration. The name can be anything.
  • Lumos access: the Integrations page in Lumos, where you paste the values and connect.
  • A decision on scope: Lumos supports read-only syncing as well as writing email updates back to ADP. 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

​
Read-only access vs provisioning

Is read-only possible? Yes. The read scope (worker.read) and the write scopes are enabled separately on your ADP project, so you can grant only the read scope and get syncing without any writes. What read-only requires. The same four values as any connection, with only the read scope enabled on the ADP project. Follow the steps below but skip the write scopes and the edit privileges in Part A. What write access requires. The same values plus the write scopes above and edit privilege on the Contact object in ADP (Part A). The email-change scope drives the active write path, updating a worker’s business email from Lumos. Watch out for. Scopes are set on the ADP project itself, not toggled inside Lumos, so grant the write scopes in ADP before connecting if you want write access from the start. This Direct API connector is also a separate connection from the Merge-powered ADP Workforce Now card. Use whichever card matches what you’re trying to do rather than expecting one to become the other.

​
Instructions

​
Part A: Configure API permissions and APIs in ADP API Central

This is done inside your ADP project in API Central. It 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 screen for the Lumos project and review the edit-privilege toggles.
  2. Grant view privilege for Status.
  3. Grant view privilege for Personal Profile.
  4. Confirm Contact is included, and grant edit if you want to update emails from Lumos. In ADP, Contact is where emails and phone numbers live (check View Details on an employee under Employment / Personal Information). This object is required for writing email updates back.
  5. Save the permission changes.
A2. Add the required API products
  1. Go to the project’s APIs section and click Add more APIs.
  2. Add Applicant Onboarding. Click Add on both variants presented.
  3. Add Custom Fields, again both variants.
  4. Add the email-change APIs. Search “email”, then add the Email change product and the entry directly above it. These map to worker.business-communication.email.change.
  5. Apply email change to business email only. Personal email flows in from ADP and shouldn’t be written back, so only the business-communication variant is needed.
  6. Skip anything you don’t need, such as payroll, benefits, or dependents.
  7. Save the changes to the project.
Watch out: the connector syncs workers, org units, job codes and titles, departments, and custom attributes. Confirm the API products covering those objects 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 and 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 common name so you know which one is current, for example “lumos production”.
  4. Save all three generated artifacts immediately: the Certificate, the private Key, and the CSR. They won’t 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 and 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 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: Connect the integration in Lumos

  1. In Lumos, open Integrations and search for “ADP” (reconnect an existing card or add a new one). Select the correct ADP Workforce Now tile.
  2. Confirm the Client ID matches the ADP project from Part C so you’re pointing at the same project.
  3. Paste the Client Secret (use Show Secret in ADP to verify what you copied).
  4. Confirm the Account ID is present.
  5. Paste the SSL Certificate (copied with ADP’s View → Copy button) and the SSL Key (the private key from Part B).
  6. Sanity-check all fields, then click Connect.
For more detail, see ADP’s guide on troubleshooting app integrations with ADP. Reach out to ADP Support if the generated credentials can’t access API Central. There are times when their support is required.

​
Troubleshooting

Can’t connect the integration. Confirm the Client ID and Client Secret came from the same ADP project, and that the certificate and private key belong to the same pair. A mismatched certificate or key blocks the OAuth handshake. If the paste looks right but the connection still fails, re-copy the certificate with ADP’s View → Copy button, since a manual copy can carry hidden characters. Connection fails right after generating a new certificate. New certificates go through an activation step on ADP’s side. Wait and retry before regenerating. Provisioning actions fail. Writes need the write scopes enabled on the ADP project and edit privilege on the Contact object for email updates. With only the read scope, syncing works but writes fail. Credentials can’t access API Central. Contact ADP Support. Some credential issues can only be resolved on their side.