Setting Up the Personio Attendance API

 

This article is a guide to using the Personio Attendance API that can be used in connection with integrations and external tools. The API allows you (with the help of an IT expert) to retrieve the attendance periods that your employees have entered into Personio from the system, and also to feed attendance times into Personio.

Please note that using the Attendance API is only available with Personio's Enterprise Plan. To change your Plan and for further information, please contact us at upgrade@personio.de.

We recommend that you work with an IT expert when integrating the Attendance API. The technical documentation for our APIs, including all endpoints and technical tutorials, can be found at https://developer.personio.de/.

 

Authentication and Use

Both the GET and POST endpoints are secured and only accessible through authentication via a security token. Click here for more detailed information.

The differences between the two endpoints GET and POST are described below:

  • GET / company / attendances
  • POST / company / attendances

 

1. Retrieving your employees' attendance details (GET) 

Endpoint /company/attendances
Method GET
Description

The attendance entries of your employees are queried from this endpoint.

For a better overview, you have the option of using page breaks to display the attendance details over multiple pages. You can also filter for specific time periods and specific employees as required, and/or include inactive employees in your search.

 

Filters

The table below lists the filters that are available when retrieving attendance details:

Filters Type Format Required Standard Description
start_date string yyyy-mm-dd yes   The first day of the time period to be queried. The first day is also considered in the results.
end_date string yyyy-mm-dd yes   The last day of the time period to be queried. The last day is also included in the results. If the first and the last day are identical, only the attendances of that day will be output.
employees array [int, ...] no  

To filter for the attendance details of specific employees, use their Personio ID.

If no filter has been set, all employees' attendance details will be retrieved.

limit int   no 200

Limit the number of records to be output by using the Limit command.

Example: You would like to have no more than 200 attendance records output. Set the Limit to "200."

Only 200 lines will be output.

offset int   no 0

Shrink the data sets that are output via the API by using the Offset command.

Example: You want to query the attendance data only from line 300 onward. Set the Offset to "300."

When the data is queried, only the lines from 300 will be output, up to your limit (see above).

Limiting the query mainly helps to save memory and reduces the time to load.

Also define the attributes to be transmitted under Settings > API > Access > Allowed employee attributes.

 

Parameters for retrieving the attendance periods

The following are the attributes and types that are relevant for the retrieval of attendance periods.

Attribute Type Format Description
date string yyyy-mm-dd Attendance day
start_time string hh:mm Start time
end_time string hh:mm Finish time
break int   Duration of the break in minutes
comment string   Description or comment regarding the attendance
is_holiday boolean [true/false] Is the attendance on a public holiday or not?
is_on_time_off boolean [true/false] Is the attendance on a day for which a "real" absence (absence is time off) had been recorded in the system? If yes, Personio will regard and calculate these attendance hours as overtime.
employee int   Employee ID

 

2. Adding attendance details of your employees (POST)

Endpoint /company/attendances
Method POST
Description The attendance entries of your employees are added from this endpoint. You can add attendances for one employee or for multiple employees at the same time. The transmitted data set should be a list of attendance periods in the form of an array.

The filters for adding attendance details are the same as for retrieving them (see above).

 

Parameters for adding attendance periods

The following are the attributes and types that are relevant for adding attendance periods.

Attribute Type Format Description
date string yyyy-mm-dd Attendance day
start_time string hh:mm Start time
end_time string hh:mm Finish time
break int   Duration of the break in minutes
comment string   Description or comment regarding the attendance
employee int   Employee ID

 

Validation

When the data is validated, the following cases will result in a validation error and the data consequently not being stored in Personio:

  • The attendance period start time and end time overlap with another attendance period that has already been stored in Personio for that day
  • No employee found for the set filter
  • Incomplete data set (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