Connect ADP Workforce Now

Connect ADP Workforce Now so the people, teams and pay in Flowstate follow what HR records in ADP. Hires, leavers, pay changes and hours changes reach the forecast without anyone re-keying them.

Setting it up takes your ADP administrator, your integration team and a Flowstate admin. First decide whether ADP is your source of truth. See Get your people data into Flowstate.

How it connects

ADP sends an event whenever a worker changes, and requires a client certificate on every call to its APIs. Both are handled by your integration platform, such as Workato, Boomi or MuleSoft. The platform takes the event, reads the worker from ADP, and updates Flowstate through its REST API.

Route	How it works	Best for
Event-driven (recommended)	ADP sends each event, such as a hire or a pay change, to a webhook on your integration platform, or your platform reads ADP's event queue. The platform reads the worker from ADP and updates Flowstate through the REST API.	Every ADP Workforce Now organisation
Scheduled sync	A Flowstate custom integration reads ADP on a schedule.	Not used for ADP. A custom integration can't present ADP's client certificate. If you'd rather not receive webhooks, your platform can read ADP's event queue on a schedule instead.

Why event-driven is recommended: it's the route ADP's security allows. Every call to ADP must carry the client certificate ADP issued, and only your integration platform can hold it. ADP's webhooks also need a public receiving address hosted in the US, which your platform provides.

What you need from ADP

• ADP API Central for ADP Workforce Now, bought by your organisation from ADP, with a project for Flowstate.
  • Or, if your integration platform connects as an ADP Marketplace app, an ADP administrator consents to that app. Until they do, it gets no credentials.
• A client certificate for the project. ADP issues it from a certificate signing request, and it goes with every call.
• API access in the project's scope: worker information and departments, plus job requisitions if you sync vacancies. Job requisitions are only available to US and Canadian clients.
• People access set by your ADP administrator, so the connection sees the employees you want to sync. Pay is sensitive in ADP and needs access to full worker information.
• For webhooks: a receiving address on your integration platform that's public and hosted in the US.

Set it up

Your Flowstate contact provides the integration logic for ADP Workforce Now, and works through it with your integration team. There's no one-click connection.

In ADP

1. In ADP API Central, open or create the project your integration team uses for Flowstate.
2. Add worker information and departments to the project's APIs, and job requisitions if you need them.
3. Create the certificate signing request, get the client certificate, and give it to your integration team with the client ID and secret.
4. In Workforce Now, go to Setup → Security → Access Permissions → People Management and set the connection user's People Access to the employees you sync.
5. Go to Projects, select your project, then APIs → Events → Add Events. Add the worker changes you need, such as hires, pay changes, standard hours changes and worker type changes.
6. For webhooks: enter your integration platform's receiving address and how ADP should sign in to it: an API key, basic authentication, or OAuth client credentials. Select Test webhook, then Save webhook. To skip webhooks, your integration team reads the event queue instead.

Event-driven: connect your integration platform

1. In Flowstate, go to Settings → Users & Access → API Keys and select Create API Key. Name it after the sync, such as "ADP sync", and tick view, create and update for employees, contractors, vacancies and teams. See Create and manage API keys.
2. Copy the key and give it to your integration team, who store it in the platform with the ADP certificate and credentials. Keys last 90 days at most, so put a reminder in to replace it.
3. If people are already in Flowstate, your integration team gives each one their ADP ID first. See Adopt people who are already in Flowstate.
4. Your integration team loads everyone once from ADP, leavers included. The platform creates or updates each person in Flowstate by their ADP ID.
5. They switch on event handling. For each event, the platform reads the worker from ADP, sends the changes to Flowstate, and marks the event done in ADP. How: Sync people from an HR system with the REST API.

Scheduled sync

Not used for ADP Workforce Now, because a Flowstate custom integration can't present ADP's client certificate. If your integration platform reads ADP's event queue on a timer, that's still the event-driven route above.

What syncs

In ADP Workforce Now	In Flowstate	Notes
Associate OID (AOID)	The person's external ID	ADP's own ID for the worker. It's what ADP's events and worker lookups use.
Worker related to you as an employee	Employee
Worker related to you as a contractor	Contractor	ADP relates each worker to your organisation as an employee or a contractor. Check how your organisation records contractors in ADP. If ADP doesn't hold a contractor's rate, add it in Flowstate.
Job requisition	Vacancy	US and Canadian clients only.
Department (home or assigned organisational unit)	Team
Reports-to worker	Line manager
Job title and job code	Job role
Full-time equivalence ratio	FTE on the person's team allocation	Flowstate records FTE, not hours.
Hire date and termination date	Start date and end date
Base remuneration	Pay changes	Each change carries annual base salary, currency and the date it takes effect. Needs access to full worker information.
Name and work email	Name and work email	Work email links the person to their activity in your other tools.

The REST API also sets a person's location, resource type and notice date, when your integration team maps them.

How changes arrive

• Webhooks. ADP sends each event to your platform as it happens, and retries if the platform doesn't confirm it.
• Event queue. Your platform reads events one at a time. ADP advises reading at least hourly, and removes events older than 30 days.
• Effective dates. ADP raises an event when a change is entered, not when it takes effect, and the event carries the effective date. ADP advises reading the worker again rather than holding future-dated events back. Future pay changes show as Scheduled on the person's Compensation tab until their date.
• Leavers. The termination date becomes the person's last day. They stay in Flowstate for past months.
• Rehires. A rehire under the same ADP ID updates the same person, and your platform clears their old end date through the REST API.
• Edits made in Flowstate. Anything your platform sends from ADP is put back the next time that person changes in ADP. Details it doesn't send stay as you set them.

Check it's working

1. Make a test change to a worker in ADP, such as their standard hours.
2. The change shows on the People tab under Resourcing → People and teams.
3. On Settings → Users & Access → API Keys, the key shows recent use.

If something's not right

Every call to ADP fails, even getting a token. The client certificate has expired or been replaced. Renew it in ADP, and your integration team updates it in the platform.

Some workers never arrive. They're outside the connection's People Access in ADP, so their events are refused. Widen People Access, then load those workers again.

Events have stopped coming through. Events that were read but never marked done are blocking the queue. Your integration team clears them. For webhooks, check the receiving address is still public and hosted in the US.

ADP changes stop reaching Flowstate. The Flowstate API key has expired. Create a new one with the same permissions and give it to your integration team.

For your technical team

ADP APIs

• Auth.
  • POST https://accounts.adp.com/auth/oauth/v2/token with grant_type=client_credentials, client ID and secret as HTTP Basic.
  • Every request, including the token request, presents the X.509 client certificate (mutual TLS).
  • The response includes expires_in.
• Scopes. Each API's canonical URI must be in the application's scope, for example /hr/workerInformationManagement/workerManagement/workerProfileManagement/worker.read.
• Workers.
  • GET https://api.adp.com/hr/v2/workers and GET /hr/v2/workers/{aoid}.
  • Page with $top and $skip until the workers array is empty.
  • Filter on hire or termination date, for example $filter=/workers/workAssignments/terminationDate ge '20170101'. ADP's guide warns against filtering on workerStatus.
• Fields.
  • The worker ID is associateOID, with workerID/idValue alongside it.
  • Work assignments carry jobTitle, jobCode, homeOrganizationalUnits, assignedOrganizationalUnits, reportsTo[].workerID.idValue, homeWorkLocation, fullTimeEquivalenceRatio, hireDate, terminationDate and primaryIndicator.
  • Pay is under workAssignments/baseRemuneration. Check the currency field in your payloads.
• Departments. GET /hcm/v1/validation-tables/departments, scope .../departments.items.read.
• Job requisitions. US and Canadian clients only, 20 records per response, paged with $top and $skip, total in meta.totalNumber. Check the path in ADP's guide.
• Coverage. Worker APIs cover Workforce Now and TotalSource, with limited support for Workforce Now Next Gen.

Events

• Queue.
  • GET /core/v1/event-notification-messages returns one message, with its ID in the adp-msg-msgid header.
  • DELETE /core/v1/event-notification-messages/{adp-msg-msgid} removes it. Only then can the next message be read.
  • An empty queue returns 204 in the API Central guide, and 200 with an empty events array in the Marketplace guide. Handle both.
  • ADP returns at most the top 1,000 events, and 1,000 unprocessed events block new ones. Events older than 30 days are purged; individual ADP systems may differ.
• Follow-up. Treat each event as a trigger. Read GET /hr/v2/workers/{aoid} for current data rather than using the event body. A 403 on the event's link means the worker is outside the connection's population; delete the event.
• Event names include worker.hire, worker.business-communication.email.change, base-remuneration.change, standard-hours.change and worker.work-assignment.worker-type.change.
• Webhooks. Added by ADP in October 2025.
  • The receiver must be publicly reachable and hosted in the US. It authenticates ADP with an API key (Bearer), HTTP Basic, or OAuth 2.0 client credentials.
  • Reply 200, 201 or 202 with {"status":"success","timestamp":"<UTC>"}. Anything else is retried.
  • ADP retries 10 times at one-minute intervals, then 10 more times every six hours, and keeps failed events for five days. Failure emails are opt-in.
  • The adpx-messageauthentication header is an HMAC-SHA256 keyed with the client secret and computed over the client ID, not the payload. It doesn't protect the body, so rely on the endpoint's own authentication as well.
  • The payload is the queue event wrapped in meta (messageId, orgID, messageSentTime, attempts, queueName and others).

Flowstate

• REST API. https://{tenant}.flowstate.inc/api/v1/org/{orgId} with Authorization: Bearer <key>.
  • There's no upsert. GET /employees/{aoid}, then POST on 404 or PATCH on 200. Contractors, vacancies and teams work the same way.
  • PATCH /employees/:id sets managerId, geographyId, workTypeId and noticeDate, and { "endDate": null } clears a leaving date.
  • See the recipe and Permissions by endpoint.
• Why not a custom integration. A custom integration can't present a client certificate, so it can't call ADP. See Limits.

ADP documentation

• ADP API Central for ADP Workforce Now
• Event APIs, event notifications and webhooks
• Marketplace event notifications
• Data connector authorisation
• Introduction to credentials
• Worker Management API guide, chapter 1 and chapter 2
• Departments validation table API guide
• Job Requisitions API guide