Prerequisites
Before you start, please read the following instructions carefully to ensure that all requirements are met for the integration to work:
You have already discussed and licensed the API integration with your Customer Success or Sales Manager.
You have “Administrator” permissions in your Personio instance or an administrator has approved access for you. This is necessary to retrieve the API access data, as explained later in this guide.
Setting up the integration
Log in to your Personio account
If you cannot see the “Settings” gear in the bottom left corner, this means that your account does not have administrator rights.
Find out who the administrator of your Personio account is and ask them to take over the setup process or give your account “Administrator” rights.
Find your API domain
Your API domain is the same domain you use to log in to Personio.
Open your Personio login page, you should be able to see your domain here.
Generate your API credentials
Log in to your Personio account.
Open the marketplace page. You can follow the link in the integration guide or use the following link with your own subdomain
<https://<your> subdomain>.personio.com/configuration/marketplace/connected
Go to the marketplace page and click on “Create custom integration“.
Enter a name for your new connection – e.g. become.1 and click on “Next“.
Check the required read rights in the integration window (the displayed image and the scope it contains serve as an example):
Confirm the required read permissions in the Personio interface, including Employees, Attendances, Absences, Org Units and Legal Companies:
Now confirm the required read rights for the employee attributes.
These attributes should always be clicked on:
|
German label |
English label |
|---|---|
|
Vorname |
Firstname |
|
Nachname |
Lastname |
|
Gesellschaft |
Subcompany |
|
Personalnummer |
Personal Number |
|
Abrechnungsrelevante Personalnummer (z.B. DATEV Personalnummer) |
Payroll-relevant personnel number (e.g. DATEV personal number) |
|
|
|
|
Kostenstelle |
Cost center |
|
Status |
Status |
|
Anstellungsart |
Employment type |
|
Occupation type (bspw. Permanent employee, Working Student, Intern) |
Occupation type (eg. permanent employee, working student, Intern) |
|
Employee ID |
Employee ID |
|
Arbeitszeiten |
Weekly hours |
|
Erstellt am |
Created at |
|
Anstelldatum |
Hire date |
|
Letzter Arbeitstag |
Last day of work |
|
Austrittsdatum |
Termination date |
|
Zuletzt geändert |
Last modified |
|
Position |
Position |
|
Abteilung |
Department |
|
Standort |
Office |
|
Team |
Team |
|
Geburtstag |
Birthday |
|
Wochenstunden |
Weekly-hours |
|
Füge alle relevanten benutzerderfinierten Felder hinzu |
Add all your custom fields which are relevant |
Click on “Create Integration“.
You will now see your created API credentials:
Copy the “Client ID” and the “Client Secret” into the integration flow and click on “Set up Integration“.
Done – you have successfully linked Personio to become.1!
Optional: After setting up the integration there is an option to set a filter which is used to only synchronise parts of the employees contained in Personio for e.g. from specific legal entities or employees with a specific status – more to this within the following article:
Wie nutze ich die HRIS Integration Filter Funktion?