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 +3000 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 of which can be found under Settings > API > Credentials in your Personio account.


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 the download link in the credentials section.
Note: If you request API credentials again, your current API credentials will be invalidated.

When using the GET Employee endpoint, you will also need to whitelist the employee attributes that can be accessed via the API. To do so, navigate to the Access > Edit tab 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 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 enpoints 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

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.

Updated about a month ago


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 +3000 Personio customers or just for your own team, this guide will help you getting started.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.