Beta Test I Custom Reports API I August 2022

This article provides all the information needed by Personio customers who are participating in the beta test for the Custom Reports API. Thank you for participating in this beta test.

Tip
Click on the Follow button at the top-right of the application to receive an email notification that includes current information on the development progress and the individual beta phases.

 

The Beta Testing Procedure

The beta test is expected to proceed as follows:

Time

Description

CW 34

Start of the beta phase: The functionalities listed below are activated in your Personio account.

CW 38

Global Release: the functionalities listed above are available for all customers

Scope of Beta Testing

The following functionalities are available in the current beta phase:

  1. Endpoint to get a list of existing custom reports:
    This endpoint provides you with metadata about existing custom reports in your Personio account, such as report name, report type, report date / timeframe.
  2. Endpoint to get a list of columns/attribute definitions:
    This endpoint provides human-readable labels for report table columns. It is particularly important if you get a report with custom attributes or absence data, as you will need to match the column IDs to the translation. 
  3. Endpoint to get report data of an existing custom report:
    This endpoint provides you with the data in an existing Custom Report in JSON format. 

For using the Custom Reports endpoint, generate credentials or activate the Read endpoint for an existing pair of credentials. A Write endpoint is currently not implemented.

Note
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. 

 

API access and authorization

Detailed information on general access and authorization can be found in the Personio Developer Hub

 

Custom Reports Endpoints

For using the Custom Reports endpoints, you will need to generate API credentials (client_id and client_secret). To do so, follow these steps:

  1. Click on Generate new credentials.
  2. Tick Read for Custom Reports. It is also possible to activate the Custom Report Read endpoint for an existing pair of credentials. 

     

    custom-reports-api-credentials_en-us.png

    The Custom Reports API 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.

    A common use case for the Custom Reports API is to export data contained in a Personio custom report to other systems, such as a BI tool or a data warehouse. 

    When using the Custom Reports API, please be aware of the following points:

    Large data sets or time ranges

    For reports that include large numbers of employees or span long date ranges, it’s 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.

    Custom Attributes

    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

     

    GetReports endpoint

    HTTP Method - GET

    https://api.personio.de/v1/company/custom-reports/reports

    The purpose of this endpoint is to retrieve the list of the existing custom reports in your account. Note that you can only retrieve reports that were already created within the Personio platform.

    Response Example

    {
       "success": true,
       "metadata": {
           "total_elements": 92,
           "current_page": 1,
           "total_pages": 1
      },
       "offset": 0,
       "limit": 0,
       "data": [
          {
               "type": "Report",
               "attributes": {
                   "id": "9f1edbf3-f68e-4f13-83e3-9b1400bacw313",
                   "name": "Test Report",
                   "description": "This is a description",
                   "author_first_name": "Robert",
                   "author_last_name": "Wilson",
                   "type": "point_in_time",
                   "status": "UP_TO_DATE",
                   "start_date": "2022-07-13",
                   "end_date": "2022-07-13",
                   "created_at": "2022-07-11T12:39:05Z",
                   "updated_at": "2022-07-12T09:45:13Z",
                   "data_refreshed_at": "2022-07-12T09:45:13Z",
                   "columns": [
                       "first_name",
                       "last_name",
                       "position",
                       "team_id",
                       "department_id",
                       "fix_salary",
                       "dynamic_1945114"
                  ],
                   "filters": [
                      {
                           "column": "subcompany_id",
                           "comparison": "neq",
                           "value": "7996"
                      },
                      {
                           "column": "subcompany_id",
                           "comparison": "neq",
                           "value": "21963"
                      },
                  ],
                   "period_type": "today",
                   "items": null
              }
          }
      ]
    }

    GetColumns endpoint

    HTTP Method - GET

    https://api.personio.de/v1/company/custom-reports/columns?locale=de

    The purpose of this endpoint is to retrieve a list of all available columns to allow users to map column_id to the human-readable translation.

    Response Example
    {
       "success": true,
       "metadata": {
           "total_elements": 232,
           "current_page": 1,
           "total_pages": 1
      },
       "offset": 0,
       "limit": 0,
       "data": [
          {
               "type": "Column",
               "attributes": {
                   "id": "id",
                   "human_readable": "ID",
                   "data_type": "INTEGER"
              }
          },
          {
               "type": "Column",
               "attributes": {
                   "id": "first_name",
                   "human_readable": "First name",
                   "data_type": "TEXT"
              }
          },
          {
               "type": "Column",
               "attributes": {
                   "id": "last_name",
                   "human_readable": "Last name",
                   "data_type": "TEXT"
              }
          },
          {
               "type": "Column",
               "attributes": {
                   "id": "email",
                   "human_readable": "Email",
                   "data_type": "TEXT"
              }
          },
          {
               "type": "Column",
               "attributes": {
                   "id": "dynamic_47589",
                   "human_readable": "Birthday",
                   "data_type": "DATE"
       }
          }
      ]
    }

    Tip
    To offer richer data for reporting purposes, that the data_type(s) for the column of the custom reports endpoint, might be different from data_types in the employees' endpoint.


    GetReportData endpoint

    HTTP Method - GET

    https://api.personio.de/v1/company/custom-reports/reports/{report_id}

    The purpose of this endpoint is to retrieve the data of an existing custom report from your account.

    Response Example
    {
       "success": true,
       "metadata": {
           "total_elements": 114,
           "current_page": 1,
           "total_pages": 1
      },
       "offset": 0,
       "limit": 0,
       "data": [
          {
               "type": "Report",
               "attributes": {
                   "id": "9f1edbf3-f65e-4f13-83e9-9b1400bace13",
                   "name": "Report Name",
                   "description": "This is a description",
                   "author_first_name": "Robert",
                   "author_last_name": "Wilson",
                   "type": "point_in_time",
                   "status": "UP_TO_DATE",
                   "start_date": "2022-07-12",
                   "end_date": "2022-07-12",
                   "created_at": "2022-07-11T12:39:05Z",
                   "updated_at": "2022-07-12T09:45:13Z",
                   "data_refreshed_at": "2022-07-12T09:45:13Z",
                   "columns": [
                       "first_name",
                       "last_name",
                       "position",
                       "team_id",
                       "department_id",
                       "fix_salary",
                       "dynamic_1945114"
                  ],
                   "filters": [],
                   "period_type": "today",
                   "items": [
                      {
                           "employee_id": 1314107,
                           "attributes": [
                              {
                                   "attribute_id": "first_name",
                                   "data_type": "TEXT",
                                   "value": "Adella Lena"
                              },
                              {
                                   "attribute_id": "last_name",
                                   "data_type": "TEXT",
                                   "value": "Broose-Maier"
                               },
                              {

                                   "attribute_id": "position",
                                   "data_type": "TEXT",
                                   "value": "Director Engineering"
                               },
                              {

                                   "attribute_id": "team_id",
                                   "data_type": "ENTITY",
                                   "entity_id": "64728",
                                   "value": "Executive Team"
                               },
                              {

                                   "attribute_id": "department_id",
                                   "data_type": "ENTITY",
                                   "entity_id": "412781",
                                   "value": "Product & Engineering"
                              },
                              {
                                   "attribute_id": "fix_salary",
                                   "data_type": "SALARY",
                                   "amount": "100000.00",
                                   "currency_symbol": "$"
                              },
                              {
                                   "attribute_id": "fix_salary_interval",
                                   "data_type": "TEXT",
                                   "value": "yearly"
                              },
                              {
                                   "attribute_id": "dynamic_1945114",
                                   "data_type": "OPTION",
                                   "value": "Festanstellung/Permanent position"
                              }
                          ]
                      },
                      {
                           "employee_id": 2610586,
                           "attributes": [
                              {
                                   "attribute_id": "first_name",
                                   "data_type": "TEXT",
                                   "value": "Joline"
                              },
                              {
                                   "attribute_id": "last_name",
                                   "data_type": "TEXT",
                                   "value": "Sicha"
                              },
                              {
                                   "attribute_id": "position",
                                   "data_type": "TEXT",
                                   "value": "Engineering Manager"
                               },
                              {

                                   "attribute_id": "team_id",
                                   "data_type": "ENTITY",
                                   "entity_id": "64938",
                                   "value": "A Team"
                              },
                              {
                                   "attribute_id": "department_id",
                                   "data_type": "ENTITY",
                                   "entity_id": "346001",
                                   "value": "Research & Development"
                               },
                              {

                                   "attribute_id": "fix_salary",
                                   "data_type": "SALARY",
                                   "amount": "70000.00",
                                   "currency_symbol": "$"
                              },
                              {
                                   "attribute_id": "fix_salary_interval",
                                   "data_type": "TEXT",
                                   "value": "yearly"
                              },
                              {
                                   "attribute_id": "dynamic_1945114",
                                   "data_type": "OPTION",
                                   "value": "Festanstellung/Permanent position"
                              }
                          ]
                      }
                  ]
              }
          }
      ]
    }

     

    Note
    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. 

    Tip
    For further details, please find an openapi.yaml file in this article's Downloads section. 

    Feedback

    As a beta customer, you have the opportunity to actively shape the peer review experience for the Custom Reports API. The feature that you are testing is in an early development stage, and we would love to hear your thoughts about it. The sooner we receive your feedback the better, so that ideally we can analyse and further consider it for future improvements.

    Please fill out this form to share your feedback with us:

    Note
    Every Beta Tester needs to submit feedback at least one time during the test phase using the Typeform form below.

     

Comments

0 comments

Please sign in to leave a comment.

    Topics of this article

    Downloads