Setting Up the Personio Attendance API
This article is a guide to using the Personio attendance API, which can be used in conjunction with integrations and external tools. The API offers you the option of (with the help of an IT professional) retrieving employee attendance periods that have been logged in Personio in the form of raw data as well as recording attendance periods in Personio.
Please note that the use of the attendance API is only available with the Enterprise plan and above. To change plans or for further information, please feel free to contact us via upgrade@personio.de.
Please note that the integration of the attendance API should be carried out by an IT professional. You can find the technical documentation for our API, along with all endpoints and technical tutorials, at https://developer.personio.de/.
Authentication and Use
Both the GET and the POST endpoint are protected and are only accessible through authentication via a security token. You can find further information on this here.
In the following, we will describe the differences between the GET and POST endpoints:
- GET / company / attendances
- POST / company / attendances
Retrieving Employee Attendance Information (GET)
Endpoint | /company/attendances |
Method | GET |
Description |
Employee attendance periods can be retrieved from this endpoint. Page breaks can be used to display the attendance information over several pages, thus giving you a better overview. In addition, you can filter the retrieved attendance information using a time period that is relevant for you, only select certain employees, and/or include inactive employees in your search. |
Below, you will see a list of the filters that can be used for retrieving attendance information:
Filter | Typ | Format | Erforderlich | Standard | Beschreibung |
start_date | string | YYYY-mm-dd | ja | First day of the period being retrieved. The first day will itself also be included in the results. | |
end_date | string | YYYY-mm-dd | ja | Last day of the period being retrieved. The last day will itself also be included in the results. If the first and last day are the same, only the attendance for this day will be displayed. | |
employees | array | [int, ...] | nein |
In order to display the attendance information for specific employees only, use your employees’ Personio IDs. If no filter is set, the attendance information for all employees will be retrieved. |
|
limit | int | nein | 200 |
Limit the number of data sets displayed with the Limit command. If, for example, you would like to limit the number of attendance data sets displayed to 200, set a Limit of ‘200’. Then only 200 rows will be displayed. |
|
offset | int | nein | 0 |
Reduce the number of data sets displayed by the API with the Offset command. If, for example, you would like to request attendance data from row 300 onwards, set an Offset of ‘300’. Then your request will only return results from row 300 up to your limit (see above). The main benefits of a limited request relate to storage and reducing loading times. |
Parameters for Retrieving Attendance Periods
Here you can see the different attributes and types that are relevant when retrieving attendance periods.
Attribut | Typ | Format | Beschreibung |
date | string | YYYY-mm-dd | Attendance day |
start_time | string | hh:mm | Start time |
end_time | string | hh:mm | End time |
break | int | Length of break in minutes | |
comment | string | Description or comment relating to the attendance | |
is_holiday | boolean | [richtig/falsch] | Was the attendance on a public holiday, or not? |
is_on_time_off | boolean | [richtig/falsch] | Was the attendance on a day for which a ‘real’ absence (Absence is time off) has been logged? If so, Personio will count the attendance hours as overtime. |
employee | int | Employee ID |
Adding Employee Attendance Information (POST)
End point | /company/attendances |
Method | POST |
Description | Employee attendance periods can be added from this endpoint. Attendance periods can be added for one or several employees simultaneously. The data packet sent should be a list of attendance periods in the form of an array. |
The filters for adding attendance information are identical to those for retrieving attendance information. They can be found further up in this document.
Parameters for Adding Attendance Periods
Here you can see the different attributes and types that are relevant when adding attendance periods.
Attribut | Typ | Format | Beschreibung |
date | string | YYYY-mm-dd | Attendance day |
start_time | string | hh:mm | Start time |
end_time | string | hh:mm | End time |
break | int | Length of break in minutes | |
comment | string | Description or comment relating to the attendance | |
employee | int | Employee ID |
Validation
The following cases will lead to a validation failure and the data not being saved in Personio:
- The attendance period start_time and end_time overlap with another attendance period that is already logged in Personio for the same day
- No employees found for the filter that has been set
- Incomplete data packet (start-time or end_time missing)
Can't find what you're looking for?
We are happy to help you! Just write us a message with your questions and we will get back to you as soon as possible.
Submit a request
Comments
Article is closed for comments.