Initial core data sync

📘

For a successful integration, you will first need to create the main Personio entities in your system. We expect that many or all of these Personio entities will have a matching entity on your side.

In this section we will guide you through the first download of relevant Personio data into your system. We expect this to be done once per integration.

Fetch Employees

Employees form the central element of our system; All recorded data in Personio is associated with an individual employee. We will guide you through transferring the necessary employee data from Personio to your system.

📘

Determining Which Employees to Sync

Personio's clientele includes both blue-collar and white-collar workers, but not all require shift planning services. It's important to ensure cost-efficiency by syncing only those employees who actually need and use the shift planning features. Please ensure that you only migrate into your system those employees who are activated for Shift Planning.

Begin by listing all employees using the List Persons endpoint. For each employee record, check the boolean attribute that indicates eligibility for shift planning (shift_planning = True).

🚧

Important: 'shift_planning' is a dynamic attribute that needs to be enabled on the customer's Personio account. Therefore, please reach out to your customer's point-of-contact, to create this dynamic attribute in their Personio account. If you don’t find it in your demo or client account, please follow the instructions to create a dynamic attribute here.

You should retain the information only those employees who are flagged for shift planning capabilities (which have the attribute value above set to True).

Currently, the List Persons endpoint does not support filtering by custom attributes, and there are no immediate plans to introduce this feature.

The data provided in each Person object’s response should be sufficient to replicate the entity in your system. If additional details are needed, you can fetch all attributes of an employee using the Retrieve person endpoint.
Persons have employments associated with them. Since a person might be employed multiple times by the same company in their lifetime, employments hold the information about all their relationship periods with the company.

Related API endpoints

Live List persons
Live Retrieve person
Live List employments for a person
Live Retrieve an employment

📘

Fetch Locations

In case you need this information, please use the “office” attribute available in the Employment endpoint for each employee.

There is no Location concept in Personio. We do have Office and Department attributes and the department structure can be obtained using the Org Unit API. If your system requires a Location entity, we suggest that you populate your list of company locations by looping over the employees enabled for shift planning and evaluating the Office attribute of each employee.

Fetch weekly working hours

Weekly working hours are also part of the Employment endpoint response. At the moment, we have decided not to enhance this data with attendance policies.

Fetch planned absences

Absence periods reflect when employees will not be available for shift work. To enable shift planning, you should retrieve the list of active absence periods for each shift worker using the List absence period endpoint.
To determine which shift workers will be unavailable on a specific date, retrieve the list of upcoming absences for all shift workers in your system.