Get started with Personio API

📘

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 are two different types of credentials. Both can be found under Settings > API credentials in your Personio account.

NOTE: Personio's API endpoints currently supports the TLS 1.2 protocol to ensure end-to-end security of data being transferred to and from Personio. For a list of ciphers supported by Personio please refer to this link

❗️

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 five endpoints offered on the Personio API:

• Employee
• Attendances
• Absences
• Recruiting
• Custom Reports
• Webhooks

3.1 Employee

The Employee endpoint supports both GET, POST, and PATCH 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 follow 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, the automatic deficit hours feature has to be enabled in Personio. This is only necessary if minus hours are recorded in your company.

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.

3.5 Custom Reports API

The Custom Reports API supports GET only. It allows you to retrieve all rows and fields of a Custom Report formatted in JSON and ready for further analysis or consumption. At present, the API does not allow creating or updating an existing report.

❗️

All existing reports can be retrieved if the Read endpoint is enabled. Additionally, the section Readable employee attributes for the Employee Data API will not be considered for the Custom Reports endpoint. All attributes added to a custom report will be retrievable via the endpoint if it is enabled for the respective credentials, no matter if the attribute has been whitelisted or not.

GET

• Custom employee attributes have an attribute ID that begins with the dynamic_ prefix, which is provided when retrieving report contents using the GetReportData endpoint. To retrieve the human-readable name for the attribute, it is necessary to use the GetColumns endpoint first, which allows cross-referencing the attribute ID to its human-readable name. Names for other locales can be retrieved by affixing ?locale=<2 character locale code> to the GetColumns endpoint, e.g. …/columns?locale=EN
• For reports that include large numbers of employees or span long date ranges, it is recommended to first query the GetReports endpoint to retrieve the data_refreshed_at timestamp for the report of interest. This must be done before retrieving the contents of the report using the GetReportData endpoint to ensure a sufficient period of time has elapsed since the previous data refresh.
• For the historical data report type, the response for historical values is matched to the employee_id only. First name and last name will not be included. To match the employee_id to the name, the employee endpoint can be retrieved.
• To offer richer data for reporting purposes, the data_types for the column of the custom reports endpoint, might be different from the data_types in the Employees’ endpoint.
• Pagination can be used in the GetReport Endpoint via page and limit query parameters. The limit indicates how many employees per page should be returned. Example: /company/custom-reports/reports/{report_id}?page=2&limit=100

Custom Reports can have the following statuses assigned:

• up-to-date: Your report is loaded and up to date. Any data changes that happen in the system that are relevant for report results will trigger an automated update to the report. For example, if a person’s position and salary is changed, any report that displays this data will be updated.
• updating: Your report is currently loading. This can take a while depending on the amount of data.
• update_failed: Something went wrong on our side. Reload the report or reach out through Find Answers if reloading fails.

Further, Custom Reports can have the following archival statuses assigned:

• archived: The report has not been viewed or retrieved via Public API for at least 60 days. We are not updating it anymore. To reactivate the report, open the report and reload. Recent data changes will be reflected afterwards.
• live: The report is live and any data changes that happen in the system that are relevant for the report results will trigger an automated update to the report

The status of a report is also available via the GetReports endpoint.

3.6 Webhooks

Webhooks are now available for the Person entity and the management of Webhooks is administered through the following endpoints

• GET List and GET a Webhook
• POST Create a new Webhook
• PATCH Update a Webhook
• DELETE a Webhook

Do note that the Webhooks Scope (Read and/or Write depending on which of the operations above can be performed) must be present in the API credential in order to access these endpoints.

Personio Webhooks offer limited retry functionality i.e. 3 retries in the span of 30-60 seconds after the initial attempt, to increase the reliability of delivery. Additionally it must be noted that Personio Webhooks do not support redirects. More info about Webhooks can be found here: https://developer.personio.de/v2.0/reference/webhooks