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.

 

Filter

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

0 comments

Article is closed for comments.

    Topics of this article