Payroll integration
HiBob to Paychex Flex integration: new US employees from Bob prepared in Paychex Flex
An integration between HiBob and Paychex Flex creates a new employee of the US entity in Bob as a worker in Paychex Flex, with name, worker type, employee ID and start date. Paychex puts such a worker on IN_PROGRESS, after which the employee or the Flex administrator fills in tax forms and bank details in Flex.
What the integration does
Organisations that run HR in HiBob and US payroll in Paychex Flex record new US colleagues in Bob first. Someone then creates them again in Flex with the same name and start date, often only when the first payroll run is coming up.
- The Flex administrator approves the partner app under Company Settings, Integrated Applications.
- Bob reports a new employee; KoppelHet checks that they belong to the US entity and are an employee.
- KoppelHet creates the worker in the right Paychex company and only stores a workerId from a successful response.
- In Flex the employee and administrator complete the remaining payroll data.
- Every day KoppelHet compares the new US employees in Bob with the workers in Flex and reports differences.
What to watch for with HiBob and Paychex Flex
- KoppelHet builds this integration on the Paychex API. The Payroll Hub API HiBob offers payroll providers is still in early access.
- For a new worker Paychex only asks for first name, last name and worker type. Everything else Paychex Flex requires depends on the customer's setup, and as long as it is missing the worker stays IN_PROGRESS. KoppelHet therefore sends the minimum from Bob and leaves the rest to be finished in Flex.
- Through the API Paychex only knows EMPLOYEE, a W-2 employee, and INDEPENDENT_CONTRACTOR, a 1099 worker; the type CONTRACTOR is not possible. Anyone listed in Bob as a contractor at the US entity therefore does not go across automatically; KoppelHet reports them to payroll.
- In Paychex's example a different workerCorrelationId comes back than was sent when several workers go in one request. KoppelHet does not rely on that alone, but also links each workerId back to the right employee using the employee ID from Bob.
- With a locked Paychex account the API returns a 423, while a workerId has sometimes been created anyway. Paychex says not to use that ID. KoppelHet only stores IDs from a response with status 200 and retries the employee from Bob once the account is open again.
- HiBob silently leaves out fields the service user has no read rights on. Without rights on the US entity KoppelHet therefore sees no new employees; the service user gets rights on only that population, so salaries from other countries stay outside the integration.
- Paychex grants access per client company through a partner app. KoppelHet requests access with the eight-digit displayId of the Paychex company, and only after approval by the Flex administrator can the first employee from Bob go in.
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 go across as well?
Not in the first version. The integration starts with new hires; pay changes can follow later as an extension.
Who fills in the W-4 and the bank account?
The employee or the Flex administrator, in Paychex Flex. That data is usually not in Bob.
Technical details for IT
For those who want to know how it works under the hood: APIs, fields and sources used.
- HiBob through signed webhooks for employee events and the People API (POST /v1/people/search with selected fields), with a service user that only sees the US entity.
- Paychex through https://api.paychex.com with a partner app (one key and secret); access per client through /management/requestclientaccess with the displayId. Create with POST /companies/{companyId}/workers, later changes with PATCH /workers/{workerId}.
Which fields are transferred
The key fields. The full mapping is agreed per customer.
| Field in HiBob | Field in Paychex Flex | Notes |
|---|---|---|
root.firstName | name.givenName | |
root.surname | name.familyName | |
Werknemer van de Amerikaanse entiteit | workerType EMPLOYEE | Only EMPLOYEE or INDEPENDENT_CONTRACTOR is possible through the API |
Personeelsnummer in Bob | employeeId | |
work.startDate | currentStatus (IN_PROGRESS, PENDING_HIRE) met ingangsdatum | |
HiBob employee id | workerCorrelationId bij meerdere workers per verzoek |
Related
Ashby → HiBob
Ashby to HiBob integration: a hire from Ashby straight in as an employee in Bob
Bullhorn → HiBob
Bullhorn to HiBob integration: an approved placement as a new employee in Bob
Carerix → HiBob
Carerix to HiBob integration: successful match becomes a new employee in Bob
Greenhouse → HiBob
Greenhouse to HiBob integration: from a hire in Greenhouse to a new employee in Bob