Sync Personio

With HRIS Sync, onyo automatically imports your employees from Personio – every hour, with no manual import. This guide walks you through the setup step by step.

Prerequisite: In Personio you need the access rights for the Marketplace integration and the API (under Einstellungen → Mitarbeiterrollen → Zugriffsrechte → Konto-Konfiguration) – a full administrator role is not required.

Already connected onyo to Personio? Then do not create a new integration – just reset the credentials, see Reset the credentials at the end of this article.

Note: the screenshots show the German Personio and onyo interfaces; the German labels are quoted alongside the English text.

Step 1: In onyo, set the provider to Personio

In onyo, open the HRIS Sync page (Settings → General → HRIS Sync) and set the HRIS provider to Personio.

Step 2: In Personio, open the onyo Marketplace listing

In Personio, open the Marketplace and search for "onyo". Click the onyo tile in the search results.

Step 3: Check the permissions

Open the onyo integration. Under "Einrichtung und Berechtigungen" (setup and permissions) you can see that onyo only needs the single permission "Daten zu Mitarbeitenden lesen" (read employee data). You do not need to select anything manually here – the permission is granted automatically when you connect.

Step 4: Connect and generate new credentials

Click "Verbinden" (connect) in the top right. In the next step choose "Neue API-Zugriffsdaten generieren" (generate new API credentials) and confirm.

Step 5: Copy the Client-ID and secret

Personio now generates the credentials: the Client-ID and the Client secret. Keep this window open until both values are entered in onyo (the secret is only shown once), and copy them over one at a time – first the Client-ID, then the secret (step 6).

Step 6: Enter the credentials in onyo

Switch back to onyo and, under "Connect", paste the Client-ID into the "Personio client ID" field and the secret into the "Personio API-Secret" field. Then click "Save changes".

Step 7: Configure the sync

The sync settings only appear after the connection has been saved (the group list is loaded live from Personio). Define which employees are imported:

• Employment status – only import employees with these statuses.
• Employment type – only import employees with these employment types.
• HRIS groups – "HRIS groups" is onyo's umbrella term for department, team, office, subcompany and cost center from Personio. It has nothing to do with the Mitarbeiterrollen (employee roles) in Personio, which control access rights. Leave empty to import all current and future groups. Only the attributes onyo may read in Personio are offered: if the list is empty or e.g. the cost center is missing, onyo shows the note "Some optional employee attributes are not shared" under "Connect". In that case, go to Einstellungen → "API-Zugriffsdaten" (settings → API credentials) in Personio, select "onyo" and add the missing attributes to the readable employee attributes.
• Custom fields – only import employees whose own field in Personio has a certain value, e.g. "onyo: yes". See Control access with your own field in Personio further below.
• Budget field in tokens – irrelevant for most companies and only relevant if you use virtual tokens instead of euros in onyo. Enable it only in that case, and only if the budget in Personio is also maintained in tokens.

Important: If you set several filters, employees must match all of them to be imported. For example, if you select certain employment statuses and certain employment types, someone is only imported when both the status and the type match (and, if groups are selected, the person belongs to one of them, and, if custom fields are selected, each of them has one of the ticked values). Within a single filter, one match is enough – e.g. one of the selected statuses.

Step 8: Start the first sync

Click "Synchronize now with Personio" to start the first import. After that, onyo syncs automatically every hour. A green "Sync completed" confirms that everything works.

All done :) From now on onyo keeps your employees in sync with Personio automatically: new people are created in onyo, changes (e.g. name or address) are applied, and people who no longer match your criteria or were deleted in Personio are deactivated – every hour and with no manual import. Should you have any questions or problems, feel free to contact us via the contact form at any time.

Optional: Control access with your own field in Personio

If you want to decide per person directly in Personio who may use onyo, you can use your own (custom) field for it – e.g. a field "onyo" with the values "ja" and "nein" (yes/no).

1. Create the field as a new employee attribute in the Personio settings, e.g. as a selection with the options "ja" and "nein".
2. Set it to "ja" for the employees who should use onyo.
3. Share the field with onyo: in Personio, go to Einstellungen → "API-Zugriffsdaten" (settings → API credentials), select "onyo" and add the field to the readable employee attributes. As long as onyo cannot access any custom field, the HRIS Sync page shows the note "onyo has no access to custom fields." under "Custom fields".
4. In onyo, choose your field under "Custom fields" → "Filter by field…". onyo shows all values of the field and how many people in Personio have each value. Tick the values that grant access to onyo – values like "ja" or "yes" are preselected. Then click "Save changes".

Important: Everyone who has none of the ticked values – including people whose field is empty – is deactivated in onyo at the next sync. So fill in the field in Personio before you save the filter. If nobody currently has one of the ticked values, onyo warns you.

If you later stop sharing the field with onyo or delete it in Personio, onyo stops syncing instead of deactivating all employees – until you share the field again or remove the filter in onyo.

Already connected? Reset the credentials

If you have already set up the onyo integration in Personio, do not create a new integration. Instead, reset the existing credentials:

1. In Personio, go to Einstellungen → "API-Zugriffsdaten" (settings → API credentials) and select "onyo".
2. Open the "API credentials" tab and click "Client-ID und API-Secret zurücksetzen" (reset Client-ID and API secret), then confirm.
3. Enter the new Client-ID and the new API secret in onyo (steps 6–8 above).