Personio API Directory

Personio is a comprehensive cloud-based HR software tailored specifically for small and medium-sized enterprises (SMEs) aiming to streamline and automate their HR processes. This robust platform offers a suite of tools designed to enhance HR management, recruitment, performance management, and time management. By centralizing employee data, Personio enables businesses to efficiently track attendance, manage payroll, oversee job postings, and handle applicant tracking. Additionally, it facilitates performance reviews and the management of working hours and leave requests, making it an invaluable asset for companies seeking to digitize their HR operations and minimize administrative burdens.

One of the standout features of Personio is its ability to integrate seamlessly with other systems through the Personio API. This integration capability allows businesses to connect Personio with various third-party applications, enhancing the software's functionality and ensuring a smooth flow of data across platforms. By leveraging the Personio API, companies can customize their HR processes to better fit their unique needs, further optimizing their HR management and operational efficiency.

Key highlights of Personio APIs

• 1. Easy Data Access:
  • Seamlessly read and write company, census, and payroll data, including deductions and benefits contributions.
• 2. Automation:
  • Supports automated data transfer to streamline administrative processes and reduce manual data entry.
• 3. Custom Integration:
  • Open API allows for easy integration with other software solutions, connecting existing systems with Personio.
• 4. Third-Party Integrations:
  • Integrates with applications like Xero and DATEV for effortless data transfer and enhanced HR processes.
• 5. Unified API via Merge:
  • Connects products with Personio and other applications to help businesses close more deals and retain customers.
• 6. Scalable:
  • Designed to support companies with 10 to 2000 employees, offering scalability as business needs grow.
• 7. Developer-Friendly:
  • Enables the creation of automations, scripts, and applications to enhance HR processes.

Personio API Endpoints

Absence Management

• POST https://api.personio.de/v1/company/absence-periods : The 'Create an Absence Period' API allows you to add absence data for absence types with a time unit set to hours. It does not support creating periods for absence types with certificate requirements enabled. The API requires headers for partner and application identifiers. The request body must include employee ID, time-off type ID, start and end dates, and optionally start and end times for partial-day absences, half-day indicators, comments, and approval settings. A successful response returns details of the created absence period, including its ID, measurement unit, effective duration, employee and absence type details, and timestamps. Error responses include codes and messages for invalid requests, not found errors, validation errors, and internal server errors.
• DELETE https://api.personio.de/v1/company/absence-periods/{id} : This API deletes an absence period by its ID for absence types with the time unit set to hours. The request requires the absence period ID as a path parameter. Optional headers include 'X-Personio-Partner-ID' and 'X-Personio-App-ID' for partner and application identification. A successful response (200) returns a success message indicating the absence period was deleted. If the request is invalid (400), an error message is returned. If the absence period ID is not found (404), an error message is also returned.

Attendance Management

• POST https://api.personio.de/v1/company/attendances : The 'Create an Attendance' API endpoint allows for adding attendance data for company employees. It supports adding attendances for one or multiple employees simultaneously. The request body should contain a list of attendance periods, each with details such as employee ID, date, start and end times, break duration, project ID, and comments. The API requires optional headers for partner and application identifiers. On success, it returns the IDs of created attendance periods. In case of errors, detailed messages are provided. The API also supports an optional 'skip_approval' parameter to manage approval flows.
• GET https://api.personio.de/v1/company/attendances/projects : The List Projects API provides a list of all company projects. It is a GET request to the endpoint https://api.personio.de/v1/company/attendances/projects. The request can include optional headers such as X-Personio-Partner-ID and X-Personio-App-ID for partner and application identification. The response includes a success flag and a data array containing project details such as id, type, name, active status, and timestamps for creation and last update.
• PATCH https://api.personio.de/v1/company/attendances/projects/{id} : The 'Update Project by ID' API allows users to update the details of a specific project identified by its numeric ID. The API endpoint is 'https://api.personio.de/v1/company/attendances/projects/{id}' and uses the PATCH method. The request requires the 'id' path parameter to specify the project to be updated. The request body can include 'name' and 'active' fields to update the project's name and availability status, respectively. The response includes a success status and the updated project details if successful (HTTP 200), or error messages if the request fails due to invalid data (HTTP 400) or if the project is not found (HTTP 404).
• PATCH https://api.personio.de/v1/company/attendances/{id} : The 'Update Attendance by ID' API endpoint allows updating attendance data for company employees. The endpoint requires the attendance ID as a path parameter and accepts optional body parameters such as date, start_time, end_time, break, comment, project_id, and skip_approval. Headers may include X-Personio-Partner-ID and X-Personio-App-ID for identification. The response includes a success status and a message or error details if the request fails.

Custom Reports

• GET https://api.personio.de/v1/company/custom-reports/columns : The 'List Custom Report Column Labels' API endpoint provides human-readable labels for report table columns. It is useful for matching column IDs to their translations, especially when dealing with custom attributes or absence data. The API accepts optional query parameters such as 'columns' to filter specific columns, 'locale' for translating localized fields, and 'report_id' to filter results by report ID. If no report ID is provided, all columns for the company are returned. The response includes metadata about the request and detailed information about each column, including its ID, human-readable label, and data type.
• GET https://api.personio.de/v1/company/custom-reports/reports : The 'List Custom Reports' API endpoint allows users to retrieve metadata about existing custom reports in their Personio account. The API supports filtering the results by report IDs and status through query parameters. The request headers can include 'X-Personio-Partner-ID' and 'X-Personio-App-ID' for identification purposes. The successful response (HTTP 200) includes metadata such as total elements, current page, and total pages, along with detailed information about each report, including its ID, name, description, author, type, status, date range, and filters. In case of an error (HTTP 500), the response provides details about the error, including a trace ID, timestamp, and error specifics.
• GET https://api.personio.de/v1/company/custom-reports/reports/{report_id} : The 'Get Custom Report by ID' API endpoint allows users to retrieve data of an existing custom report by specifying the report ID. The endpoint requires the 'report_id' as a path parameter. Optional query parameters include 'locale' for translating localized fields, 'page' for pagination, and 'limit' to specify the number of employees returned per page. Headers can include 'X-Personio-Partner-ID' and 'X-Personio-App-ID' for partner and application identification. The response includes a success status, metadata about the report, and detailed data about the report's attributes, including employee information and various attributes such as performance targets, salary, and compensation details. The API handles various response codes, including 200 for success, 400 for bad requests, 404 for report not found, and 500 for internal server errors.

Document Management

• GET https://api.personio.de/v1/company/document-categories : The 'List Document Categories' API endpoint is used to fetch all document categories of a company. It requires optional headers 'X-Personio-Partner-ID' and 'X-Personio-App-ID' for partner and application identification. The response includes a success flag and a list of document categories, each with an ID, type, and name attribute.
• POST https://api.personio.de/v1/company/documents : This API endpoint allows for uploading documents to the profiles of company employees. It requires a POST request to the specified URL with necessary headers and body parameters. The body parameters include the document title, employee ID, category ID, and the file itself, among others. The response will indicate success with details of the uploaded document or provide error messages if the upload fails due to invalid parameters or non-existent employee or category IDs.

Employee Management

• GET https://api.personio.de/v1/company/employees : The 'List Company Employees' API allows users to retrieve a list of employees from a company. The API endpoint is 'https://api.personio.de/v1/company/employees' and it uses the GET method. Users can filter the results using query parameters such as 'limit', 'offset', 'email', 'attributes[]', and 'updated_since'. The 'updated_since' filter is applied only to attributes that are whitelisted as part of the API Credentials. The API requires optional headers 'X-Personio-Partner-ID' and 'X-Personio-App-ID'. The response includes a list of employees with detailed attributes such as 'id', 'first_name', 'last_name', 'email', 'gender', 'status', and more. The response is in JSON format and includes a 'success' boolean and a 'data' array containing employee details.
• GET https://api.personio.de/v1/company/employees/attributes : The 'List Allowed Employee Attributes' API endpoint allows users to retrieve a list of all the attributes that can be associated with employees in the Personio system. This includes standard attributes like first name, last name, email, and more specialized attributes such as hire date, termination date, and salary details. The API requires optional headers for partner and application identification. The response includes a success flag and a data array containing objects with details about each attribute, including its key, label, type, universal ID, and any options available for list-type attributes.
• GET https://api.personio.de/v1/company/employees/custom-attributes : The 'List Allowed Custom Attributes' API endpoint allows users to retrieve a list of custom attributes available for employees in the Personio system. This endpoint is an alias for /company/employees/attributes. The API uses the GET method and requires optional headers for partner and application identification. The response includes a success flag and a data array containing objects with details about each attribute, such as key, label, type, universal ID, and options for list-type attributes. The available attribute types include standard, date, integer, decimal, list, link, tags, and multiline.
• GET https://api.personio.de/v1/company/employees/{employee_id} : The 'Get Employee by ID' API allows users to retrieve detailed information about a specific employee using their unique employee ID. The API requires the 'employee_id' as a path parameter, which is mandatory. Optional headers include 'X-Personio-Partner-ID' and 'X-Personio-App-ID' for partner and application identification. The response includes a success flag and a data object containing comprehensive employee attributes such as personal details (first name, last name, email, gender), employment details (position, supervisor, employment type, weekly working hours), and other organizational information (department, office, subcompany, cost centers, holiday calendar, work schedule). In case of an error, the response will include an error object with a code and message.
• GET https://api.personio.de/v1/company/employees/{employee_id}/absences/balance : This API retrieves the absence balance for a specific employee identified by the employee_id path parameter. The request requires optional headers for partner and application identifiers. The response includes a success flag and a data array containing details of various absence types, their effective balance, and available balance. If the request fails, an error object with a code and message is returned.
• GET https://api.personio.de/v1/company/employees/{employee_id}/profile-picture/{width} : The Get Employee Profile Picture API retrieves the profile picture of a specified employee. It requires the employee's numeric ID and the desired width of the image as path parameters. The API supports optional headers for partner and application identification. If the profile picture is available, it returns the image in the specified width. If the employee does not exist, the profile picture is missing, or the attribute is not whitelisted, a 404 error is returned with details in the response body.

Time-Off Management

• GET https://api.personio.de/v1/company/time-off-types : The List Time-Off Types API provides a list of absence types for absences with time units set to either days or hours. It includes types such as 'Paid vacation', 'Parental leave', or 'Home office'. The API supports pagination through 'limit' and 'offset' query parameters. The response includes a success flag and an array of time-off type objects, each containing details like id, name, unit, category, legacy category, and other attributes related to the time-off type.
• POST https://api.personio.de/v1/company/time-offs : The 'Create a Time-Off' API allows you to add absence data for employees for absence types with a time unit set to days. The API requires the employee ID, time-off type ID, start and end dates, and whether the start and end dates are half-days. Optional parameters include a comment and a flag to skip approval. The API returns a success status and details of the created time-off, including the time-off type, employee details, and certificate status. Error responses include invalid requests, not found errors, and validation errors.
• DELETE https://api.personio.de/v1/company/time-offs/{id} : The 'Delete Time-Off by ID' API allows users to delete an absence period by specifying its ID in the path parameters. The API uses the DELETE method and requires the 'id' path parameter to identify the absence period to be deleted. Optional headers 'X-Personio-Partner-ID' and 'X-Personio-App-ID' can be included for partner and application identification. Upon successful deletion, a 200 response is returned with a success message. If the ID is invalid, a 400 error response is returned, and if the absence period is not found, a 404 error response is returned.

Recruiting

• POST https://api.personio.de/v1/recruiting/applications : This API allows you to create applications in Personio by sending a POST request to the specified endpoint. The request body must include details such as the job position ID, applicant's first and last name, and email. Optional fields include recruiting channel ID, external posting ID, message, application date, tags, phase, files, and attributes. The response will indicate success with a 201 status code or provide error details if the request fails.
• POST https://api.personio.de/v1/recruiting/applications/documents : This API endpoint allows users to upload documents that can later be attached to applications. The request requires a multipart-form-data file upload with a maximum size of 20MB. Supported file types include pdf, pptx, xlsx, docx, and many others. The request headers must include the company's Personio ID and an authorization bearer token. Upon successful upload, the response returns a UUID for the file, which can be used to attach the file to an application. The response also includes the file size, MIME type, original filename, and file extension. Error responses include unauthorized access, forbidden access, payload too large, unprocessable entity, too many requests, and internal server error.

Job Positions

• GET https://api.personio.de/xml : The Retrieve Open Positions API allows users to access the job positions XML feed from the Company Career Site. The API supports multiple languages, specified by the 'language' query parameter, which is required. The available languages are German (de), English (en), French (fr), Spanish (es), Dutch (nl), Italian (it), and Portuguese (pt). The request headers may include 'X-Personio-Partner-ID' and 'X-Personio-App-ID' for partner and application identification, respectively, and must include 'X-Company-ID' for the company's Personio ID. The response includes an array of job postings, each containing details such as job ID, subcompany, office, department, recruiting category, job name, job descriptions, employment type, seniority, schedule, years of experience, keywords, occupation, occupation category, and creation date.

Personio API FAQs

How do I generate API credentials in Personio?

• Answer: To generate API credentials in Personio:some text
  1. Navigate to Settings > Integrations > API Credentials.
  2. Click on Generate new credentials.
  3. Select the desired scopes and readable attributes for the API key.
  4. Save the generated client_id and client_secret securely.
• Source: Generate and manage API credentials - Personio

What authentication method does the Personio API use?

• Answer: The Personio API uses OAuth 2.0 for authentication. After obtaining your client_id and client_secret, you can request an access token by making a POST request to the authentication endpoint. This token must be included in the Authorization header of your subsequent API requests.
• Source: Get started with Personio API - Personio Developer Hub

Are there rate limits for the Personio API?

• Answer: Yes, Personio enforces rate limits to ensure fair usage:some text
  • Documents and Applications Endpoints: Limited to 20 requests per 60 seconds per company.
  • Other Endpoints: Specific rate limits are not publicly documented; it's recommended to implement error handling for potential 429 Too Many Requests responses.
• Source: Introduction - Personio Developer Hub

Can I retrieve employee data using the Personio API?

• Answer: Yes, you can retrieve employee data by making a GET request to the /v1/company/employees endpoint. Ensure that the desired employee attributes are whitelisted in your API credentials settings to access them via the API.
• Source: List Employees - Personio Developer Hub

Does the Personio API support webhooks?

• Answer: Yes, Personio supports webhooks for specific events, such as when an employee's profile is created, updated, or deleted. You can configure webhooks to receive real-time notifications for these events.
• Source: Personio Developer Hub

‍

Get Started with Personio API Integration

For quick and seamless integration with Personio API, Knit API offers a convenient solution. It’s AI powered integration platform allows you to build any Personio API Integration use case. By integrating with Knit just once, you can integrate with multiple other CRMs, HRIS, Accounting, and other systems in one go with a unified approach. Knit takes care of all the authentication, authorization, and ongoing integration maintenance. This approach not only saves time but also ensures a smooth and reliable connection to Personio API.‍

To sign up for free, click here. To check the pricing, see our pricing page.