# Personio Developer Hub Documentation

## 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
- [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:
- [Event-driven data from Personio](https://developer.personio.de/docs/event-driven-data-from-personio.md): Utilizing Personio Webhooks to drive sync efficiency
- [Guidelines for syncing information into Personio](https://developer.personio.de/docs/guidelines-for-syncing-information-into-personio.md)
- [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.
- [Initial core data sync](https://developer.personio.de/docs/initial-core-data-sync.md)
- [Introduction and Prerequisites](https://developer.personio.de/docs/introduction-and-prerequisites.md)
- [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

## API Reference
- [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.
- [Deletes an absence period by ID.](https://developer.personio.de/reference/delete_v2-absence-periods-id.md): Deletes an absence period by ID.
- [Retrieves an absence period by ID.](https://developer.personio.de/reference/get_v2-absence-periods-id.md): Retrieves 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.
- [Absence Periods](https://developer.personio.de/reference/absence-periods.md): Explanation of starts_from and ends_at objects
- [Updates an absence period by ID.](https://developer.personio.de/reference/patch_v2-absence-periods-id.md): Updates an absence period by ID.
- [Creates a new absence period.](https://developer.personio.de/reference/post_v2-absence-periods.md): Creates a new 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.
- [Delete an attendance period by ID.](https://developer.personio.de/reference/delete_v2-attendance-periods-id.md): Deletes an attendance period by ID.
- [Get an attendance period.](https://developer.personio.de/reference/get_v2-attendance-periods-id.md): - Retrieves an attendance period by given attendance period ID.
- [List attendance periods.](https://developer.personio.de/reference/get_v2-attendance-periods.md): List attendance periods by given filters.
- [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.
- [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.
- [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 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.
- [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.
- [Get a Project.](https://developer.personio.de/reference/get_v2-projects-id.md): Retrieves a project by given project ID.
- [List Projects](https://developer.personio.de/reference/get_v2-projects.md): List all projects by given filters.
- [Update a Project.](https://developer.personio.de/reference/patch_v2-projects-id.md): Update a project by given project ID.
- [Create a project.](https://developer.personio.de/reference/post_v2-projects.md): Create a project and return the newly created project ID.
- [Authentication](https://developer.personio.de/reference/authentication.md)
- [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.
- [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.
- [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.
- [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 document metadata.](https://developer.personio.de/reference/get_v2-document-management-documents.md): Lists the metadata of Documents belonging to the provided owner ID.
- [Document Management](https://developer.personio.de/reference/document-management.md)
- [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.
- [Retrieve an employment.](https://developer.personio.de/reference/get_v2-persons-person-id-employments-id.md): Retrieves an employment for the provided ID.
- [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.
- [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.
- [Retrieves a Job.](https://developer.personio.de/reference/getjob.md): - Returns the requested Job. - Requires `personio:jobs:read`.
- [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`.
- [Retrieve a Salary Band.](https://developer.personio.de/reference/getsalaryband.md): - Returns the requested Salary Band. - Requires `personio:salary-bands: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`.
- [Retrieves a legal entity.](https://developer.personio.de/reference/getlegalentitybyid.md): Returns a legal entity for the provided ID.
- [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 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.
- [Include our headers in your requests](https://developer.personio.de/reference/include-our-headers-in-your-requests.md)
- [Introduction](https://developer.personio.de/reference/introduction.md)
- [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.
- [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 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.
- [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.
- [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.
- [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.
- [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.
- [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.
- [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.
- [Retrieves a report.](https://developer.personio.de/reference/getreport.md): Retrieves a report for the provided ID.
- [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.
- [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.
- [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.
- [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 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 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 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 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 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 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 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.
- [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.
- [Get a webhook.](https://developer.personio.de/reference/get_v2-webhooks-id.md): Get a webhook. This endpoint requires the `personio:webhooks:read` scope.
- [List webhooks.](https://developer.personio.de/reference/get_v2-webhooks.md): Returns a list of webhooks. This endpoint requires the `personio:webhooks:read` scope.
- [Webhooks](https://developer.personio.de/reference/webhooks.md)
- [Update a webhook.](https://developer.personio.de/reference/patch_v2-webhooks-id.md): Update a webhook. 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.
- [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 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.
- [Create new webhook.](https://developer.personio.de/reference/post_v2-webhooks.md): Create a new webhook. This endpoint requires the `personio:webhooks:write` scope.
- [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.

## Changelog
- [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)
- [Reporting API V2 Endpoints](https://developer.personio.de/changelog/reporting-api-v2-endpoints.md)