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. Lumos syncs ADP workers, org units, and job codes on its regular integration sync schedule, and connecting or reconnecting the integration starts a sync right away. To refresh sooner, see Triggering Syncs Deep Dive. The read scope covers all syncing. Writing back is optional, and the only write Lumos performs is the business email update below. Lumos doesn’t hire, terminate, or rehire workers, and doesn’t change their org unit or job code assignments.

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 five values into the Lumos ADP integration to establish or re-establish the connection. All five come from ADP: Client ID, Client Secret, Account ID, 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 role: an Admin in Lumos. Only Admins can connect integrations (see Lumos roles).
  • 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

All scopes below start with /hr/workerInformationManagement/workerManagement/.

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 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 email-change scope and edit privilege on the Contact object in ADP (Part A). That lets Lumos update a worker’s business email. Watch out for. Scopes are set on the ADP project itself, not toggled inside Lumos, so grant the email-change scope 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. For the Merge-powered card, see ADP Workforce Now (Merge).

Instructions

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

You complete this part 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: Lumos reads everything it syncs (workers, org units, job codes and titles, departments, and custom fields) from ADP worker records through the Workers API (/hr/v2/workers). Confirm the project includes the Workers (HR Workers v2) API under Worker Management, which grants worker.read, while you’re in this screen. A project built from a read-only template, such as Worker Demographic Data (Read Only), may not include worker.read, so check that the scope is listed.

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, 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 values to hand to Lumos

All of these come from ADP.

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 Direct API ADP Workforce Now tile: it’s the one that asks for Client Id, Client Secret, Account Id, Ssl Cert, and Ssl Key. The Merge card shows ADP Workforce Now (MERGE) with only a Connect button.
  2. In Client Id, enter the Client ID from Part C. If you’re reconnecting, confirm it matches the ADP project from Part C so you’re pointing at the same project.
  3. In Client Secret, paste the Client Secret (use Show Secret in ADP to verify what you copied).
  4. In Account Id, enter the Account ID. If you’re reconnecting, confirm it’s still present.
  5. In Ssl Cert, paste the SSL certificate (copied with ADP’s View → Copy button). In Ssl Key, paste the private key from Part B.
  6. Check all fields, then click Connect. Lumos checks the credentials by reading a worker record from ADP, and the card then shows the integration’s sync status. Workers appear after the first sync completes.
ADP certificates expire. Before yours does, generate a new one (Part B), then reconnect the card with the new certificate in Ssl Cert and the new key in Ssl Key. 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 stops working after it was fine. The certificate may have expired. Generate a new one (Part B) and reconnect the card with the new certificate and key. Connection fails right after generating a new certificate. New certificates go through an activation step on ADP’s side. Wait and retry before regenerating. Email updates fail. The Update Email action needs the email-change scope enabled on the ADP project and edit privilege on the Contact object. With only the read scope, syncing works but email updates fail. Credentials can’t access API Central. Contact ADP Support. Some credential issues can only be resolved on their side. Team, Title, or Manager stopped populating after switching from the Merge connector. Your Source of Truth attributes still point at the old Merge instance, which no longer syncs. Both connectors show the name ADP Workforce Now in the Source App dropdown. In Settings → Source of Truth, edit each attribute, select the Direct API instance, and use these Source Field Names: Update Start Date, End Date, and any Custom Attributes the same way, then run a sync. See Troubleshooting attribute sources.