Guides
Signup For Free

Personio API Integration

Suggest Edits

These are the list of integration use cases supported by Knit for Personio API as part of the HRIS category

Delete Absence Period by ID

  • ID: delete_absence_period_by_id
  • Operation: write
  • Entities: absence type, absence period, time unit
  • Summary: 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.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Delete Attendance by ID

  • ID: delete_attendance_by_id
  • Operation: write
  • Entities: attendance, company, employee
  • Summary: The 'Delete Attendance by ID' API endpoint allows for the deletion of attendance data for company employees. It requires the attendance period ID as a path parameter. Optionally, a query parameter 'skip_approval' can be set to false to trigger an approval flow if applicable. The request headers may include 'X-Personio-Partner-ID' and 'X-Personio-App-ID' for identification purposes. The API returns a success message upon successful deletion or an error message with a code if the request fails due to reasons such as unauthorized access, forbidden access, or if the attendance period is not found.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Delete Project by ID

  • ID: delete_project_by_id
  • Operation: write
  • Entities: attendance, company, project
  • Summary: The 'Delete Project by ID' API allows users to delete a project from the company account by specifying the project's numeric ID in the path parameters. The API uses the DELETE HTTP method and requires the 'id' path parameter to identify the project to be deleted. The request can include an optional 'accept' header to specify the desired response media type. Upon successful deletion, the API returns a 204 status code with no body. If the project does not exist, a 404 status code is returned with a response body containing a 'success' boolean set to false and a 'message' string indicating the project was not found.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Delete Time-Off by ID

  • ID: delete_time_off_by_id
  • Operation: delete
  • Entities: absence type, absence period, company
  • Summary: 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.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Get Absence Balance for Employee

  • ID: get_absence_balance_for_employee
  • Operation: read
  • Entities: absence balance, company, employee
  • Summary: 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.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

List Company Employees

  • ID: get_company_employees
  • Operation: read
  • Entities: company, department, employee
  • Summary: 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.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Get Custom Report by ID

  • ID: get_custom_report_by_id
  • Operation: read
  • Entities: attribute, employee, report
  • Summary: 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.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Get Employee by ID

  • ID: get_employee_by_id
  • Operation:
  • Entities:
  • Summary: 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.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Get Employee Profile Picture

  • ID: get_employee_profile_picture
  • Operation: read
  • Entities: profile picture, error, employee
  • Summary: 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.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

List Absence Periods

  • ID: get_list_absence_periods
  • Operation: read
  • Entities: absence type, absence period, employee
  • Summary: The List Absence Periods API fetches absence periods for absences with the time unit set to hours. It supports pagination and filtering by period, specific employees, absence types, and absence period IDs. The API requires optional headers for partner and application identification. Query parameters include start_date, end_date, updated_from, updated_to, employees[], absence_types[], absence_periods[], limit, and offset. The response includes metadata about the total elements, current page, and total pages, along with detailed data about each absence period, including employee details, absence type, certificate status, and breakdowns of effective duration by date. The API returns a 200 status code for successful requests, and 400 or 500 status codes for bad requests or internal server errors, respectively.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

List Allowed Custom Attributes

  • ID: get_list_allowed_custom_attributes
  • Operation: read
  • Entities: company, attribute, employee
  • Summary: 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.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

List Allowed Employee Attributes

  • ID: get_list_allowed_employee_attributes
  • Operation: read
  • Entities: company, attribute, employee
  • Summary: 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.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

List Attendances

  • ID: get_list_attendances
  • Operation: read
  • Entities: attendance period, employee, project
  • Summary: The List Attendances API allows fetching attendance data for company employees. The data can be filtered by date range, update time, and specific employees. It supports pagination with limit and offset parameters. The request requires optional headers for partner and app identification. The response includes metadata about the total number of elements and pages, and a list of attendance periods with details such as employee ID, date, start and end times, status, and project information. The API returns a 200 status code for successful requests, and 401 or 403 for unauthorized or forbidden access.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

List Custom Report Column Labels

  • ID: get_list_custom_report_column_labels
  • Operation: read
  • Entities: company, column, report
  • Summary: 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.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

List Custom Reports

  • ID: get_list_custom_reports
  • Operation: read
  • Entities: metadata, report, author
  • Summary: 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.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

List Document Categories

  • ID: get_list_document_categories
  • Operation: read
  • Entities: company, document category
  • Summary: 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.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

List Projects

  • ID: get_list_projects
  • Operation: read
  • Entities: attendance, company, project
  • Summary: 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.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

List Time-Off Types

  • ID: get_list_time_off_types
  • Operation: read
  • Entities: time unit, time-off type, certification
  • Summary: 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.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

List Time-Offs

  • ID: get_list_time_offs
  • Operation: read
  • Entities: time off, period, employee
  • Summary: The List Time-Offs API fetches absence periods for absences with the time unit set to days. It supports pagination and filtering by period and specific employees. The API accepts query parameters such as start_date, end_date, updated_from, updated_to, employees[], limit, and offset. The headers include X-Personio-Partner-ID and X-Personio-App-ID. The response includes a success flag and a data array containing details of each time-off type, such as id, name, category, unit, and approval requirements.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Retrieve Open Positions

  • ID: get_retrieve_open_positions
  • Operation: read
  • Entities: company, department, position
  • Summary: 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.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Get Time-Off by ID

  • ID: get_time_off_by_id
  • Operation: read
  • Entities: time off, employee, certificate
  • Summary: The 'Get Time-Off by ID' API retrieves an absence period for absences with the time unit set to days. It requires the absence period's numeric ID as a path parameter. Optional headers include 'X-Personio-Partner-ID' and 'X-Personio-App-ID' for partner and application identification. The API returns a detailed response containing the absence period's attributes, such as status, start and end dates, days count, and associated employee details. If the absence period is not found, a 404 error response is returned with an error code and message.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Update Attendance by ID

  • ID: patch_update_attendance_by_id
  • Operation: write
  • Entities: attendance, company, employee
  • Summary: 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.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Update Employee by ID

  • ID: patch_update_employee_by_id
  • Operation: write
  • Entities: department, employee, supervisor
  • Summary: The Update Employee by ID API allows updating an existing employee's details using a PATCH request to the specified endpoint. The request requires the employee_id as a path parameter and accepts various fields in the request body, such as first_name, last_name, preferred_name, gender, position, subcompany, department, office, hire_date, weekly_working_hours, status, supervisor_id, and custom_attributes. Note that the email field cannot be updated. The response returns a success status and the updated employee's ID if successful, or an error code and message if the update fails.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Update Project by ID

  • ID: patch_update_project_by_id
  • Operation: write
  • Entities: attribute, project, parameter
  • Summary: 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).
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Create a Project

  • ID: post_create_a_project
  • Operation: write
  • Entities: attendance, company, project
  • Summary: This API endpoint allows the creation of a new project within the company account. It requires a POST request to the specified URL with a JSON body containing the 'name' of the project, which is mandatory, and an optional 'active' status. The request headers can include 'X-Personio-Partner-ID' and 'X-Personio-App-ID' for identification purposes. On success, it returns a JSON object with the project details including its ID, name, active status, and timestamps for creation and last update. If the request fails due to invalid data, such as an empty project name, it returns an error object with relevant messages.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Create an Absence Period

  • ID: post_create_absence_period
  • Operation: write
  • Entities: absence type, absence period, employee
  • Summary: 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.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Create an Attendance

  • ID: post_create_an_attendance
  • Operation: write
  • Entities: attendance period, employee, project
  • Summary: 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.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Create Applications in Personio

  • ID: post_create_applications_in_personio
  • Operation: write
  • Entities: job position, file, application
  • Summary: 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.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Create an Employee

  • ID: post_create_employee
  • Operation: write
  • Entities: department, employee, supervisor
  • Summary: This API endpoint allows for the creation of a new employee in the system. The request requires an employee object in the body with mandatory fields such as email, first_name, and last_name. Optional fields include preferred_name, gender, position, subcompany, department, office, hire_date, weekly_working_hours, status, supervisor_id, and custom_attributes. The response will include the ID of the newly created employee if successful, or an error message if the creation fails.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Create a Time-Off

  • ID: post_create_time_off
  • Operation: write
  • Entities: absence, time off type, employee
  • Summary: 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.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Upload Document for Company Employees

  • ID: post_upload_document_for_company_employees
  • Operation: write
  • Entities: document, employee, category
  • Summary: 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.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Upload Documents to Applications

  • ID: post_upload_documents_to_applications
  • Operation: write
  • Entities: error, document, application
  • Summary: 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.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Updated about 1 month ago