Skip to main content

What can we help you with?

Back

The Personio Custom Reports API

 

This article explains what a Public Application Programming Interface (API) is, what can you use the Custom Reports API for, and how to generate API credentials for it.

 

What is a Public API in Personio?

APIs allow data to be exchanged between Personio and another service or tool. This way, you can build connections between Personio and your own databases, or set up integrations with third-party providers that are available in the Personio Marketplace. 

Personio currenlty offers several public APIs: the Recruiting API, the Custom Reports API and the four Personnel Data APIs (Employees, Absences, Attendances, and Documents).

 

What can you do with the Custom Reports API?

The Custom Reports API, in particular, allows you to create more advanced analytics and reporting. 

Depending on the endpoint, this API allows you to:

          • retrieve a list of all existing custom reports in your Personio account (GetReports endpoint),
          • retrieve a list of all existing report table columns (GetColumns endpoint), and;
          • retrieve data of a particular custom report in JSON format (GetReportData endpoint).

In other words, the Custom Reports API allows you to merge Personio HR data with other datasets, to store it in a dataware house, and to process it further in a business intelligence (BI) tool.

Example
You can use the Custom Reports API to retrieve historical employee data, and also to retrieve the number of overtime hours your employees worked in a specific month.

Note
The Custom Reports API does not currenlty allow creating or editing an existing custom report.

 

Generate API Credentials

      1. Go to Settings > Integrations > API credentials.
      2. Click Generate new credential.
      3. The Add new credential sidebar will appear. In the Name field, enter a meaningful name (for example, Custom Reports Credentials) for the API credentials.
      4. If applicable, select an integration from the Integration drop-down menu. If not, select Other.
      5. Select the Read checkbox for the Custom Reports API.

        Tip
        Read more about the different checkboxes in the article Generate and manage API credentials.

      6. Click Generate new credential.
      7. A message will display confirming that the new API credentials have been created.

      custom-reports-api-credentials_en-us.png

      Tip
      Alternatively, you can also activate the Custom Report Read endpoint for an existing API credential. Go to Settings > Integrations > API credentials, click on a credential and select the Custom Report checkbox.

      Note
      All existing reports can be retrieved if the Read endpoint is enabled. Additionally, the section Readable employee attributes for the Personnel 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. 

      Note
      The reports that are not retrieved via the Custom Reports API in a period of 60 days will automatically change into an Archived status. The report will not be automatically updated until it gets reactivated by viewing it via the Personio app. 

Technical documentation

All the documentation for our Custom Reports API, including endpoints, information about the precise data transferred and technical tutorials, is available in our Developer Hub.