Payroll integration
UKG Pro to Loket integration: Dutch employees, pay and hours from UKG Pro ready for the payroll run
With an integration between UKG Pro and Loket, a new Dutch employee from UKG Pro arrives in Loket as a concept employee, and pay, working hours and termination go to the employment in Loket. KoppelHet only reads the pay group of the Dutch entity, so payroll no longer retypes anything from the American HR system.
What the integration does
Organisations with an American head office on UKG Pro and a Dutch entity paid by a payroll bureau in Loket usually send changes by email or spreadsheet. The bureau converts annual salaries itself, and an hours change entered in UKG Pro only reaches the payslip a month later.
- HR hires an employee in UKG Pro, in the pay group of the Dutch entity.
- In the next run KoppelHet creates a concept employee in Loket at the right employer, with BSN, address and IBAN.
- Payroll completes collective agreement, payroll tax credit and pension and converts the concept into an employee.
- A pay or hours change in UKG Pro goes to the pay or working hours of the employment, with the effective date.
- A termination ends the employment in Loket per the date from UKG Pro.
What to watch for with UKG Pro and Loket
- UKG Pro records a pay group per employee, with its own period. KoppelHet uses the pay group of the Dutch entity to select which employees go to Loket and which employer in Loket they belong to.
- UKG Pro indicates per employee whether they have a fixed salary or an hourly wage. An hourly worker gets an hourly wage in Loket, and a salary is converted from an annual amount to the payroll period of the employer in Loket.
- Every amount in UKG Pro has a currency code. If a Dutch employee's salary is not in euros, KoppelHet does not put it in Loket but reports it to payroll, so no dollar amount is paid out as euros.
- UKG Pro wants changes requested at most every three hours, and does not say which field changed. KoppelHet keeps the previous state and only sends Loket pay, hours or dates that are actually different, so no pay line is closed unnecessarily.
- The IBAN of an employee outside the United States is stored in UKG Pro's global bank details, separate from the American accounts. KoppelHet fetches it there and sets it as SEPA payment details in the concept in Loket.
- The BSN is stored in UKG Pro among the national documents, with the issuing country. Only a Dutch number goes to Loket. If it is missing, KoppelHet creates no concept and HR gets a notification.
- Loket settles a retroactive pay change itself, as long as it falls in the same calendar year. If HR records a raise in UKG Pro with an effective date in a previous year, the payroll bureau gets a notification to correct it separately.
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 collective agreement and payroll tax credit also come from UKG Pro?
No. UKG Pro does not know these Dutch concepts. Payroll records them in Loket, and the integration does not overwrite them.
Does this work if a payroll bureau manages Loket for us?
Yes. The bureau gives the integration access to your employer in Loket only.
Technical details for IT
For those who want to know how it works under the hood: APIs, fields and sources used.
- UKG Pro through the Personnel API with a service account, the US-CUSTOMER-API-KEY header and basic authentication. employee-changes (changes since the previous call, at least three hours apart, eight times a day, per_page up to 200, View role on EmployeeExport), employment-details, compensation-details (salaryOrHourlyCode, annualSalary, hourlyPayRate, payPeriodPayRate, payGroupCode, payPeriod, scheduledPeriodWorkHours, currencyCode), national-documents and employee-global-banks. 429 on too many calls.
- Loket is written through the Loket REST API (api.loket.nl/v2) with OAuth 2.0: concept-employee, convert to employee, wage, deviating-hourly-wage, working-hours, payment-information and ending the employment. Testing in the acceptance environment (api.loket-acc.nl/v2) with test data.
Which fields are transferred
The key fields. The full mapping is agreed per customer.
| Field in UKG Pro | Field in Loket | Notes |
|---|---|---|
employeeNumber | Personeelsnummer | Fixed key |
firstName en lastName | Voornaam, voorvoegsel en achternaam | |
nationalId met land NLD (national-documents) | Burgerservicenummer | |
payGroupCode | Werkgever in Loket | |
lastHireDate | Begindatum dienstverband | |
salaryOrHourlyCode | Maandloon of uurloon | |
annualSalary of hourlyPayRate | Loon per verloningsperiode | |
scheduledPeriodWorkHours | Arbeidstijd (uren per week) | |
iban (employee-global-banks) | Betaalgegevens (SEPA) | |
terminationDate | Einde dienstverband |
Related
Recruitee → UKG Pro
Recruitee to UKG Pro integration: European hires through the Global New Hire service in UKG Pro
Teamtailor → UKG Pro
Teamtailor to UKG Pro integration: European hires as global new hires
UKG Pro → Active Directory
UKG Pro to Active Directory integration: domain accounts for the Dutch branch
UKG Pro → ADP iHCM
UKG Pro to ADP iHCM integration: salary and terminations of the Dutch pay group to ADP