Payroll integration
Darwinbox to ADP iHCM integration: CTC changes, extra payments and approved separations to Dutch ADP payroll
An integration between Darwinbox and ADP iHCM passes salary changes from the Darwinbox Global Compensation module, one-off and recurring extra payments and approved separations to Dutch payroll in ADP iHCM. Employees of the Dutch group company who already exist in ADP get their new salary, bonus and end date without payroll retyping anything; creating a new employee in ADP remains work for payroll.
What the integration does
Organisations that use Darwinbox as their HR system and process Dutch payroll in ADP iHCM export a CTC report from Darwinbox every month and enter the differences in ADP by hand. An extra payment that recurs monthly in Darwinbox then has to be re-entered by payroll every period, and a withdrawn resignation is often reversed too late in ADP.
- HR records a new CTC, an extra payment or a separation in Darwinbox for an employee of the Dutch group company.
- KoppelHet fetches the changed CTC rows and extra payments over the window since the previous run, filtered on the Dutch group company.
- The basic component goes to ADP as a salary change; extra payments go in as variable lines in the right pay period.
- An approved separation starts the termination in ADP; a revoked separation cancels it again.
- Anything ADP rejects is listed for payroll and HR with the error message.
What to watch for with Darwinbox and ADP iHCM
- Darwinbox's Global Compensation API returns both the annual amount and the amount per pay frequency for each CTC component, with the previous values alongside. KoppelHet only sends the basic component to ADP, and only when the amount really differs from the previous value; a recalculation without a new amount therefore produces no salary change.
- Darwinbox has extra payments with frequency One-Time, Weekly or Monthly and a status In Progress or Completed. KoppelHet puts a one-off payment in the ADP period of the payment_date, and repeats a monthly payment every period until the stopped_date HR fills in in Darwinbox.
- A separation in Darwinbox is Pending, Approved or Revoked. KoppelHet only starts the termination in ADP at Approved. If an approved departure is later revoked, KoppelHet cancels the termination in ADP, because iHCM cannot amend a termination.
- The Darwinbox separation API requires a list of employee IDs and gives no overview of all leavers. KoppelHet therefore uses the employees of the Dutch group company from the master data as input, so no departure outside the Netherlands goes to ADP.
- Darwinbox records the currency per CTC component and per extra payment, because the module works globally. ADP iHCM NL calculates in euros. KoppelHet holds back an amount in another currency and reports it to payroll, instead of converting it.
- Extra payments can be requested in Darwinbox by payment date or by modification date. KoppelHet requests by modification date, so a bonus HR enters afterwards with an old payment date is still found; ADP then marks such a line as retroactive itself.
- ADP iHCM accepts one salary change per call. If HR changes the CTC of a whole department at once in Darwinbox, KoppelHet sends them one after another, per employee, and keeps track of what ADP reports back for each call.
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
Does the integration create new employees in ADP iHCM?
No. We found no API in ADP's public iHCM guides to create an employee. KoppelHet reports a new Dutch employee from Darwinbox to payroll and links them as soon as they exist in ADP.
What happens to CTC components other than base salary?
In the first version only base salary and extra payments are included. Fixed allowances fall under a separate API in ADP and can be added later as an extension.
Do Indian or other foreign salaries go along?
No. KoppelHet filters on the Dutch group company and holds back amounts in a currency other than euro.
Technical details for IT
For those who want to know how it works under the hood: APIs, fields and sources used.
- Darwinbox through the Basic Auth APIs with api_key: payrollapi/componentctcbreakup (from_date, to_date, group_company; ctc_break_up with component, frequency, effective_date, currency, annual_value, value and previous_*), payrollapi/componentextrapayments (modified_from, modified_to; payment_frequency, payment_date, status, stopped_date), UpdateEmployeeDetails/separationDetails (separation_status Approved/Pending/Revoked, employee_ids required) and masterapi/employee with last_modified.
- ADP iHCM through GET /hr/v2/workers (payrollfilenumber, paygroupcode), the Base Remuneration Change API (/events/hr/v1/worker.work-assignment.base-remuneration.change, fields 2416 and 2417, one event per call), the Pay Data Input API for iHCM NL (.add with batch ID, .replace as long as the run has not been processed) and the Worker Terminate API (worker.terminate, worker-termination.cancel). Every canonical URI in the Consumer Application Registry (CAR).
Which fields are transferred
The key fields. The full mapping is agreed per customer.
| Field in Darwinbox | Field in ADP iHCM | Notes |
|---|---|---|
employee_no | payrollfilenumber | Linked once and stored by KoppelHet |
group_company_name | payrollGroupCode | Lookup per group company |
ctc_break_up: component Basic, value en frequency | Salariscode 2416 en salarisbedrag 2417 | |
ctc_break_up: effective_date | effectiveDateTime van de salariswijziging | |
payment_name, payment_amount, payment_date | Variabel veld (Vxxx) met payPeriodStartDate en payPeriodEndDate | Lookup per payment type |
Separation Details (Approved of Revoked) | worker.terminate of worker-termination.cancel |
Related
Darwinbox → Active Directory
Darwinbox to Active Directory integration: domain accounts that follow Darwinbox, per office location
Darwinbox → AFAS Profit
Darwinbox to AFAS integration: Dutch employees from Darwinbox in AFAS payroll
ASDarwinbox → Arbodienst (SIVI)
Darwinbox to the occupational health service via SIVI: approved sick leaves as absence reports
Darwinbox → DATEV
Darwinbox to DATEV integration: German employees, pay and leavers from Darwinbox to the DATEV payroll program