Payroll integration
Workday to Paychex Flex integration: US new hires from Workday as a worker in Paychex Flex
An integration between Workday and Paychex Flex prepares a US new hire from Workday as an in-progress worker in Paychex Flex, with name, employee ID, date of birth, SSN and start date. The employee or the Flex administrator then completes the required payroll fields in Flex, such as tax forms and bank account, after which the worker becomes ACTIVE.
What the integration does
Organisations that manage HR worldwide in Workday and run US payroll through Paychex Flex enter US new hires twice. HR completes the Hire in Workday, and then someone at the US entity types the same name, SSN and start date into Flex again.
- HR completes a Hire in the US pay group in Workday.
- KoppelHet creates a worker in the right Paychex company with status IN_PROGRESS and reason PENDING_HIRE, with the Workday employee ID as employeeId.
- With the email address passed along, Paychex sends the new hire an invitation to complete their own details in Flex.
- KoppelHet stores Paychex's workerId on the Workday worker and follows whether the worker becomes ACTIVE.
- If a worker is still IN_PROGRESS shortly before the first working day, the payroll administrator gets a notification.
What to watch for with Workday and Paychex Flex
- A worker that arrives through the API stays IN_PROGRESS in Paychex Flex until all required fields are filled. Which fields are required depends on the customer's Flex configuration. KoppelHet supplies what Workday holds and leaves the rest to be completed in Flex.
- Paychex itself sends an in-progress worker an invitation if an email address or mobile number is included. Business email first, then personal email, then business mobile. A US starter often has no work email before day one, so KoppelHet passes the personal address from Workday.
- Through the API you can only create workers of type EMPLOYEE (W-2) or INDEPENDENT_CONTRACTOR (1099), not company contractors. Contingent workers from Workday therefore do not go along automatically; KoppelHet only sends US employees.
- If the customer's Paychex account is locked, the API returns a 423 and a workerId may still have been created. Paychex says that ID is invalid. KoppelHet discards it and retries the Hire later, instead of storing the ID on the Workday worker.
- Access runs through a Paychex partner app. The customer receives a request with the eight-digit displayId and approves the app as Flex Admin under Company Settings, Integrated Applications. Only then can Workday data go to that Paychex company.
- Federal and state taxes have their own endpoints with different required fields per state, such as a county in Maryland. Workday usually does not supply those W-4 choices with an external payroll. KoppelHet therefore leaves them to be filled in during Flex onboarding.
- With several workers in one request each worker needs a workerCorrelationId. KoppelHet fills in the Workday employee ID there, so each workerId from the response lands on the right Workday worker.
How we build and run it
- The integration runs on the KoppelHet platform, hosted in a data centre in the EU.
- Every sync and every error is visible in the functional log; on an error your administrator is notified.
- A change that cannot go through is not half-applied but queued for another attempt.
- KoppelHet is ISO 27001 certified. Data travels encrypted and stays on the platform no longer than needed.
- After go-live we manage the integration and adjust it when your process changes.
- The integration fits next to your existing integration layer. Only the fields in the design are transferred; the platform keeps no register of its own.
Implementation and price
This is not an app you switch on. We build the integration for your organisation on our platform, with building blocks we reuse on every project. So it is custom work that does not start from scratch.
A consultant prepares the intake and analyses both systems. We then record the mapping and exceptions field by field, test in the test or acceptance environment and go live at a moment you choose. Costs are a one-off amount for the setup and a monthly amount for platform, monitoring and support.
Frequently asked questions
Do pay changes from Workday also go to Paychex?
Not in the first version. The Paychex API has compensation and pay components with an effective date, so it can be added later as an extension, after a test in the customer's environment.
Can the integration also fill in bank details and the W-4?
Technically Paychex has endpoints for this. Because that data is usually not in Workday, KoppelHet lets the employee fill it in themselves in Flex through the invitation.
What if someone is rescinded in Workday before the start?
Then KoppelHet reports the in-progress worker to the Flex administrator, who handles it in Flex. The integration does not delete workers itself.
Technical details for IT
For those who want to know how it works under the hood: APIs, fields and sources used.
- Workday is read through a RaaS report on the US pay group with completed Hires (Employee_ID, Legal_Name, Date_of_Birth, National_ID USA-SSN, Time_Type, Hire_Date, Personal Email).
- Paychex through https://api.paychex.com with OAuth 2.0 client credentials (token from /auth/oauth/v2/token, valid for about an hour). Create with POST /companies/{companyId}/workers (Accept application/vnd.paychex.workers.v1+json), check with GET /companies/{companyId}/workers; companyId through the Companies API. Customer access through POST /management/requestclientaccess with the displayId. Limit of 10,000 requests per minute per partner key, shared across all integrations using that key.
Which fields are transferred
The key fields. The full mapping is agreed per customer.
| Field in Workday | Field in Paychex Flex | Notes |
|---|---|---|
Employee_ID | employeeId | Fixed key next to Paychex's workerId |
Legal_Name | name.givenName, middleName, familyName | |
Worker type (Employee) | workerType EMPLOYEE | |
Time_Type | employmentType (bijvoorbeeld FULL_TIME) | |
Date_of_Birth | birthDate | |
National_ID (USA-SSN) | legalId (legalIdType SSN) | |
Hire_Date | currentStatus.effectiveDate | With statusType IN_PROGRESS and statusReason PENDING_HIRE |
Personal email | communications (EMAIL, PERSONAL) | Determines where the invitation goes |
Related
Ashby → Workday
Ashby to Workday integration: hires to Workday, with a check on outcome and phone number
Bullhorn → Workday
Bullhorn to Workday integration: a consultant's first placement as a hire in Workday
Carerix → Workday
Carerix to Workday integration: a placed candidate becomes a pre-hire and starts the hire
Greenhouse → Workday
Greenhouse to Workday integration: hires as pre-hires, interim staff and contractors included