Payroll integration
UKG Pro to PayFit integration: French new hires from UKG Pro as a collaborator with contract in PayFit
An integration between UKG Pro and PayFit turns a new employee at the French company in UKG Pro into a collaborator with a basic contract in PayFit, with personal email, address and social security number. The PayFit API cannot change a running contract, so later changes and leavers from UKG Pro go to the French payroll administrator as a task.
What the integration does
Organisations that use UKG Pro as their HR system and pay their French subsidiary in PayFit enter French starters in PayFit by hand. The work email from UKG Pro does not work yet at that point, so the PayFit invitation does not reach the new colleague.
- Every three hours KoppelHet requests the changed employees in UKG Pro.
- KoppelHet keeps the new employees of the French company and fetches their French national documents.
- KoppelHet creates the collaborator and then the basic contract.
- The payroll administrator completes working time, health insurance and other contract details in PayFit.
- Changes and leavers from UKG Pro go to the payroll administrator as a task with a date.
What to watch for with UKG Pro and PayFit
- The changes-by-date query in UKG Pro returns the current state of an employee, not what changed. Because PayFit only supports creating through the API, KoppelHet remembers which French employees already have a collaborator and compares the rest with the previous round to report changes as a task.
- UKG advises running the changes query at most every three hours, about eight times a day. A PayFit contract only becomes visible two to five minutes after the 201 response. KoppelHet therefore checks the contract in the next round, not right after creating it.
- PayFit only creates contracts for French companies through the API. UKG Pro returns a companyId and a country code per employee; KoppelHet only sends employees of the French company with country code FR, and reports an employee of another company who lives in France to payroll.
- PayFit requires a personal email address. Besides emailAddress, usually the work email, UKG Pro has an alternateEmailAddress. KoppelHet only uses that second address and holds back a starter without one with a message to HR.
- The French social security number is held in UKG Pro under national documents, which can be requested per issuing country; the service account needs the View role on Personnel Integration for that. KoppelHet only requests documents with country FR and checks the fifteen characters PayFit expects for France.
- Besides hireDate, UKG Pro also returns dateOfLastHire. If they differ, it is a rehire. PayFit advises against creating several contracts for one collaborator; KoppelHet finds the existing collaborator and tells payroll a new contract is needed.
- UKG Pro supplies the address as employeeAddress1 and employeeAddress2, while PayFit requires street number and street separately. KoppelHet splits the French address on the leading house number and holds back an address that cannot be split for HR to check.
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 leave from UKG Pro also go to PayFit?
Not in the first version. PayFit accepts absences through the API as approved and rejects overlaps; a leave flow can be added later as an extension.
Can the integration put a pay rise into PayFit?
No, the public API has no endpoint to change a running contract. KoppelHet reports the rise with its effective date to payroll.
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; View role on EmployeeExport) and GET /personnel/v1/national-documents with nationalDocumentIssuingCountryCode (View role on Personnel Integration). Basic authentication with a service account plus the US-Customer-Api-Key header.
- PayFit through partner-api.payfit.com with the customer's API key: POST collaborators (firstName, lastName, personalEmail, personalAddress) and POST contracts (France only, 201 without data, available after two to five minutes).
Which fields are transferred
The key fields. The full mapping is agreed per customer.
| Field in UKG Pro | Field in PayFit | Notes |
|---|---|---|
employeeNumber | Bewaard naast het PayFit collaborator-ID | Key for tasks |
firstName, lastName | firstName, lastName | Required |
alternateEmailAddress | personalEmail | Required; not the work email |
employeeAddress1, city, zipCode, countryCode | personalAddress (streetNumber, addressFirstLine, city, postCode, country) | |
nationalDocumentNumber (FR) | socialSecurityNumber | Fifteen characters |
jobCode of alternateJobTitle | jobTitle (contract) | |
hireDate | startDate (contract) |
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