The Personio integration connects ZEP with the HR system Personio and synchronizes time bookings, absences, and employee master data bidirectionally between both systems.
Data direction: ZEP ↔ Personio
Product line availability
Note: The Personio integration is available in ZEP Clock, ZEP Compact, and ZEP Professional. Importing time bookings from Personio into ZEP is only available in ZEP Clock. Absence synchronization requires the Absences & Overtime module. In ZEP Compact with the Revenues & Costs module and in ZEP Professional, specifying a default price group is mandatory when creating users automatically.
Prerequisites
To set up the integration, you need:
Access to the Interface Marketplace in ZEP to license the module
A Personio account with administrator rights to create API credentials.
Setting up the integration
The Personio integration is configured in ZEP under Administration > Interfaces > Personio.
Create credentials in Personio
For ZEP to access the Personio API, you first need to create API credentials in Personio. Go to Settings > API Credentials – Generate new credential:
Name: "ZEP"
Integration: "ZEP"
Readable employee attributes: select all attributes
Save
Then copy the Client ID and Client Secret from Personio into the corresponding fields in ZEP under Administration > Interfaces > Personio.
Date of introduction
The date of introduction specifies when the module was activated in ZEP. It limits the synchronization period: no time bookings or absences prior to this date are synchronized. This prevents historical data from one system from overwriting or deleting data in the other system.
Note: Synchronization covers a maximum of 3 years into the past, even if the introduction date is set further back.
Assign Personio IDs
In Personio, every employee is identified by a unique Employee ID (also: Personio ID). For time bookings to be correctly assigned during synchronization, every ZEP user whose times should be synchronized must have their Personio ID stored in ZEP. This can be done manually in the employee data under Employees > [Name] > Settings, or automatically via email matching (see next section).
Note: Time bookings in ZEP are only marked for synchronization after the employee's Personio ID has been set. Changes made before the ID was set are not synchronized retroactively.
Synchronizing master data
Personio can be configured as the leading system for HR master data. ZEP will then automatically adopt changes from Personio and optionally create new employees directly in ZEP.
Match Employee IDs using email address
If employees already exist in both ZEP and Personio, the Personio task automatically determines their Employee IDs based on matching email addresses and assigns them to the ZEP users. Activate the option Match Employee IDs using email address in the settings.
Recommendation: Start the task manually once after activating this option. This immediately assigns all existing Personio IDs and starts time booking synchronization.
Note: For email matching to work, the Email field must be included in the list of attributes to be transferred in Personio under Settings > API > Access.
Transfer user data from Personio
If the option Transfer user data from Personio is active, ZEP transfers the attributes enabled in the Personio API definition during every synchronization and updates the corresponding employee data in ZEP. Attributes to be transferred are enabled in Personio under Settings > API > Access.
Warning: If this option is active, the Last Modified field must also be enabled among the transferable attributes in Personio. Without it, Personio delivers no modification date and no transfer occurs. ZEP compares the modification dates of both systems and only transfers changes if the record in Personio is newer than in ZEP.
The following attributes are supported by ZEP:
Personio ID, Email, First Name, Last Name
Gender – transferred to the salutation in ZEP
Date of Birth, Personnel Number
Cost Center – the first assigned cost center is transferred (requires the Export for Accounting module)
Profile Picture – transferred to ZEP if stored in Personio
Mobile Phone Number (business), Extension, Private Landline Number
Street and House Number, Postal Code, City
IBAN, BIC, Name of Bank
Termination Date – end of employment relationship; not the same as contract end date
Employment Type (e.g., permanent, student worker) – a matching employee category is created in ZEP if not present
Work Schedule – transferred as Regular Working Times in ZEP
Employment Type – internal or external (requires the Freelance Employees setting in ZEP)
Price Group – controllable via the custom attribute ZEP Price Group in Personio (ZEP Compact with Revenues & Costs module, ZEP Professional)
Username – controllable via the custom attribute ZEP Username in Personio
The following are additionally transferred when creating new users:
Hire Date – start of employment; if not provided, ZEP defaults to today's date
Team, Department, and Location (Office) – ZEP searches for a department with a matching short designation (order: Team, Department, Location) and assigns it (only with the Locations & Departments module)
Holiday Calendar – assigned if a calendar with an identical name exists in ZEP
Vacation Entitlement per year – transferred to the employment period
Note: Team, Department, and Location are not only transferred when creating new users – if the option Transfer user data from Personio is active, ZEP also updates these fields for existing employees, provided the Locations & Departments module is licensed.
Create new employees in ZEP
If the option Identify new Personio users and create them in ZEP is active, the Personio task checks with every execution whether there are employees in Personio not yet present in ZEP. Newly found employees are automatically created in ZEP with a unique username and all enabled attributes are transferred.
Under Administration > Interfaces > Personio you can specify the username generation scheme. Example: Max Muster (Email: [email protected], Personio ID: 123456):
email_personioid – max.muster_123456 (default)
user_personioid – user_123456
firstname.lastname – max.muster
f lastname – mmuster
Name from email address – max.muster
If the generated username already exists in ZEP, a digit is appended until uniqueness is achieved. Alternatively, the username can be specified individually via the custom Personio attribute ZEP Username: create this attribute in Personio under Settings > Employee Information of type Standard, enable it under Settings > API > Access, and enter the desired username for each employee.
Additionally, ZEP can automatically send a password reset link by email when creating new users – activate via the option Send link to change password via email.
Warning: Email address, first name, and last name are mandatory fields in ZEP. At least these attributes must be enabled in Personio under Settings > API > Access, otherwise user creation will fail. In ZEP Compact with the Revenues & Costs module and in ZEP Professional, specifying a default price group is also mandatory – without this setting, the user transfer will fail with an error message.
Tip: This option is especially useful during initial setup to minimize manual setup effort in ZEP. Since the ZEP subscription fee depends on the number of active employees, check whether this option should remain permanently active.
Exclude employees from transfer
By default, all employees in Personio are transferred to ZEP. To exclude individual employees, create a custom Personio attribute named Transfer to ZEP of type Selection List with options Yes and No (section is freely selectable). Enable it under Settings > API > Access and set it to No for employees to be excluded.
Note: The Transfer to ZEP attribute must be set before the first employee transfer – it only controls the initial creation. Changing it to No retroactively will not delete employees already created in ZEP.
Assign price groups
In ZEP Compact with the Revenues & Costs module and in ZEP Professional, specifying a price group is mandatory when creating users. To manage price groups directly in Personio, create a custom attribute ZEP Price Group of type Selection List:
Under Settings > Employee Information (e.g., in the Public Profile area), create an attribute "ZEP Price Group" of type Selection List.
Enter the short codes of the price groups defined in ZEP under Administration > Prices & Receipts > Price Groups as options.
Add the attribute "ZEP Price Group" to the list of transferable attributes in Personio under Settings > API > Access.
Set the appropriate ZEP price group for all employees.
The price group is transferred during the next synchronization and set accordingly when employees are created. Alternatively, a global default price group for all newly created users can be configured in ZEP under Administration > Interfaces > Personio.
Synchronizing time bookings
Enable the option Synchronize time bookings under Administration > Interfaces > Personio to transfer time bookings recorded in ZEP to Personio as Attendances.
Transfer time bookings aggregated
If this option is active, ZEP summarizes all time bookings of one day per employee and transfers them as a single Attendance – from start to end of work, with summed breaks. If disabled, each individual ZEP time booking is transferred as a separate Attendance to Personio.
Merge time bookings
By default, ZEP recognizes when manually created Attendances already exist in Personio for a given day and skips that day during synchronization. If those Attendances still require approval, ZEP postpones synchronization for up to 7 days.
If the option Merge time bookings is active, ZEP instead attempts to blend the ZEP time bookings into the existing Personio Attendances – as long as no time overlaps occur. Personio Attendances pending approval also receive the "pending approval" identifier.
Import time bookings from Personio
This option is only available in ZEP Clock. If employees record working hours directly in Personio, those Attendances can be imported into ZEP – ensuring both systems show identical totals.
Warning: Import only occurs if the Personio Attendance and an existing ZEP time booking do not overlap. Overlapping entries will fail to import. An active ZEP break regulation considers imported time bookings and may affect the calculated breaks.
Receive times changed in Personio
All time bookings transferred from ZEP to Personio automatically receive a remark beginning with "ZEP". Synchronization only modifies Attendances marked with "ZEP" – manually created Personio Attendances remain untouched.
Tip: If a ZEP-created Attendance was manually changed in Personio and the change should be preserved, remove "ZEP" from its comment. The synchronization will then no longer recognize it as a ZEP booking and will not overwrite it.
Open approvals
In Personio, times can be configured to require approval from a supervisor before being confirmed. The synchronization recognizes days with pending Attendances and suspends synchronization for up to 7 days for those days. If the Attendances have neither been approved nor rejected within this period, normal synchronization resumes on day 8 using the current ZEP time bookings.
The option Follow the Personio approval process additionally controls whether ZEP respects the Personio approval status when writing Attendances by setting the skip_approval parameter accordingly.
0-bookings for days without time bookings
Due to Personio's hour deduction mechanism, on working days with no ZEP bookings and on days of approved absence of type Time Off In Lieu, a 0-booking (0:00 to 0:00, 0 minutes break) must be transmitted to trigger the deduction of deficit hours from the time account in Personio. ZEP creates these 0-bookings automatically for all affected days up to and including yesterday. If ZEP detects subsequently recorded working hours directly in Personio, it removes the previously sent 0-booking.
Creating 0-bookings can be disabled via the option Create "0-bookings" on working days without time booking in the settings.
Automatic break deduction
ZEP supports freely definable break regulations for specifying minimum breaks, fixed breaks, and maximum working times (Administration > Working Hours > Break Regulation). A break regulation is assigned to an employee in their Regular Working Time definition (Employees > [Name] > General > Regular Working Time).
The break regulation does not directly trim booked times. It shows the employee a warning for violations. If an automatic deduction of non-complied break times is configured, the Break Overview and Month-end Report (Absences & Overtime module) reflect the corresponding deductions – which are then also transmitted to Personio.
Shift and night work
Time bookings in ZEP and Personio are recorded with start and end times in the 0:00–24:00 range. For work crossing midnight, two separate time bookings must be recorded – one before and one after midnight.
When transmitting, ZEP normally aggregates a day's bookings into one Attendance. For night/shift work across midnight, this would produce confusing Attendances (0:00–24:00 with hours of break) in Personio. ZEP therefore identifies gaps of more than 2 hours between time bookings and transmits the time blocks before and after such gaps as separate Attendances.
Re-transfer a month's time bookings
Using the Synchronize now button under Administration > Interfaces > Personio, you can select a specific month and re-transfer all employees' time bookings for that month to Personio. This requires that the ZEP users have their Personio IDs assigned.
Before the re-synchronization, you can optionally enable deletion of all existing ZEP bookings for that period in Personio (Delete Personio bookings). This ensures no outdated entries remain in Personio.
Synchronizing absences
Both ZEP and Personio support the management of absences and leave with an approval process. Absence reasons/types in ZEP correspond to leave types/absence types in Personio.
The Absences & Overtime module must be active in ZEP to use absence synchronization. Configure the leading system under Administration > Interfaces > Personio:
Do not synchronize absences: No exchange of absences occurs.
Transfer Personio absences to ZEP: Personio is the leading system. Absences approved in Personio are transferred to ZEP, displayed in the ZEP calendar, and overwrite manually recorded absences in ZEP.
Transfer ZEP absences to Personio: ZEP is the leading system. Absences approved in ZEP are transferred to Personio and mapped as leave entries.
Warning: In the mode Transfer Personio absences to ZEP, absences imported from Personio should not be edited manually in ZEP – they will be automatically overwritten during the next synchronization.
Note: After activating an absence sync mode, start the Personio task manually once and check the task logs to identify which ZEP absence reasons have not yet been mapped to Personio absence types, then complete the mapping.
Map absence reasons
To synchronize absences, ZEP absence reasons and Personio leave types must be mapped to one another. In ZEP, an absence reason is defined by a short designation and a designation (e.g., UB for "Paid Leave"). Personio leave types have a name and an internal ID (Personio: Settings > Absences).
Warning: Only absences for which the ZEP absence reason designation exactly matches the Personio leave type name are synchronized. Case sensitivity and special characters are taken into account. Entries without an exact match are ignored during synchronization.
Example: If the absence reason in ZEP is "Urlaub bezahlt" and the leave type in Personio is "Bezahlter Urlaub", no synchronization will occur – the designations must be identical.
Setting up synchronization
Personio synchronization runs via a scheduler task in ZEP. Set up the task under Administration > System > Tasks:
Click + Create new task.
Select the task Personio Synchronization.
Specify the time intervals at which the task should run (hourly recommended).
Click on the task name under Administration > System > Tasks to view the logs of all past executions. These contain information about the task's progress and notes on any errors during synchronization.
Tip: If you activated the option Match Employee IDs using email address, start the task manually once after configuration. This immediately determines and assigns all Personio IDs – from that point on, time bookings are marked for synchronization.