Getting started with the Personio API

Welcome to the Personio Developer Hub! Whether you want to build an out-of-the-box integration for the +4000 Personio customers or just for your own team, this guide will help you getting started.

📘

Want to integrate your product with Personio and become a Product Partner?
See our Product Partnership Guideline to learn more about how to become a certified partner.


1. Get a Personio account

In case you don't already have one, you will first need a Personio Account to get started. If you are looking to integrate your product with Personio and don't have an account yet, please fill out the partnership form as described here

Your user account will also need API access rights in order to create API credentials for the next step.


2. API access and authorization

Depending on which endpoints you're planning to use, there's two different types of credentials. Both can be found under Settings > API credentials in your Personio account.

❗️

Cross-Origin Resource Sharing

API keys are used to authenticate incoming requests to our API. The holder of the client_id and client_secret is considered a trusted source, keeping the pair safe from various forms of exposures and attacks. Hence, we strongly discourage implementations, that are running on a user's browser, since it is considered an unsafe environment where credentials can easily leak to malicious actors. To discourage the approach, Personio uses CORS (cross-origin resource sharing) to prevent browsers from getting data directly from our APIs.


2.1 Employee, Attendance and Absence endpoints

For using the Employee, Attendance, and Absence endpoints, you will need to generate API credentials (client_id and client_secret) by clicking Generate new credentials.

When using the GET employee endpoint, you will also need to whitelist the employee attributes in the Wizard. To do so, you have to give access to the employees endpoint and select any number of attributes from the list.

With the API credentials generated and attributes whitelisted, you are ready to access the API as described here.

2.2 Recruiting API

The access token for the recruiting API is predefined for each account and can be directly retrieved from the credentials section and used to get open positions and post applications as described here.


3. Working with the Personio API endpoints

After you've created the necessary API credentials and familiarized yourself with the authorization process, you're ready to call the API endpoints.
In the following sections you'll find some pointers on working with the four endpoints offered on the Personio API:

  • Employee
  • Attendances
  • Absences
  • Recruiting

🚧

Webhooks

Please be aware, that we currently don't offer webhooks.

3.1 Employee

The Employee endpoint supports GET, POST and PATCH both for system and custom employee attributes.

GET

  • Only whitelisted attributes (see 2.1) can be retrieved via the API
  • Returned attributes include the current value only (not scheduled or historical values)
  • Please note that currently no salary data (except fixed salary 100% and hourly wage) is automatically available via API endpoints.
  • Custom employee attributes are following this pattern:
"dynamic_24407"{
    "label":"Titel",
    "value":"Dr"
}

POST / PATCH

  • When updating employees (PATCH), the following attributes from the personnel information can be changed:
    first_name, last_name, gender, position, subcompany, department, office, hire_date, weekly_hours, custom_attributes.

  • Custom attributes can be also be edited using the PATCH endpoint. To do so, you first need to retrieve the dynamic attribute names by calling the GET custom attributes endpoint

GET  http://api.personio.de/v1/company/employees/custom-attributes

3.2 Attendance

The Attendance endpoint supports GET, POST, PATCH and DELETE.

POST / PATCH

  • Start time, end time and pause time must be transmitted
  • This also applies in case the end time was forgotten – in this case an end time must be defined either way (e.g. identical to start time), to ensure that a time pair ist transmitted.
  • Start time must be before end time
  • Attendance periods must not overlap
  • Attendance periods cannot run over two days. These must first be divided into two periods before they can be transferred to Personio

Further Information

  • For days on which an employee does not record times, 00:00 - 00:00 (break time: 00) must be transferred so that correct over- and minus-hour calculation can be carried out in Personio. This is only necessary if minus hours are recorded in your company.
  • Automatic transfer of deficit times for days on which no times are recorded should be limited to employees with the status "active" and should be optionally activatable or deactivatable for the customer.

3.3 Absence

The Absence endpoint supports GET, POST and DELETE

POST

  • Start and end day of the absence period must be transferred
  • For each absence period you must specify whether the first / last day is a half day with an boolean.
  • Start day must be before or on the end day of the absence period
  • If start or end day is a half day, this has to be defined as a boolean (0 / 1) in the code

For more information on the method of customizing existing absence periods that have been changed in the time tracking module in Personio, see the following list:

  • Request for an updated absence period for the relevant period carry out
  • Check whether an existing period exists for the corresponding period
  • If an existing period exists for the corresponding period, the system checks whether the period is identical
    (1) if the start and end dates and the half-day information are identical, the existing period is left as it is and not retransferred
    (2) in case of different start and end dates or different information on the half days, the existing period will be deleted and the new one transferred

🚧

Hourly Absences

Please note, that absence types that allow for hourly absence bookings are not taken into account in the absence endpoint.

3.4 Recruiting API

The Recruiting API allows you to GET open job positions (as described here) and POST applications to Personio (as described here). Other methods are currently not supported.

For the Recruiting API endpoint, please use the separate access token provided under Settings > API > Credentials > Recruiting API Access Token as described above.

POST

  • Applicants can only be transferred via the API for assigned job postings that are published at that time

  • Size per documentation is a maximum of 20 MB

  • General transmission size is a maximum of 64 MB

  • The following document types are allowed: 'pdf', 'docx', 'doc', 'jpg', 'png', 'txt', 'jpeg', 'odt', 'ods', 'xlsx', 'rtf', 'xls', 'pptx', 'ppt', 'gif', 'tif', 'tiff', 'bmp', 'csv', 'rar', 'gz', 'zip', '7z'.

  • System attributes are described in this documentation. You can also transfer user-defined applicant attributes using the applicant API. To do this, check the dynamic name of the respective attribute in Personio under Settings > Recruiting > Applicant > Edit Attribute > API Attribute Name

  • You can transfer job postings from Personio to your career site via xml feed. You can find further information here.


Did this page help you?