Pagination Adoption Guide for V1 GET employees endpoint

Overview

To improve the performance and reliability of Personio public API the pagination for the GET /v1/company/employees endpoint will be enforced.

Key Changes

• Mandatory pagination: All requests to GET /v1/company/employees must include pagination parameters using offset and limit. Unpaginated requests will default to 50 employees per page.
• Limit reduction: The maximum number of employees that can be returned per request will be reduced from 200 to 100.
• Default page size: If no pagination parameters are provided, the response will default to 50 employees per page.

What You Need to Do

Update your API requests

To comply with the new pagination rules, ensure that your requests to the GET /v1/company/employees endpoint include the offset and limit parameters:

• offset: The starting position for the employee records.
• limit: The number of employee records to return, with a maximum of 100.

GET /v1/company/employees?offset=0&limit=100

If no pagination parameters are provided, the API will return 50 employees per page by default:

GET /v1/company/employees

Process paginated responses

The API response will include pagination details within the metadata field. Below is an example of the response structure you will receive:

{  
  "data": [  
     // Employees data  
  ],  
  "metadata": {  
    "total_elements": 100,  
    "current_page": 0,  
    "total_pages": 2  
  },  
  "offset": 0,  
  "limit": 50  
}

Iterating through multiple pages

If the employee dataset spans multiple pages, you will need to adjust the offset to fetch subsequent pages, based on the metadata values returned in the response.

Sample pseudo-code for fetching all employees:

offset = 0  
limit = 100  
employees = []  
while True:  
    response = api.get('/v1/company/employees', params={'offset': offset, 'limit': limit})  
    employees.extend(response['employees'])  
    if response['metadata']['current_page'] >= response['metadata']['total_pages'] - 1:  
        break  
    offset += limit

Error handling

If a request includes a limit greater than 100, the API will return a 422 Unprocessable Entity error. Make sure your application handles these errors appropriately.

{  
    "success": false,  
    "error": {  
        "message": "The limit must be between 1 and 100.",  
        "code": 0,  
        "error_data": {  
            "limit": [  
                "The limit must be between 1 and 100."  
            ]  
        }  
    }  
}

FAQ

Why is pagination now enforced?

Previously, it was possible to request all employees without pagination, which caused performance issues. Enforcing pagination ensures that datasets are returned in manageable chunks, improving performance and reliability.

What happens if I don’t include pagination parameters?

If you don’t specify pagination, the API will default to returning 50 employees per page. You can adjust this by using the offset and limit parameters.

Can I still request 200 employees per page?

No, the maximum limit will be been reduced from 200 to 100 to optimize performance and ensure efficient handling of high traffic.