Personio API: Guide for HRIS Integration and Automation

Getting Started with Personio API

Personio API allows businesses to automate and integrate their HR and payroll processes with Personio's platform. It enables:

• Employee Management: Add, update, or remove employee records.
• Payroll Processing: Automate salary calculations, tax deductions, and payments.

This API is designed to streamline HR operations, reduce manual data entry, and ensure data consistency across your organization’s software systems.

‍

OAuth 2.0 Authentication

Before interacting with Personio's API, you need to authenticate your requests to ensure they are secure. Personio uses OAuth 2.0 for authentication, a robust and widely adopted standard.

Steps to Authenticate:

1. Obtain API Credentials:
   • Client ID and Client Secret: Provided by Personio when you register your application.
2. Request an Access Token:
   • Send a POST request to the authentication endpoint with your credentials to receive an access token.

curl --request POST \
     --url https://api.personio.de/v2/auth/token \
     --header 'accept: application/json' \
     --header 'content-type: application/x-www-form-urlencoded' \
     --data grant_type=client_credentials \
     --data 'client_id=[YOUR_CLIENT_ID]' \
     --data 'client_secret=[YOUR_CLIENT_SECRET]'

3. Use the Access Token:
   • Include the token in the Authorization header of your API requests.

Authorization: Bearer YOUR_ACCESS_TOKEN

Example in Python:

import requests

# Authentication details
client_id = "YOUR_CLIENT_ID"
client_secret = "YOUR_CLIENT_SECRET"
auth_url = "https://api.personio.de/v2/auth/token"

# Requesting access token
response = requests.post(auth_url, data={
    "grant_type": "client_credentials",
    "client_id": client_id,
    "client_secret": client_secret
}, headers={
    "accept": "application/json",
    "content-type": "application/x-www-form-urlencoded"
})

access_token = response.json().get("access_token")
print("Access Token:", access_token)

‍

Deep Dive into Personio API Endpoints

The Personio API (v2) provides a range of endpoints that allow developers to access various employee data.

Here are the most commonly used endpoints, along with practical use cases.

1. GET /v2/persons

• Description: Returns a list of all employees. Your managed organisation must manage every employee.
• cURL Request:

curl --request GET \
     --url 'https://api.personio.de/v2/persons?limit=10&id=[PERSON ID]' \
     --header 'accept: application/json'

• Parameters:
  • limit: The amount of resources to be returned per one request. It can range between 1 and 50, and the default is 10.
  • id: Filter results matching one or more provided person ids.
• Use Case: Obtain employee data of an organization from Personio into your system.

‍

2. GET /v2/persons/{id}

Description: This endpoint retrieves a specific employee.

cURL Request:

curl --request GET \
     --url https://api.personio.de/v2/persons/id \
     --header 'accept: application/json'

• Parameters:
  • id: The ID of the employee to retrieve.
• Use Case: Obtain a specific employee’s data from Personio into your system.

‍

3. GET /v2/compensations

• Description: This endpoint retrieves a list of payroll compensations of people for an authorized company.
• cURL Request:

curl --request GET \
     --url 'https://api.personio.de/v2/compensations?start_date=[START_DATE]&end_date=[END_DATE]&person.id=[ID_1]%2C[ID_2]' \
     --header 'accept: application/json'

• Parameters:
  • start_date: A start date from which compensations are run. The duration (end_date - start_date) must be equal to or smaller than a month. The format is ISO-8601 (YYYY-MM-DD)
  • end_date: An end date to which compensations are run.
  • id: The ID of the employees to get payroll for.
• Use Case: Obtain payroll runs for al or specific employees from Personio into your system.

‍

Pagination and Rate Limits

Pagination

When retrieving lists of data (e.g., employees), the API may paginate results using a pagination cursor to manage large datasets efficiently.

• Parameters:
  • limit: The amount of resources to be returned per request. It can range between 1 and 50, and the default is 10.
  • cursor: The pagination cursor to navigate over to the next list of resources.

For example, here’s how you can implement pagination while retrieving employees:

curl --request GET \
     --url 'https://api.personio.de/v2/persons?limit=10&cursor=cur_82sQwR2eZvKilo2duNh219Kw' \
     --header 'accept: application/json'

Rate Limits

For Personio API, rate limit is currently set to:

• 300 requests per minute.
• Burst rate: 15 requests per second.

Exceeding this limit will result in a 429 error. Implement an exponential backoff strategy to retry requests after a brief delay.

‍

Troubleshooting Guide

Error Handling

APIs can return errors for various reasons, such as invalid requests or server issues. Personio uses standard HTTP status codes to indicate success or failure.

Common HTTP Status Codes:

‍

Get Started With with Personio API Using Bindbee

Integrating with Personio shouldn’t feel like a battle.But for most teams, it ends up being a major time sink—draining valuable engineering resources.

Why put your developers through the grind when Bindbee can get you live with Personio in just minutes?

Setting up Personio connector with Bindbee

Sign up with Bindbee and navigate to the dashboard.

Create a Connector:

Click on Create Connector from the dashboard.

Select HRIS as the type of integration. Enter customer details and give your connector a unique ID (e.g., Employment_Hero_Integration).

Generate a Magic Link:

After setting up the connector, click Create Link to generate a magic link. This will allow the customer to authenticate the connection with Personio.

Open the link and enter the necessary credentials. This step establishes the connection between Personio and Bindbee.

Sync the Connector:

Once the connection is made, the connector will begin syncing data from BambooHR. This may take a few minutes depending on the size of the data. You can track the sync status in the connector section.

Access the Synced Data:

After syncing, go to the Employee section in the Bindbee dashboard and select Get Employees to retrieve employee data from BambooHR.

Get the API Key and Connector Token:

Copy the API key and the x-connector-token from the Bindbee dashboard, which you will need to make authenticated API requests.

Retrieving Employee Data with Bindbee

Once the Personio data has been synced, you can retrieve employee data on to your application via the Bindbee API.

Here’s a step-by-step process for accessing synced data from BambooHR through Bindbee’s unified API:

1. Request Setup:

Use the Bindbee API to send a request for employee data. You’ll need both your Bindbee API token and the x-connector-token.

‍2. Example  cURL Request:

curl --request GET \
  --url https://api.bindbee.com/hris/v1/employees \
  --header 'Authorization: Bearer YOUR_BINDBEE_API_KEY' \
  --header 'x-connector-token: YOUR_CONNECTOR_TOKEN'

This request will return a list of employee objects, including details like the employee’s first name, last name, job title, department, and contact information.

‍3. Sample Response:

{
  "items": [
    {
      "id": "018b18ef-c487-703c-afd9-0ca478ccd9d6",
      "first_name": "Kunal",
      "last_name": "Tyagi",
      "job_title": "Chief Technology Officer",
      "department": "Engineering",
      "work_email": "kunal@bindbee.dev"
    }
  ]
}

‍

Bulk Employee Data Retrieval

For retrieving large datasets, Bindbee simplifies the process by allowing you to fetch bulk employee data from BambooHR.

The pagination feature helps manage large responses by returning results in pages.

• Pagination Parameters:
  • Use the cursor and page_size parameters to navigate through the results. By default, Bindbee returns 50 records per page.
  • Example of a paginated request:

url = "https://api.bindbee.com/hris/v1/employees?cursor=MDE4YjE4ZWYtYzk5Yy03YTg2LTk5NDYtN2I3YzlkNTQzM2U1&page_size=50"
response = requests.get(url, headers=headers)

• Querying for Specific Employee Data:
  • You can further refine your request by filtering based on specific fields, such as manager_id, remote_id, or company_id to get employees under a particular manager or company.

Say hello to Bindbee.

Book a demo with our experts today.