Payroll integration
UKG Pro to DATEV integration: German employees from UKG Pro as master and movement data for the tax adviser
An integration between UKG Pro and DATEV prepares new German employees, pay, hours, bank details and leavers from the German pay group in UKG Pro for the tax adviser's DATEV payroll program, where the adviser takes them over. KoppelHet builds the delivery on the UKG Pro personnel APIs.
What the integration does
Organisations that record HR in UKG Pro and have German payroll processed by a tax adviser in DATEV send the office an export from UKG Pro every month. It is retyped there, and an hours change in UKG Pro that falls between two exports reaches DATEV a month late.
- KoppelHet gets a service account in UKG Pro with read rights on the required web services.
- Every three hours KoppelHet requests the changed employees and compares the response with the previous state.
- KoppelHet converts employees in the German pay group into master and movement data with the tax adviser's wage types.
- The delivery goes through the Lohnimportdatenservice to the DATEV data centre, or as an ASCII file to the office.
- The tax adviser takes over the data; KoppelHet reports what is still open before the cut-off.
What to watch for with UKG Pro and DATEV
- The UKG Pro employee-changes API may not be called more often than every three hours; UKG recommends eight times a day. That is plenty for the German monthly close. KoppelHet schedules the last request of the month so no change falls between it and the cut-off date.
- The employee-changes response does not say which fields changed; UKG advises comparing with the previous call. KoppelHet keeps the last delivered state per German employee, so only real changes go to DATEV as movement data and not the whole employee again.
- UKG Pro stores national documents with a type and a country of issue. KoppelHet filters on country DEU and records per document type whether it is the tax ID or the social insurance number, so an American SSN never ends up in DATEV.
- In UKG Pro pay is an annual salary or an hourly rate, marked with salaryOrHourlyCode. DATEV works with a fixed monthly amount or an hourly rate per wage type. KoppelHet converts an annual salary into the monthly amount and records per pay group which of the office's wage types it lands on.
- Bank details of non-US employees are in the global banks in UKG Pro, with IBAN. KoppelHet reads the IBAN there, because the US direct deposit fields stay empty for a German employee.
- DATEV only opens the Lohnimportdatenservice to selected third-party systems, and the tax adviser activates it in DATEV Arbeitsplatz. According to DATEV the service costs five cents per paid employee per month. If KoppelHet is not yet admitted for this route, KoppelHet delivers an ASCII file that the office imports into LODAS.
- German tax and social insurance data, such as tax class and health insurer, do not belong in an American HR system. The tax adviser records them in DATEV, and the integration does not overwrite them.
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 this work with LODAS and with Lohn und Gehalt?
The Lohnimportdatenservice is meant for DATEV's payroll programs. At the start we ask the office which program it uses, because the ASCII route only applies to LODAS.
Do one-off payments also go across?
Not in the first version. Bonuses as movement data on a wage type can be added later as an extension.
Technical details for IT
For those who want to know how it works under the hood: APIs, fields and sources used.
- UKG Pro through GET /personnel/v1/employee-changes (startDate, endDate, per_page up to 200, at least three hours between calls), compensation-details (salaryOrHourlyCode, payGroupCode, scheduledPeriodWorkHours), /personnel/v1/national-documents (filter nationalDocumentIssuingCountryCode) and employee-global-banks. Basic authentication with a service account plus the US-CUSTOMER-API-KEY header; View role on the relevant web services.
- To DATEV through the Lohnimportdatenservice (master and movement data via the DATEV data centre, takeover with one click in the payroll program, status for source and user, activation in DATEV Arbeitsplatz) or an ASCII file for LODAS. Access for partner software after onboarding on the DATEV Developer Portal.
Which fields are transferred
The key fields. The full mapping is agreed per customer.
| Field in UKG Pro | Field in DATEV | Notes |
|---|---|---|
employeeNumber | Personalnummer | Or a lookup to the office's numbers |
firstName, lastName | Vorname, Name | |
nationalDocumentNumber (issuing country DEU) | Steuer-ID of Sozialversicherungsnummer | Per document type |
lastHireDate | Eintrittsdatum | |
salaryOrHourlyCode en annualSalary of hourlyPayRate | Festbezug of Stundenlohn | Converted to the monthly amount |
scheduledPeriodWorkHours | Wöchentliche Arbeitszeit | |
iban (employee-global-banks) | Bankverbindung (IBAN) | |
terminationDate | Austrittsdatum |
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