# 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.

## Documentation: Getting started
- [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)

## Documentation: Recruiting
- [Passing applications to Personio](https://developer.personio.de/docs/applications-endpoint.md): Description of the applicant endpoint of the Personio Recruiting API

## Documentation: Shift Planning Integration Guide
- [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: Overview
- [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)

## API Reference: Authentication
- [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…
  - [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.

## API Reference: Webhooks Management API
- [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…
  - [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…
  - [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.
  - [Rotate the webhook's signing secret.](https://developer.personio.de/reference/post_v2-webhooks-id-signing-secret.md): Generates a new active signing secret (or accepts a customer-supplied `value`) and moves the previous active secret into a 7-day retiring grace window. The secret `value` is returned exactly once in…

## API Reference: Document Management
- [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.

## API Reference: Person
- [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…
- [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.

## API Reference: Employment
- [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.

## API Reference: Payroll Integrations API
- [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…
- [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…
- [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…

## API Reference: Organization Management
- [Retrieves an Org Unit.](https://developer.personio.de/reference/getorgunit.md): - Returns the requested Org Unit. - Always includes the `leads` of the Org Unit. An empty array means the Org Unit has no leads. - Supports enriching the response by providing options via query…
- [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…

## API Reference: Legal Entities
- [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…
- [Retrieves a legal entity.](https://developer.personio.de/reference/getlegalentitybyid.md): Returns a legal entity for the provided ID.

## API Reference: Absence Period API
- [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…
  - [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.

## API Reference: Attendances API
- [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…
- [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,…

## API Reference: Recruiting
- [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.  > 📘…
- [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…
- [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.
- [Submit an application.](https://developer.personio.de/reference/post_v2-recruiting-applications.md): Submits a new application for a job position, on behalf of an authenticated OAuth client. Documents must be uploaded first via `POST /v2/recruiting/applications/documents` and referenced here by the…
- [Upload a document.](https://developer.personio.de/reference/post_v2-recruiting-applications-documents.md): Uploads a document to be attached to an application, and returns a file reference (`uuid`, `size`, `mimetype`, `original_filename`, `extension`) that can be used to create or update an application.…
- [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.  > 📘…
- [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…
- [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.
- [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.
- [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.
- [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.

## API Reference: Cost Centers
- [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…

## API Reference: Workplaces
- [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…

## API Reference: Public API - Reporting Engine Service
- [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.

## API Reference: Jobs and Salary Bands
- [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. -…
- [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.…
- [Retrieve a Salary Band.](https://developer.personio.de/reference/getsalaryband.md): - Returns the requested Salary Band. - Requires `personio:salary-bands:read`.

## Changelog
- [Job Application Submission](https://developer.personio.de/changelog/job-application-submission.md)
- [Update of the TLS Certificate](https://developer.personio.de/changelog/update-of-the-tls-certificate.md)
- [Recruiting API is Generally Available](https://developer.personio.de/changelog/recruiting-api-is-generally-available.md)
- [Deprecation of Attendances and Projects V1 Endpoints](https://developer.personio.de/changelog/deprecation-of-attendances-and-projects-v1-endpoints.md)
- [Cost Center, Org Unit and Workplace APIs are Generally Available](https://developer.personio.de/changelog/cost-center-org-unit-and-workplace-apis-are-generally-available.md)
- [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)