The Personio integration connects ZEP with the HR system Personio and synchronizes time bookings and absences between both systems and adopts employee master data from Personio.
Data direction: ZEP ↔ Personio
Product line availability
Note: The Personio integration is included in all product lines.
Importing time bookings from Personio into ZEP is only available in ZEP Clock.
Synchronizing absences requires the Absences & Overtime area.
From ZEP Control onwards, specifying a default price group is mandatory when users are created automatically.
Setup and configuration are reserved for administrators.
Prerequisites
To set up the integration, you need:
Access to the Interface Marketplace in ZEP to set up and activate the integration
A Personio account with administrator rights to create API credentials.
Setting up the integration
The Personio integration is configured in ZEP under Administration > Interfaces > Interface Marketplace > 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 > Interface Marketplace > Personio. In the field Company (subcompany) – synchronize only these employees (empty = all), you can limit the synchronization to the employees of one Personio company. If the field stays empty, ZEP synchronizes all employees.
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 under Employees > [Name] > Employee File (pencil icon in the master data, Interfaces section, Personio ID field), or automatically via email matching (see next section).
Note: ZEP only transfers time bookings after the employee's Personio ID has been set. Whatever was recorded or changed before that is not made up for automatically.
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 area)
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 category (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 (from ZEP Control onwards)
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 area)
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 area 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 > Interface Marketplace > Personio you can specify the username generation scheme. Example: Max Muster (Email: [email protected], Personio ID: 123456):
email_personioid – max.muster_123456 (default). If no email address is stored in Personio, the user_personioid scheme is used instead.
user_personioid – user_123456
firstname.lastname – max.muster
flastname – 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. From ZEP Control onwards, 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. After the initial import, check whether this option should remain permanently active, so that only the employees you want are created in ZEP.
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
From ZEP Control onwards, 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 > Interface Marketplace > Personio. The field appears once the option Identify new Personio users and create them in ZEP is active.
Synchronizing time bookings
Enable the option Synchronize time bookings under Administration > Interfaces > Interface Marketplace > Personio to transfer time bookings recorded in ZEP to Personio as Attendances.
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 14 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. To do so, activate the option Import attendances registered in Personio. The transfer in the other direction is not affected: times recorded in ZEP still go to Personio.
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 14 days for those days. If the Attendances have neither been approved nor rejected within this period, normal synchronization resumes on day 15 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.
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. A working day here is any day that the employee’s regular working hours define as a working day. Public holidays and days with an absence therefore count as well: if nothing is booked in ZEP on such a day, a 0-booking goes to Personio. 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-minutes" 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 > Project Times > Work break regulation, in ZEP Clock Administration > Working hours > Work break regulation). A break regulation is assigned to an employee in their working time model (Employees > [Name] > Employee File > Working time model).
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 area) 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 > Interface Marketplace > Personio, you open the window Month to be synchronized. There you choose a period with a from and a to date, and quick links set whole months. The to date reaches no further than today. Execute re-transfers all employees' time bookings for that period 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 area must be active in ZEP to use absence synchronization. Configure the leading system under Administration > Interfaces > Interface Marketplace > 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, ZEP transfers the time bookings of those employees.
When times do not arrive in Personio
If a single time is missing in Personio, running the synchronization again does not help. Look for the cause instead. The log shows first whether ZEP left the day out on purpose. If there is nothing about the day there, the four cases from the section after next apply.
Look at the log first
Open Administration > System > Tasks and click the name Personio synchronization. The Executions area lists the previous runs with status, result and log. Every log line starts with the user name and the date, for example mustermann@2026-09-29. Look for the day in question there.
The log says | Meaning and remedy |
Personio hat "Offene Genehmigungen" ... Synchronisation verschoben | In Personio, a requested time booking is waiting for approval on that day. ZEP waits so that the request is not confirmed unintentionally. Approve the booking in Personio. If it stays open, ZEP transfers the day after 14 days at the latest. |
Attendance ... was modified in Personio. Skipped | There is a booking in Personio for that day that does not come from ZEP. ZEP does not overwrite it. Delete the booking in Personio or set the option Merge ZEP and Personio time bookings. |
No mapping for ... found. Fehlzeit/Absence skipped | The ZEP absence reason has no absence type of the same name in Personio. The assignment works by name, not by a key. Align the names. |
Planned Fehlzeit/Absence ignored | The absence is only planned in ZEP. Only approved absences are transferred. |
an error message from Personio | Personio rejected the write access, for example because of an overlap with an existing booking. ZEP tries the day again on the next run. |
Causes that no log reports
If there is nothing at all about the day in the log, ZEP did not consider it for transfer in the first place. There are four reasons for that:
The Personio ID came later. Times recorded before the employee had a Personio ID assigned are not transferred by ZEP on its own. Adding the ID afterwards does not make up for them.
The booking was moved to another day. ZEP then transfers the new day. In Personio, the old time remains on the old day.
Only the invoicing of the booking was changed. Assigning a time to an invoice or releasing it from one does not trigger a transfer.
The employee was not employed on that day. If the day lies outside the employment period, ZEP skips it without a message. This also affects days before a start date that was changed afterwards.
Two further cases look like missing times but are intended: times on activities flagged as on-call duty are not transferred, and if a subcompany is stored in the settings, employees of other subcompanies receive no Personio ID at all.
Closing gaps
For all cases in the previous section there is exactly one remedy: Synchronize now in the Personio settings, described in the section Re-transfer a month’s time bookings. It transfers every day of the chosen period again, for every employee with a Personio ID assigned, and starts the synchronization right away.
Tip: Check beforehand whether the employee’s Personio ID is set. Without it, the re-synchronization stays ineffective as well. You find the ID in the employee file in the master data, Interfaces section, Personio ID field.
Note: Deleting the task under System > Tasks and creating it again only resets the schedule. Nothing changes about the transferred data. This does not help against single missing days, the re-synchronization is there for that.
The task no longer runs
If the synchronization fails continuously for about a week, ZEP pauses it on its own. The account owner and the administrators receive an email about it.
In the list under System > Tasks the task then shows as paused. Clarify the cause first, usually expired credentials, and then resume the task with Schedule Task.