# Personio Developer Hub Documentation > Find documentation for the Personio API as well as comprehensive guides for integrating Personio into your existing landscape of tools and services. ## Guides - [Get started with Personio API](https://developer.personio.de/docs/getting-started-with-the-personio-api.md): Welcome to the Personio Developer Hub! Whether you want to build an out-of-the-box integration for the +8000 Personio customers or just for your own team, this guide will help you getting started. - [Marketplace TOS & API Policy](https://developer.personio.de/docs/tos-api-security-1.md) - [For product partners](https://developer.personio.de/docs/ipaas-partner.md) - [Passing applications to Personio](https://developer.personio.de/docs/applications-endpoint.md): Description of the applicant endpoint of the Personio Recruiting API - [Key points for Implementing Shift Planning Integration with Personio HRIS](https://developer.personio.de/docs/key-points-for-implementing-shift-planning-integration-with-personio-hris.md): TL;DR for setting up Shift Planning Integrations with Personio - [Introduction and Prerequisites](https://developer.personio.de/docs/introduction-and-prerequisites.md) - [Initial core data sync](https://developer.personio.de/docs/initial-core-data-sync.md) - [Event-driven data from Personio](https://developer.personio.de/docs/event-driven-data-from-personio.md): Utilizing Personio Webhooks to drive sync efficiency - [Attendance & Absence Events](https://developer.personio.de/docs/attendance-and-absence-events.md) - [Handling Logic for Shift Planning](https://developer.personio.de/docs/handling-logic.md): The flow chart outlines the handling logic for various employee-related scenarios: - [Guidelines on when not to update Personio](https://developer.personio.de/docs/guidelines-on-when-not-to-update-personio.md): This page provides clarity on specific scenarios where updates to Personio are not required. - [Guidelines for syncing information into Personio](https://developer.personio.de/docs/guidelines-for-syncing-information-into-personio.md) ## API Reference - [Introduction](https://developer.personio.de/reference/introduction.md) - [Include our headers in your requests](https://developer.personio.de/reference/include-our-headers-in-your-requests.md) - [Authentication](https://developer.personio.de/reference/authentication.md) - [Obtain Access Token](https://developer.personio.de/reference/post_v2-auth-token.md): Endpoint to obtain an OAuth 2.0 access token using the Client Credentials Grant. Clients authenticate with their ID and secret, receiving an access token for resource access. The request must be formatted using the `application/x-www-form-urlencoded` media type. - [Revoke Access Token](https://developer.personio.de/reference/post_v2-auth-revoke.md): Endpoint to revoke provided access token. The request must be formatted using the `application/x-www-form-urlencoded` media type. - [Webhooks](https://developer.personio.de/reference/webhooks.md) - [List webhooks.](https://developer.personio.de/reference/get_v2-webhooks.md): Returns a list of webhooks. This endpoint requires the `personio:webhooks:read` scope. - [Create new webhook.](https://developer.personio.de/reference/post_v2-webhooks.md): Create a new webhook. This endpoint requires the `personio:webhooks:write` scope. - [Get a webhook.](https://developer.personio.de/reference/get_v2-webhooks-id.md): Get a webhook. This endpoint requires the `personio:webhooks:read` scope. - [Update a webhook.](https://developer.personio.de/reference/patch_v2-webhooks-id.md): Update a webhook. This endpoint requires the `personio:webhooks:write` scope. - [Delete a webhook.](https://developer.personio.de/reference/delete_v2-webhooks-id.md): Delete a webhook. This endpoint requires the `personio:webhooks:write` scope. - [Get webhook delivery activity.](https://developer.personio.de/reference/get_v2-webhooks-id-activity.md): Returns delivery activity for a specific webhook. Only activities in the last 30 days will be included. This endpoint requires the `personio:webhooks:read` scope. - [Get webhook events.](https://developer.personio.de/reference/get_v2-webhooks-id-events.md): Returns events for a specific webhook. Only events in the last 30 days will be included. This endpoint requires the `personio:webhooks:read` scope. - [Redeliver events for a webhook.](https://developer.personio.de/reference/post_v2-webhooks-id-redelivery.md): Redelivers events selected by the request parameters. Only events from the last 30 days can be redelivered. At least one of the `occurred_at.lte` or `occurred_at.gte` fields must be provided in the request body. A maximum of 100 events will be redelivered per request. Limited to 500 events every hour. This endpoint requires the `personio:webhooks:write` scope. - [Send a ping event.](https://developer.personio.de/reference/post_v2-webhooks-id-ping.md): Use this endpoint to trigger a test event of type `ping` for a specific webhook. This allows to verify that the webhook is configured correctly and can receive events. Requires the `personio:webhooks:write` scope. - [Send a test event with custom payload.](https://developer.personio.de/reference/post_v2-webhooks-id-test-event.md): Triggers a test event with a specific event type and custom payload data for a webhook. The event must be enabled for the webhook. Requires the `personio:webhooks:write` scope. - [Document Management](https://developer.personio.de/reference/document-management.md) - [List document metadata.](https://developer.personio.de/reference/get_v2-document-management-documents.md): Lists the metadata of Documents belonging to the provided owner ID. - [Update document metadata.](https://developer.personio.de/reference/patch_v2-document-management-documents-document-id.md): Updates the metadata of the Document with the provided Document ID. - [Delete document.](https://developer.personio.de/reference/delete_v2-document-management-documents-document-id.md): Deletes the Document with the provided Document ID. - [Download document file.](https://developer.personio.de/reference/get_v2-document-management-documents-document-id-download.md): Downloads the file associated with the provided Document ID. - [List persons.](https://developer.personio.de/reference/get_v2-persons.md): - This endpoint returns a list of persons. - The endpoint supports pagination and filtering based on various parameters such as id, first_name, last_name, created_at, and updated_at. - Filters are combined using the logical "AND" operator, which requires that all conditions be true for the output to be included. - The endpoint requires the personio:persons:read scope. - [Retrieve a person.](https://developer.personio.de/reference/get_v2-persons-id.md): This endpoint returns a specific person identified by the ID parameter. The endpoint requires the personio:persons:read scope. - [Create a new Person and Employment.](https://developer.personio.de/reference/post_v2-persons.md): - This endpoint enables the creation of a Person resource and an associated Employment resource. - The endpoint requires the personio:persons:write scope. - [Update a Person.](https://developer.personio.de/reference/patch_v2-persons-person-id.md): - This endpoint enables the update of a Person resource. - The endpoint requires the personio:persons:write scope. - [Delete a Person.](https://developer.personio.de/reference/delete_v2-persons-person-id.md): - This endpoint enables the deletion of a Person resource. - The endpoint requires the personio:persons:write scope. - [List employments of a given Person.](https://developer.personio.de/reference/get_v2-persons-person-id-employments.md): Returns a list of employments of a given person. The employments are returned in sorted order, with the most recent employments appearing first. - [Retrieve an employment.](https://developer.personio.de/reference/get_v2-persons-person-id-employments-id.md): Retrieves an employment for the provided ID. - [Update an Employment.](https://developer.personio.de/reference/patch_v2-persons-person-id-employments-employment-id.md): - This endpoint enables the update of an Employment resource. - The endpoint requires the personio:persons:write scope. - [List compensations.](https://developer.personio.de/reference/get_v2-compensations.md): Returns a list of payroll compensations of people for an authorized company. Compensations listed include base salary (excluding proration), hourly, one time compensation, recurring compensation, and bonuses. - [Create Compensation.](https://developer.personio.de/reference/post_v2-compensations.md): **Requires credential with both `personio:compensations:read` and `personio:compensations:write` scopes.** Creates a compensation for people for an authorized company. Compensation types supported include one time, recurring, fixed, and hourly. Bonuses are not supported. - [List Compensation Types.](https://developer.personio.de/reference/get_v2-compensations-types.md): Returns a list of Compensation Types for an authorized company. The types include one-time and recurring Compensation Types. Bonuses should use recurring or one time types. - [Create Compensation Types.](https://developer.personio.de/reference/post_v2-compensations-types.md): Creates a new Compensation Type and returns the created resource with its UUID. This UUID can be used to create a new compensation. The types include one-time and recurring Compensation Types for salary workers. Hourly types are not supported and bonuses should use recurring or one time types. - [Retrieves an Org Unit.](https://developer.personio.de/reference/getorgunit.md): - Returns the requested Org Unit. - Supports enriching the response by providing options via query params, e.g. include_ancestors. - [Lists Org Units.](https://developer.personio.de/reference/listorgunits.md): Returns a paginated list of Org Units for the authenticated company. - Use the `type` parameter to filter by Org Unit type (e.g. `department` or `team`). - Use `limit` and `cursor` to paginate through large result sets. - Use `sort` to control the order of results by `name` or `id`, in ascending or descending order. - Optionally include the ancestor chain for each Org Unit by setting `include_parent_chain=true`. - Note: This endpoint is in beta mode. Please use the discussion page in the Developer Hub for feedback. - [List legal entities.](https://developer.personio.de/reference/listlegalentities.md): - Returns a list of existing legal entities for an authorized company. The legal entities are returned sorted by their creation date, with the most recent appearing first. - If no legal entity can be found for the relevant company the endpoint will return an empty response. - The endpoint supports filtering legal entities by country and ID. - [Retrieves a legal entity.](https://developer.personio.de/reference/getlegalentitybyid.md): Returns a legal entity for the provided ID. - [Absence Periods](https://developer.personio.de/reference/absence-periods.md): Explanation of starts_from and ends_at objects - [Retrieves an absence period by ID.](https://developer.personio.de/reference/get_v2-absence-periods-id.md): Retrieves an absence period by ID. - [Deletes an absence period by ID.](https://developer.personio.de/reference/delete_v2-absence-periods-id.md): Deletes an absence period by ID. - [Updates an absence period by ID.](https://developer.personio.de/reference/patch_v2-absence-periods-id.md): Updates an absence period by ID. - [List absence periods.](https://developer.personio.de/reference/get_v2-absence-periods.md): - This endpoint returns a list of absence periods. - It supports pagination and filtering based on various parameters. - Filters are combined using the logical "AND" operator, which requires that all conditions be true for the output to be included - except when filtering by date ranges, as in this case it'll match absences overlapping the provided period. - This endpoint requires the personio:absences:read scope. - [Creates a new absence period.](https://developer.personio.de/reference/post_v2-absence-periods.md): Creates a new absence period. - [Retrieves daily absence period breakdowns for a given absence period.](https://developer.personio.de/reference/get_v2-absence-periods-id-breakdowns.md): Retrieves daily absence period breakdowns for a given absence period. - [Retrieves an absence type by ID.](https://developer.personio.de/reference/get_v2-absence-types-id.md): Retrieves an absence type by ID. - [List absence types.](https://developer.personio.de/reference/get_v2-absence-types.md): List absence type. - [Get an attendance period.](https://developer.personio.de/reference/get_v2-attendance-periods-id.md): - Retrieves an attendance period by given attendance period ID. - [Delete an attendance period by ID.](https://developer.personio.de/reference/delete_v2-attendance-periods-id.md): Deletes an attendance period by ID. - [Update an attendance period.](https://developer.personio.de/reference/patch_v2-attendance-periods-id.md): Update an attendance period by given attendance period ID and return the attendance period ID. - [List attendance periods.](https://developer.personio.de/reference/get_v2-attendance-periods.md): List attendance periods by given filters. - [Create an attendance period.](https://developer.personio.de/reference/post_v2-attendance-periods.md): Create an attendance period and return newly created attendance period ID. - [List Projects](https://developer.personio.de/reference/get_v2-projects.md): List all projects by given filters. - [Create a project.](https://developer.personio.de/reference/post_v2-projects.md): Create a project and return the newly created project ID. - [Get a Project.](https://developer.personio.de/reference/get_v2-projects-id.md): Retrieves a project by given project ID. - [Update a Project.](https://developer.personio.de/reference/patch_v2-projects-id.md): Update a project by given project ID. - [Delete a Project.](https://developer.personio.de/reference/delete_v2-projects-id.md): Delete a project by given project ID. All its sub projects will be deleted as well. If the project or any of its sub projects have attendances, the request will fail with a 422 response. - [List Project Members](https://developer.personio.de/reference/get_v2-projects-id-members.md): List all project members by given project ID. - [Add Project Members](https://developer.personio.de/reference/post_v2-projects-id-members.md): Adds a list of project members to a project. When the project is already assigned to all employees, it will be converted to a project with members. (`assigned_to_all` will be set to false) If the person is already a member of the project, the request is a no-op. If any of the person IDs are invalid, the entire request will fail with a 422 response. Subprojects can't have members. Trying to add members to a subproject will fail with a 422 response. - [Remove Project Members](https://developer.personio.de/reference/delete_v2-projects-id-members.md): Remove project members from a project. If no person ID is provided, all members are removed. If a person ID is provided, only that member is removed. If the person ID is not a member of the project, the request is a no-op. Subprojects can't have members. Trying to remove members from a subproject will fail with a 422 response. - [List all applications.](https://developer.personio.de/reference/get_v2-recruiting-applications.md): Returns a list of applications for an authorized company, sorted by last updated date, newest first. The endpoint supports pagination. The endpoint requires the `personio:recruiting:read` scope. > 📘 Note > > Currently, the Candidates and Applications API does not return custom attributes and tags. > Please consider this limitation when using the API. > 🚧 Warning > > This endpoint is in beta, and may be subject to change. > Please report any bugs to [Help & Feedback](https://support.personio.de/hc/en-us/articles/5659436229277-Help-Feedback) section. - [Retrieve an application by ID.](https://developer.personio.de/reference/get_v2-recruiting-applications-id.md): Retrieves an application for the provided application ID. The endpoint requires the `personio:recruiting:read` scope. > 📘 Note > > Currently, the Candidates and Applications API does not return custom attributes and tags. > Please consider this limitation when using the API. > 🚧 Warning > > This endpoint is in beta, and may be subject to change. > Please report any bugs to [Help & Feedback](https://support.personio.de/hc/en-us/articles/5659436229277-Help-Feedback) section. - [List all application stage transitions for an application ID.](https://developer.personio.de/reference/get_v2-recruiting-applications-id-stage-transitions.md): Returns a list of application stage transitions, ordered by latest-first for the provided application ID. The endpoint requires the `personio:recruiting:read` scope. > 🚧 Warning > > This endpoint is in beta, and may be subject to change. > Please report any bugs to [Help & Feedback](https://support.personio.de/hc/en-us/articles/5659436229277-Help-Feedback) section. - [List all candidates.](https://developer.personio.de/reference/get_v2-recruiting-candidates.md): Returns a list of candidates for an authorized company, sorted by last updated date, newest first. The endpoint supports pagination. The endpoint requires the `personio:recruiting:read` scope. > 📘 Note > > Currently, the Candidates and Applications API does not return custom attributes and tags. > Please consider this limitation when using the API. > 🚧 Warning > > This endpoint is in beta, and may be subject to change. > Please report any bugs to [Help & Feedback](https://support.personio.de/hc/en-us/articles/5659436229277-Help-Feedback) section. - [Retrieve a candidate by ID.](https://developer.personio.de/reference/get_v2-recruiting-candidates-id.md): Returns a candidate for the provided ID. The endpoint requires the `personio:recruiting:read` scope. > 📘 Note > > Currently, the Candidates and Applications API does not return custom attributes and tags. > Please consider this limitation when using the API. > 🚧 Warning > > This endpoint is in beta, and may be subject to change. > Please report any bugs to [Help & Feedback](https://support.personio.de/hc/en-us/articles/5659436229277-Help-Feedback) section. - [List all jobs.](https://developer.personio.de/reference/get_v2-recruiting-jobs.md): Returns a list of jobs for an authorized company, sorted by last updated date, newest first. The endpoint supports pagination. The endpoint requires the `personio:recruiting:read` scope. > 🚧 Warning > > This endpoint is in beta, and may be subject to change. > Please report any bugs to [Help & Feedback](https://support.personio.de/hc/en-us/articles/5659436229277-Help-Feedback) section. - [Retrieve an job by ID.](https://developer.personio.de/reference/get_v2-recruiting-jobs-id.md): Retrieves an job for the provided job ID. The endpoint requires the `personio:recruiting:read` scope. > 🚧 Warning > > This endpoint is in beta, and may be subject to change. > Please report any bugs to [Help & Feedback](https://support.personio.de/hc/en-us/articles/5659436229277-Help-Feedback) section. - [List all job categories.](https://developer.personio.de/reference/get_v2-recruiting-categories.md): Returns a list of job categories for an authorized company. The endpoint requires the `personio:recruiting:read` scope. > 🚧 Warning > > This endpoint is in beta, and may be subject to change. > Please report any bugs to [Help & Feedback](https://support.personio.de/hc/en-us/articles/5659436229277-Help-Feedback) section. - [Retrieve a job category by its ID.](https://developer.personio.de/reference/get_v2-recruiting-categories-id.md): Retrieves a job category for the provided category ID. The endpoint requires the `personio:recruiting:read` scope. > 🚧 Warning > > This endpoint is in beta, and may be subject to change. > Please report any bugs to [Help & Feedback](https://support.personio.de/hc/en-us/articles/5659436229277-Help-Feedback) section. - [List cost centers.](https://developer.personio.de/reference/listcostcenters.md): - Returns a list of existing cost centers for an authorized company. - Supports pagination using the `cursor` and `limit` query parameters. - Supports filtering cost centers by `name` and `id` query parameters. - Supports sorting cost centers by `name` and `id` using the `sort` query parameter. - Default sort is by `id` in ascending order. - Note: This endpoint is in beta mode. Please use the discussion page in the Developer Hub for feedback. - [List all workplaces.](https://developer.personio.de/reference/listworkplaces.md): - Returns a list of existing workplaces for an authorized company. - Supports pagination using the `cursor` and `limit` query parameters. - Supports filtering workplaces by `name` and `id` query parameters. - Supports sorting workplaces by `name` and `id` using the `sort` query parameter. - Default sort is by `id` in ascending order. - Note: This endpoint is in beta mode. Please use the discussion page in the Developer Hub for feedback. - [Lists all report attributes for a company.](https://developer.personio.de/reference/listreportsattributes.md): Returns a list of the reports company attributes. The attributes response also contains the attribute details, such as type, display, filtering, etc. - [Lists all reports for a company.](https://developer.personio.de/reference/listcompanyreports.md): Returns a list of reports available for the company. The reports are returned in a sorted order, with the most recent appearing first. - [Retrieves a report.](https://developer.personio.de/reference/getreport.md): Retrieves a report for the provided ID. - [List jobs.](https://developer.personio.de/reference/listjobs.md): - Returns a list of existing Jobs for an authorized company. - Supports pagination using the `cursor` and `limit` query parameters. - Supports filtering Jobs by `name` and `ID` query parameters. - Supports sorting Jobs by `name` and `ID` using the `sort` query parameter. - Default sort is by `ID` in descending order. - Requires `personio:jobs:read`. - [Retrieves a Job.](https://developer.personio.de/reference/getjob.md): - Returns the requested Job. - Requires `personio:jobs:read`. - [List salary bands.](https://developer.personio.de/reference/listsalarybands.md): - Returns a list of existing Salary Bands for an authorized company. - Supports pagination using the `cursor` and `limit` query parameters. - Supports filtering Salary Bands by `id` query parameter. - Requires `personio:salary-bands:read`. - [Retrieve a Salary Band.](https://developer.personio.de/reference/getsalaryband.md): - Returns the requested Salary Band. - Requires `personio:salary-bands:read`. ## Changelog - [created_at field in GET /v2/document-management/documents will return UTC](https://developer.personio.de/changelog/created_at-field-in-get-v2document-managementdocuments-will-return-utc.md) - [Jobs and Salary Bands Available](https://developer.personio.de/changelog/jobs-and-salary-bands-available.md) - [Job reference now available on Employment](https://developer.personio.de/changelog/job-reference-now-available-on-employment.md) - [Deprecated: query-string credentials on `POST /v1/auth`](https://developer.personio.de/changelog/deprecated-query-string-credentials-on-post-v1auth.md) - [Status filter in list persons endpoint](https://developer.personio.de/changelog/status-filter-in-list-persons-endpoint.md)