Personnel Data

HR management and recruiting platform

developer.personio.de/reference ↗

Version

1.0

OpenAPI

3.0.0

Endpoints

Schemas

110

84

Quality

Updated

3 days ago

Hr hr recruiting management

Use this API in your AI agent

Query structured spec data via REST or MCP. Get exactly what your agent needs.

Get API Key

Server URLs

https://api.personio.de/v1

Endpoints

GET POST PUT PATCH DELETE

Absences 8 endpoints

GET /company/absence-periods

Fetches absence periods for absences with time unit set to hours. The result can be paginated and filtered by period and/or specific employee/employees. The result contains a list of hourly absence periods.

operationId: Absences_getHourlyPeriods

Parameters

Name	In	Required	Type	Description
X-Personio-Partner-ID	header	optional	string	The partner identifier
X-Personio-App-ID	header	optional	string	The application identifier
start_date	query	optional	string	Filter by absence periods that start at or before given date.
end_date	query	optional	string	Filter by absence periods that start at or before given date.
updated_from	query	optional	string	Filter by periods that were created or modified from the date updated_from. It is inclusive, so all the periods created or modified from the beginning of the updated_from will be included in the results.
updated_to	query	optional	string	Filter by periods that were created or modified until the date updated_to. It is inclusive, so all the periods created or modified until the end of the updated_to will be included in the results.
employees[]	query	optional	array	A list of Personio employee ID’s to filter the results. The result filters including only absences of provided employees
absence_types[]	query	optional	array	A list of Personio absence type IDs to filter the results. The result filters including only absences of provided absence types.
absence_periods[]	query	optional	array	A list of Personio absence period IDs to filter the results. The result filters including only absences containing the provided ids.
limit	query	optional	integer	Pagination attribute to limit how many absence periods are returned per page.
offset	query	optional	integer	Pagination attribute to identify which page you are requesting, by the form of telling an offset from the first record that would be returned.

Responses

200 —

400

Bad request

500

Internal server error

GET /company/absence-periods

POST /company/absence-periods

Adds absence data for absence types with time unit set to hours. Note that creating periods for absence types with certificate requirement enabled is not supported!

operationId: Absences_addAbsencePeriodsData

Parameters

Name	In	Required	Type	Description
X-Personio-Partner-ID	header	optional	string	The partner identifier
X-Personio-App-ID	header	optional	string	The application identifier

Request Body

required

Absence data

application/x-www-form-urlencoded

schema CreateAbsencePeriodRequest

Property	Type	Required
comment	string	optional
end_date	string	required
end_time	string	optional
start_date	string	required
start_time	string	optional
employee_id	integer	required
half_day_end	boolean	optional
skip_approval	boolean	optional
half_day_start	boolean	optional
time_off_type_id	integer	required

Responses

201

The absence period was successfully created

400

Invalid request

404

Employee or Absence type not found

422

Validation error

500

Internal server error

POST /company/absence-periods

DELETE /company/absence-periods/{id}

Deletes absence period data for absence types with time unit set to hours.

operationId: Absences_deletePeriodData

Parameters

Name	In	Required	Type	Description
X-Personio-Partner-ID	header	optional	string	The partner identifier
X-Personio-App-ID	header	optional	string	The application identifier
id	path	required	string	ID of the absence period to delete

Responses

200

Success response

400

Bad request response

404

Not found response

DELETE /company/absence-periods/{id}

GET /company/time-off-types

Provides a list of absence types for absences time unit set to either days or hours. For example ‘Paid vacation’, ‘Parental leave’ or ‘Home office’.

operationId: Absences_listTimeOffTypes

Parameters

Name	In	Required	Type	Description
X-Personio-Partner-ID	header	optional	string	The partner identifier
X-Personio-App-ID	header	optional	string	The application identifier
limit	query	optional	integer	Pagination attribute to limit how many records will be returned per page
offset	query	optional	integer	Pagination attribute to identify which page you are requesting, by the form of telling an offset from the first record that would be returned.

Responses

200 —

GET /company/time-off-types

GET /company/time-offs

Fetches absence periods for absences with time unit set to days. The result can be paginated and filtered by period and/or specific employee/employees. The result contains a list of absence periods.

operationId: Absences_getAbsencePeriods

Parameters

Name	In	Required	Type	Description
X-Personio-Partner-ID	header	optional	string	The partner identifier
X-Personio-App-ID	header	optional	string	The application identifier
start_date	query	optional	string	First day of the period to be queried. It is inclusive, so the result starts from and including the provided `start_date`
end_date	query	optional	string	Last day of the period to be queried. It is inclusive, so the result ends on `end_date` including absences from the `end_date`
updated_from	query	optional	string	Query the periods that created or modified from the date `updated_from`. It is inclusive, so all the periods created or modified from the beginning of the `updated_from` will be included in the results
updated_to	query	optional	string	Query the periods that created or modified until the date `updated_to`. It is inclusive, so all the periods created or modified until the end of the `updated_to` will be included in the results
employees[]	query	optional	array	A list of Personio employee ID’s to filter the results. The result filters including only absences of provided employees
limit	query	optional	integer	Pagination attribute to limit the number of absence periods per page
offset	query	optional	integer	Pagination attribute to identify which page number you are requesting

Responses

200 —

GET /company/time-offs

POST /company/time-offs

Adds absence data for absence types with time unit set to days.

operationId: Absences_addAbsenceData

Parameters

Name	In	Required	Type	Description
X-Personio-Partner-ID	header	optional	string	The partner identifier
X-Personio-App-ID	header	optional	string	The application identifier

Request Body

required

Absence data

application/x-www-form-urlencoded

schema CreateTimeOffPeriodRequest

Property	Type	Required
comment	string	optional
end_date	string	required
start_date	string	required
employee_id	integer	required
half_day_end	boolean	required
skip_approval	boolean	optional
half_day_start	boolean	required
time_off_type_id	integer	required

Responses

200

The absence period is successfully created

400

Invalid request

404

Employee or Absence type not found

422

Validation error

POST /company/time-offs

DELETE /company/time-offs/{id}

Deletes absence period data for absence types with time unit set to days.

operationId: Absences_deleteAbsenceData

Parameters

Name	In	Required	Type	Description
X-Personio-Partner-ID	header	optional	string	The partner identifier
X-Personio-App-ID	header	optional	string	The application identifier
id	path	required	integer	ID of the absence period to delete

Responses

200

Success response

400

Bad request response

404

Not found response

DELETE /company/time-offs/{id}

GET /company/time-offs/{id}

Gets an absence period for absences with time unit set to days.

operationId: Absences_getAbsencePeriod

Parameters

Name	In	Required	Type	Description
X-Personio-Partner-ID	header	optional	string	The partner identifier
X-Personio-App-ID	header	optional	string	The application identifier
id	path	required	integer	Numeric `id` of the absence period

Responses

200 —

404

Not found response

GET /company/time-offs/{id}

Attendances 4 endpoints

GET /company/attendances

Fetch attendance data for the company employees. The result can be paginated and filtered by period, the date and/or time they were updated, and/or specific employee/employees. The result contains a list of attendances.

operationId: Attendances_getList

Parameters

Name	In	Required	Type	Description
X-Personio-Partner-ID	header	optional	string	The partner identifier
X-Personio-App-ID	header	optional	string	The application identifier
start_date	query	required	string	First day of the period to be queried. It is inclusive, so the day specified as start_date will also be considered on the results
end_date	query	required	string	Last day of the period to be queried. It is inclusive, so the day specified as end_date will also be considered on the results.
updated_from	query	optional	string	Datetime from when the queried periods have been updated. Same format as updated_at. It is inclusive, so the day specified as updated_from will also be considered on the results. Can be just the date, or the date and the time, with or without the timezone.
updated_to	query	optional	string	Datetime until when the queried periods have been updated. Same format as updated_at. It is inclusive, so the day specified as updated_to will also be considered on the results. Can be just the date, or the date and the time, with or without the timezone.
includePending	query	optional	boolean	Returns AttendancePeriods with a status of pending, rejected and confirmed. For pending periods, the end_date attribute is nullable. The status of each period is included in the response.
employees[]	query	optional	array	A list of Personio employee ID’s to filter the results. The result filters including only attendances of provided employees.
limit	query	optional	integer	Pagination attribute to limit how many attendances are per page
offset	query	optional	integer	The offset from the first record that would be returned. With 3 results [A, B, C] and an offset of 1, the following two results will be returned [B, C].

Responses

200

The Attendance periods matching the provided filters

401

Unauthorized Access

403

Forbidden Access

GET /company/attendances

POST /company/attendances

This endpoint is responsible for adding attendance data for the company employees. It is possible to add attendances for one or many employees at the same time. The payload sent on the request should be a list of attendance periods, in the form of an array containing attendance period objects.

operationId: Attendances_createMultipleAttendances

Parameters

Name	In	Required	Type	Description
X-Personio-Partner-ID	header	optional	string	The partner identifier
X-Personio-App-ID	header	optional	string	The application identifier

Request Body

required

List of attendance periods to create

application/json

schema AttendanceCreateRequest

Property	Type	Required
attendances	array	optional
└ date	string	required
└ break	integer	required
└ comment	string	optional
└ employee	integer	required
└ end_time	string	optional
└ project_id	integer	optional
└ start_time	string	required
skip_approval	boolean	optional

application/x-www-form-urlencoded

schema NewAttendancePeriodParametersRequest

Property	Type	Required
project_id	integer	optional
skip_approval	boolean	optional
attendances[]break	integer	required
attendances[][date]	string	required
attendances[][comment]	string	optional
attendances[][employee]	integer	required
attendances[][end_time]	string	optional
attendances[][start_time]	string	required

Responses

200

The attendance periods are successfully created

400

Invalid request

401

Unauthorized Access

403

Forbidden Access

POST /company/attendances

DELETE /company/attendances/{id}

This endpoint is responsible for deleting attendance data for the company employees.

operationId: Attendances_deleteData

Parameters

Name	In	Required	Type	Description
X-Personio-Partner-ID	header	optional	string	The partner identifier
X-Personio-App-ID	header	optional	string	The application identifier
id	path	required	integer	ID of the attendance period to delete
skip_approval	query	optional	boolean	Optional, default value is true. If set to false, the approval status of the attendance period will be “pending” if an approval rule is set for the attendances type. The respective approval flow will be triggered.

Responses

200

Success response

400

Bad Request

401

Unauthorized Access

403

Forbidden Access

404

Not Found

DELETE /company/attendances/{id}

PATCH /company/attendances/{id}

This endpoint is responsible for updating attendance data for the company employees. Attributes are not required and if not specified, the current value will be used. It is not possible to change the employee id.

operationId: Attendances_updateAttendanceData

Parameters

Name	In	Required	Type	Description
X-Personio-Partner-ID	header	optional	string	The partner identifier
X-Personio-App-ID	header	optional	string	The application identifier
id	path	required	integer	ID of the attendance period to update

Request Body

required

Attendance period data to update. At least one of the properties (date, start_time, end_time, break, comment, project_id, skip_approval) is required.

application/json

schema AttendanceUpdateRequest

Property	Type	Required
date	string	optional
break	integer	optional
comment	string	optional
end_time	string	optional
project_id	integer	optional
start_time	string	optional
skip_approval	boolean	optional

Responses

200

Success response

400

Bad Request

401

Unauthorized Access

403

Forbidden Access

404

Not found response

PATCH /company/attendances/{id}

Customreports 3 endpoints

GET /company/custom-reports/columns

This endpoint provides human-readable labels for report table columns. It is particularly important if you get a report with custom attributes or absence data to match the column IDs to the translation.

operationId: CustomReports_getColumnLabels

Parameters

Name	In	Required	Type	Description
X-Personio-Partner-ID	header	optional	string	The partner identifier
X-Personio-App-ID	header	optional	string	The application identifier
columns	query	optional	array	The columns to filter the results.
locale	query	optional	string	locale used to translate localized fields.
report_id	query	optional	string	The ID of the report to filter the result of the columns. If no ID is passed, all columns for the company are returned.

Responses

200

500

Internal Server Error

GET /company/custom-reports/columns

GET /company/custom-reports/reports

This endpoint provides you with metadata about existing custom reports in your Personio account, such as report name, report type, report date / timeframe.

operationId: CustomReports_getMetadata

Parameters

Name	In	Required	Type	Description
X-Personio-Partner-ID	header	optional	string	The partner identifier
X-Personio-App-ID	header	optional	string	The application identifier
report_ids	query	optional	array	A list of report ID’s to filter the results.
status	query	optional	string	The status of the report to filter the results.

Responses

200

500

Internal Server Error

GET /company/custom-reports/reports

GET /company/custom-reports/reports/{report_id}

This endpoint provides you with the data of an existing Custom Report.

operationId: CustomReports_getData

Parameters

Name	In	Required	Type	Description
X-Personio-Partner-ID	header	optional	string	The partner identifier
X-Personio-App-ID	header	optional	string	The application identifier
report_id	path	required	string	The ID of the report to filter the result.
locale	query	optional	string	locale used to translate localized fields.
page	query	optional	integer	Pagination parameter to identify the page to return.
limit	query	optional	integer	Pagination parameter to limit the number of employees returned per page.

Responses

200

400

Bad request

404

Report not found

500

Internal Server Error

GET /company/custom-reports/reports/{report_id}

Documents 2 endpoints

GET /company/document-categories

This endpoint is responsible for fetching all document categories of the company. The result contains a list of document categories.

operationId: Documents_getCategories

Parameters

Name	In	Required	Type	Description
X-Personio-Partner-ID	header	optional	string	The partner identifier
X-Personio-App-ID	header	optional	string	The application identifier

Responses

200 —

GET /company/document-categories

POST /company/documents

This endpoint is responsible for uploading documents for the company employees.

operationId: Documents_uploadForEmployees

Parameters

Name	In	Required	Type	Description
X-Personio-Partner-ID	header	optional	string	The partner identifier
X-Personio-App-ID	header	optional	string	The application identifier

Request Body

Data necessary for document upload.

multipart/form-data

schema DocumentUploadRequest

Property	Type	Required
date	string	optional
file	string	required
title	string	required
comment	string	optional
category_id	integer	required
employee_id	integer	required

Responses

201

The document was successfully uploaded to the employees profile

404

This status code is returned if the provided employee_id or category_id are not found within the company.

422

This status code is returned if the provided request parameters cannot be processed or if the parameters are invalid.

POST /company/documents

Employees 8 endpoints

GET /company/employees

List Company Employees

operationId: Employees_getList

Parameters

Name	In	Required	Type	Description
X-Personio-Partner-ID	header	optional	string	The partner identifier
X-Personio-App-ID	header	optional	string	The application identifier
limit	query	optional	integer	Pagination attribute to limit the number of employees returned per page.
offset	query	optional	integer	Pagination attribute to identify the first item in the collection to return.
email	query	optional	string	Find an employee with the given email address. The response is still a list, containing only the filtered employee. NOTE: when using the updated_since filter, the email filter is ignored.
attributes[]	query	optional	array	A list of attributes that will be returned for the employees, ie. a projection of the employee fields and relationships. In case `updated_since` query parameter is used, this list will additionally be used to exclude the employees that had none of the provided `attributes[]` updated since `updated_since`, ie. a selection filter.
updated_since	query	optional	string	Filter to select and return only the employees that have been updated after `updated_since`. When it is used together with the `attributes[]` query parameter, the filter will select only the employees that have had any of the provided `attributes[]` updated since `updated_since`. The format is `ISO 8601` (2022-12-24T08:15:30). NOTE: when using the `updated_since` filter, the `email`, `limit`, and `offset` parameters are ignored. Examples with `updated_since` and `attributes[]`: In an example company that has 17 employees: `?updated_since=2022-12-24T08:15:30` will yield 10 employees that were recently updated: { "success": true, "metadata": { "total_elements": 10, "current_page": 0, "total_pages": 10 }, "offset": 0, "limit": 1, "data": [ { "type": "Employee", "attributes": { "id": { "label": "ID", "value": 1, "type": "integer", "universal_id": "id" }, "first_name": { "label": "First name", "value": "Alexander", "type": "standard", "universal_id": "first_name" }, "last_name": { "label": "Last name", "value": "Bergmann", "type": "standard", "universal_id": "last_name" }, "email": { "label": "Email", "value": "alexander.bergmann@demo.com", "type": "standard", "universal_id": "email" } } }, ... ], ... ... } `?attributes[]=first_name` will yield all 17 employees: `{ "success": true, "metadata": { "total_elements": 17, "current_page": 0, "total_pages": 17 }, "offset": 0, "limit": 1, "data": [ { "type": "Employee", "attributes": { "id": { "label": "ID", "value": 1, "type": "integer", "universal_id": "id" }, "first_name": { "label": "First name", "value": "Alexander", "type": "standard", "universal_id": "first_name" } } } ] }` `?attributes[]=first_name&updated_since=2022-12-24T08:15:30` will yield 3 employees, ones that had their `first_name` changed since `2022-12-24T08:15:30`: `{ "success": true, "metadata": { "total_elements": 3, "current_page": 0, "total_pages": 3 }, "offset": 0, "limit": 1, "data": [ { "type": "Employee", "attributes": { "id": { "label": "ID", "value": 1, "type": "integer", "universal_id": "id" }, "first_name": { "label": "First name", "value": "Alexander", "type": "standard", "universal_id": "first_name" } } } ] }`

Responses

200 —

GET /company/employees

POST /company/employees Create an employee

Creates a new employee. If the employee’s status is not provided, it will be set based on the hire_date value - if it is in the past, status will be active, otherwise onboarding. This endpoint responds with the id of the created employee in case of success.

operationId: Employees_createEmployee

Parameters

Name	In	Required	Type	Description
X-Personio-Partner-ID	header	optional	string	The partner identifier
X-Personio-App-ID	header	optional	string	The application identifier

Request Body

application/json

schema EmployeesCreateEmployeeRequest

Property	Type	Required
employee	object	optional
└ email	string	required
└ gender	string	optional
└ office	string	optional
└ status	string	optional
└ position	string	optional
└ hire_date	string	optional
└ last_name	string	required
└ department	string	optional
└ first_name	string	required
└ subcompany	string	optional
└ supervisor_id	number	optional
└ preferred_name	string	optional
└ custom_attributes	object	optional
└ dynamic_{{ field uid }}	string	optional
└ weekly_working_hours	number	optional

application/x-www-form-urlencoded

schema EmployeesCreateEmployeeRequest1

Property	Type	Required
employee[email]	string	required
employee[gender]	string	optional
employee[status]	string	optional
employee[position]	string	optional
employee[hire_date]	string	optional
employee[last_name]	string	required
employee[department]	string	optional
employee[first_name]	string	required
employee[supervisor_id]	number	optional
employee[preferred_name]	string	optional
employee[weekly_working_hours]	number	optional

Responses

200

Successful creation of a employee

422

Employee creation failed due to invalid payload

POST /company/employees

GET /company/employees/attributes

Lists all the allowed atrributes per API credentials including custom (dynamic) attributes.

operationId: Employees_listAttributes

Parameters

Name	In	Required	Type	Description
X-Personio-Partner-ID	header	optional	string	The partner identifier
X-Personio-App-ID	header	optional	string	The application identifier

Responses

200 —

GET /company/employees/attributes

GET /company/employees/custom-attributes

This endpoint is an alias for /company/employees/attributes.

operationId: Employees_getCustomAttributes

Parameters

Name	In	Required	Type	Description
X-Personio-Partner-ID	header	optional	string	The partner identifier
X-Personio-App-ID	header	optional	string	The application identifier

Responses

200

Please refer to /company/employees/attributes

GET /company/employees/custom-attributes

GET /company/employees/{employee_id}

Show employee by ID

operationId: Employees_showById

Parameters

Name	In	Required	Type	Description
X-Personio-Partner-ID	header	optional	string	The partner identifier
X-Personio-App-ID	header	optional	string	The application identifier
employee_id	path	required	integer	Numeric `id` of the employee

Responses

200 —

404 —

GET /company/employees/{employee_id}

PATCH /company/employees/{employee_id} Update an employee

Updates an existing employee. Note: Only the fields that are listed in the body example are updatable. Attributes that are not part of the sample request body but are present inside the request are ignored. It’s not possible to update the Email field.

operationId: Employees_updateEmployeeFields

Parameters

Name	In	Required	Type	Description
X-Personio-Partner-ID	header	optional	string	The partner identifier
X-Personio-App-ID	header	optional	string	The application identifier
employee_id	path	required	integer	Numeric `id` of the employee

Request Body

application/json

schema EmployeesUpdateEmployeeFieldsRequest

Property	Type	Required
employee	object	optional
└ gender	string	optional
└ office	string	optional
└ status	string	optional
└ position	string	optional
└ hire_date	string	optional
└ last_name	string	optional
└ department	string	optional
└ first_name	string	optional
└ subcompany	string	optional
└ supervisor_id	number	optional
└ preferred_name	string	optional
└ custom_attributes	object	optional
└ dynamic_{{ field uid }}	string	optional
└ weekly_working_hours	number	optional

application/x-www-form-urlencoded

schema EmployeesUpdateEmployeeFieldsRequest1

Property	Type	Required
employee[gender]	string	optional
employee[status]	string	optional
employee[position]	string	optional
employee[hire_date]	string	optional
employee[last_name]	string	optional
employee[department]	string	optional
employee[first_name]	string	optional
employee[supervisor_id]	number	optional
employee[preferred_name]	string	optional
employee[weekly_working_hours]	number	optional

Responses

200

Employee is updated

422

Employee update failed due to invalid payload

PATCH /company/employees/{employee_id}

GET /company/employees/{employee_id}/absences/balance

Retrieve the absence balance for a specific employee

operationId: Employees_getAbsenceBalance

Parameters

Name	In	Required	Type	Description
X-Personio-Partner-ID	header	optional	string	The partner identifier
X-Personio-App-ID	header	optional	string	The application identifier
employee_id	path	required	integer	Numeric `id` of the employee

Responses

200 —

404 —

GET /company/employees/{employee_id}/absences/balance

GET /company/employees/{employee_id}/profile-picture/{width}

Show employee’s profile picture. If profile picture is missing, the 404 error will be thrown. The Profile Picture attribute has to be whitelisted.

operationId: Employees_showProfilePicture

Parameters

Name	In	Required	Type	Description
X-Personio-Partner-ID	header	optional	string	The partner identifier
X-Personio-App-ID	header	optional	string	The application identifier
employee_id	path	required	integer	Numeric `id` of the employee
width	path	required	integer	Width of the image. Default is original size

Responses

200

404

When the employee doesn’t exist or employee doesn’t have profile picture set or Profile Picture attribute is not whitelisted, this error occurs.

GET /company/employees/{employee_id}/profile-picture/{width}

Projects 4 endpoints

GET /company/attendances/projects

Provides a list of all company projects.

operationId: Projects_getAll

Parameters

Name	In	Required	Type	Description
X-Personio-Partner-ID	header	optional	string	The partner identifier
X-Personio-App-ID	header	optional	string	The application identifier

Responses

200

List of projects returned

GET /company/attendances/projects

POST /company/attendances/projects

Creates a project into the company account

operationId: Projects_createProject

Parameters

Name	In	Required	Type	Description
X-Personio-Partner-ID	header	optional	string	The partner identifier
X-Personio-App-ID	header	optional	string	The application identifier

Request Body

application/json

schema ProjectsCreateProjectRequest

Property	Type	Required
name	string	required
active	boolean	optional

Responses

200

Project created successfully

400

Invalid data was sent

POST /company/attendances/projects

DELETE /company/attendances/projects/{id}

Deletes a project from the company account

operationId: Projects_deleteProject

Parameters

Name	In	Required	Type	Description
id	path	required	integer	Numeric `id` of the project

Responses

204

Project was successfully deleted

404

Project does not exist

DELETE /company/attendances/projects/{id}

PATCH /company/attendances/projects/{id}

Updates a project with the given data

operationId: Projects_updateData

Parameters

Name	In	Required	Type	Description
id	path	required	integer	Numeric `id` of the project

Request Body

application/json

schema ProjectsUpdateDataRequest

Property	Type	Required
name	string	optional
active	boolean	optional

Responses

200

Project updated successfully

400

Invalid data was sent

404

Project not found

PATCH /company/attendances/projects/{id}

Schemas

object Absence

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "example": 1
    },
    "status": {
      "type": "string",
      "example": "approved"
    },
    "employee": {
      "$ref": "#/components/schemas/ShortEmployee"
    },
    "end_date": {
      "type": "string",
      "example": "2017-12-79T00:00:00+0100"
    },
    "created_at": {
      "type": "string",
      "example": "2017-01-17T10:32:18.000+01:00"
    },
    "created_by": {
      "type": "string",
      "example": "API",
      "description": "API if the origin is api, otherwise returns an admin employee's name who's account is used to create the absence"
    },
    "days_count": {
      "type": "number",
      "example": 3
    },
    "start_date": {
      "type": "string",
      "example": "2017-12-27T00:00:00.000+01:00"
    },
    "updated_at": {
      "type": "string",
      "example": "2017-01-17T10:32:18.000+01:00"
    },
    "certificate": {
      "type": "object",
      "properties": {
        "status": {
          "type": "string",
          "example": "not-required"
        }
      }
    },
    "half_day_end": {
      "type": "boolean",
      "example": false
    },
    "time_off_type": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "example": "TimeOffType"
        },
        "attributes": {
          "type": "object",
          "properties": {
            "id": {
              "type": "integer",
              "example": 1
            },
            "name": {
              "type": "string",
              "example": "Vacation"
            },
            "category": {
              "type": "string",
              "example": "offsite_work"
            }
          }
        }
      }
    },
    "half_day_start": {
      "type": "boolean",
      "example": false
    }
  }
}

object AbsenceEntitlement

{
  "type": "object",
  "required": [
    "label",
    "value"
  ],
  "properties": {
    "label": {
      "example": "Absence entitlement"
    },
    "value": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "enum": [
              "TimeOffType"
            ],
            "type": "string"
          },
          "attributes": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer",
                "example": 1
              },
              "name": {
                "example": "Paid Vacation"
              },
              "entitlement": {
                "example": 30
              }
            }
          }
        }
      }
    }
  }
}

object AbsenceOverviewAttribute

{
  "type": "object",
  "properties": {
    "end_date": {
      "type": "string",
      "format": "date",
      "example": "2022-03-03"
    },
    "data_type": {
      "enum": [
        "ABSENCE_OVERVIEW"
      ],
      "type": "string"
    },
    "start_date": {
      "type": "string",
      "format": "date",
      "example": "2022-03-01"
    },
    "employee_id": {
      "type": "integer",
      "example": 17
    },
    "attribute_id": {
      "type": "string",
      "example": "absence_123"
    },
    "duration_days": {
      "type": "string",
      "example": 2
    },
    "duration_hours": {
      "type": "string",
      "example": 5
    }
  }
}

object AbsencePeriodAttribute

{
  "type": "object",
  "properties": {
    "end_date": {
      "type": "string",
      "format": "date",
      "example": "2022-03-03"
    },
    "data_type": {
      "enum": [
        "ABSENCE_PERIOD"
      ],
      "type": "string"
    },
    "start_date": {
      "type": "string",
      "format": "date",
      "example": "2022-03-01"
    },
    "employee_id": {
      "type": "integer",
      "example": 17
    },
    "attribute_id": {
      "type": "string",
      "example": "absence_123:periods"
    },
    "half_day_at_end": {
      "type": "boolean"
    },
    "half_day_at_start": {
      "type": "boolean"
    }
  }
}

object AbsencePeriodBreakdown

{
  "type": "object",
  "required": [
    "date",
    "effective_duration"
  ],
  "properties": {
    "date": {
      "type": "string",
      "format": "date"
    },
    "effective_duration": {
      "type": "integer",
      "example": 60,
      "description": "Number representing the value of duration in minutes."
    }
  }
}

object AbsencePeriodResponse

{
  "type": "object",
  "allOf": [
    {
      "$ref": "#/components/schemas/Response"
    },
    {
      "type": "object",
      "properties": {
        "data": {
          "type": "object",
          "required": [
            "type",
            "attributes"
          ],
          "properties": {
            "type": {
              "example": "TimeOffPeriod"
            },
            "attributes": {
              "$ref": "#/components/schemas/Absence"
            }
          }
        }
      }
    }
  ],
  "title": "Absence Periods response"
}

object AbsencePeriodsResponse

{
  "type": "object",
  "allOf": [
    {
      "$ref": "#/components/schemas/Response"
    },
    {
      "type": "object",
      "properties": {
        "data": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "type",
              "attributes"
            ],
            "properties": {
              "type": {
                "example": "TimeOffPeriod"
              },
              "attributes": {
                "$ref": "#/components/schemas/Absence"
              }
            }
          }
        },
        "limit": {
          "type": "integer"
        },
        "offset": {
          "type": "integer"
        },
        "metadata": {
          "type": "object",
          "required": [
            "total_elements",
            "current_page",
            "total_pages"
          ],
          "properties": {
            "total_pages": {
              "type": "integer",
              "description": "The total number of pages distributing sets of items matching the query filters."
            },
            "current_page": {
              "type": "integer",
              "description": "Current page number containing the returned set of items matching with the query filters. The page number range is from 0 to total_pages - 1"
            },
            "total_elements": {
              "type": "integer",
              "description": "The total number of items matching the query filters."
            }
          }
        }
      }
    }
  ],
  "title": "List All Absence Periods response"
}

object AbsenceType

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "example": "61fe126b-a7b3-449a-b5ee-3865a6fcc546"
    },
    "name": {
      "type": "string",
      "example": "Absence Type Name"
    },
    "time_off_type_id": {
      "type": "integer",
      "example": 1
    }
  }
}

object AbsencesAddAbsenceDataResponse

{
  "type": "object",
  "properties": {
    "data": {
      "$ref": "#/components/schemas/AbsencePeriodResponse"
    }
  }
}

object AbsencesAddAbsencePeriodsDataResponse

{
  "type": "object",
  "properties": {
    "data": {
      "$ref": "#/components/schemas/HourlyAbsencePeriodResponse"
    }
  }
}

object AbsencesListTimeOffTypesResponse

{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/TimeOffTypeResource"
      }
    },
    "success": {
      "type": "boolean"
    }
  }
}

object Attendance

{
  "type": "object",
  "properties": {
    "date": {
      "type": "string",
      "format": "date"
    },
    "break": {
      "type": "integer",
      "example": 60
    },
    "status": {
      "enum": [
        "confirmed",
        "pending",
        "rejected"
      ],
      "type": "string"
    },
    "comment": {
      "type": "string",
      "example": "I was productive as hell"
    },
    "project": {
      "type": "object",
      "nullable": true,
      "properties": {
        "id": {
          "type": "integer",
          "example": 5
        },
        "type": {
          "type": "string",
          "example": "Project"
        },
        "attributes": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "example": "A project name"
            },
            "active": {
              "type": "boolean",
              "example": true
            }
          }
        }
      }
    },
    "employee": {
      "type": "integer",
      "example": 1
    },
    "end_time": {
      "type": "string",
      "example": "17:00",
      "pattern": "^\\d\\d:\\d\\d$",
      "nullable": true
    },
    "is_holiday": {
      "type": "boolean",
      "example": false
    },
    "start_time": {
      "type": "string",
      "example": "08:00",
      "pattern": "^\\d\\d:\\d\\d$"
    },
    "is_on_time_off": {
      "type": "boolean",
      "example": false
    }
  }
}

object Attendance404ErrorResponse

{
  "type": "object",
  "title": "404 [Not Found] Attendance Error",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "example": 404
        },
        "message": {
          "example": "The attendance period was not found."
        }
      }
    },
    "success": {
      "type": "boolean",
      "example": false
    }
  }
}

object AttendanceCreateRequest

{
  "type": "object",
  "properties": {
    "attendances": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "employee",
          "date",
          "start_time",
          "break"
        ],
        "properties": {
          "date": {
            "type": "string",
            "format": "date"
          },
          "break": {
            "type": "integer",
            "example": 60,
            "minimum": 0
          },
          "comment": {
            "type": "string",
            "example": "I was productive as hell",
            "nullable": true
          },
          "employee": {
            "type": "integer",
            "example": 1,
            "minimum": 1
          },
          "end_time": {
            "type": "string",
            "example": "17:00",
            "pattern": "^\\d\\d:\\d\\d$",
            "nullable": true,
            "description": "Format: hh:mm"
          },
          "project_id": {
            "type": "integer",
            "example": 5,
            "nullable": true
          },
          "start_time": {
            "type": "string",
            "example": "08:00",
            "pattern": "^\\d\\d:\\d\\d$",
            "description": "Format: hh:mm"
          }
        }
      },
      "minItems": 1
    },
    "skip_approval": {
      "type": "boolean",
      "description": "Optional, default value is true. If set to false, the approval status of the attendance period will be \"pending\" if an approval rule is set for the attendances type. The respective approval flow will be triggered."
    }
  }
}

object AttendanceCreateUpdate400ErrorResponse

{
  "type": "object",
  "title": "400 [Bad Request] Attendances Creation Error",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "example": 400
        },
        "message": {
          "type": "string",
          "example": "Error when trying to insert Attendances periods rows"
        },
        "detailed_message": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer",
                "example": null,
                "nullable": true
              },
              "date": {
                "type": "string",
                "example": "2017-01-01T00:00:00.000Z"
              },
              "break": {
                "type": "integer",
                "example": 60
              },
              "comment": {
                "type": "string",
                "example": "Optional Test Comment"
              },
              "success": {
                "type": "boolean",
                "example": false
              },
              "employee": {
                "type": "integer",
                "example": 1234
              },
              "end_time": {
                "type": "string",
                "example": "18:00"
              },
              "error_msg": {
                "type": "string",
                "example": "Existing overlapping attendances periods"
              },
              "project_id": {
                "type": "integer",
                "example": null,
                "nullable": true
              },
              "start_time": {
                "type": "string",
                "example": "09:00"
              }
            }
          }
        }
      }
    },
    "success": {
      "type": "boolean",
      "example": false
    }
  }
}

object AttendanceDelete400ErrorResponse

{
  "type": "object",
  "title": "400 [Bad Request] Attendance Error",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "example": 400
        },
        "message": {
          "example": "Bad Request"
        }
      }
    },
    "success": {
      "type": "boolean",
      "example": false
    }
  }
}

object AttendancePeriodsResponse

{
  "type": "object",
  "allOf": [
    {
      "$ref": "#/components/schemas/Response"
    },
    {
      "type": "object",
      "properties": {
        "data": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "id",
              "type",
              "attributes"
            ],
            "properties": {
              "id": {
                "type": "integer",
                "example": 1
              },
              "type": {
                "example": "AttendancePeriod"
              },
              "attributes": {
                "$ref": "#/components/schemas/Attendance"
              }
            }
          }
        },
        "limit": {
          "type": "integer"
        },
        "offset": {
          "type": "integer"
        },
        "metadata": {
          "type": "object",
          "required": [
            "total_elements",
            "current_page",
            "total_pages"
          ],
          "properties": {
            "total_pages": {
              "type": "integer",
              "description": "The total number of pages distributing sets of items matching the query filters."
            },
            "current_page": {
              "type": "integer",
              "description": "Current page number containing the returned set of items matching with the query filters. The page number range is from 0 to total_pages - 1"
            },
            "total_elements": {
              "type": "integer",
              "description": "The total number of items matching the query filters."
            }
          }
        }
      }
    }
  ],
  "title": "List All Attendance Periods response"
}

object AttendanceProject

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "example": 1
    },
    "type": {
      "type": "string",
      "example": "Project"
    },
    "attributes": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "example": "Project name"
        },
        "active": {
          "type": "boolean",
          "example": true,
          "description": "Marks the availability of the project. When a new project is created, it's set by default to false."
        }
      }
    }
  }
}

object AttendanceUpdateRequest

{
  "type": "object",
  "properties": {
    "date": {
      "type": "string",
      "format": "date"
    },
    "break": {
      "type": "integer",
      "example": 60,
      "minimum": 0
    },
    "comment": {
      "type": "string",
      "example": "I was productive as hell",
      "nullable": true
    },
    "end_time": {
      "type": "string",
      "example": "17:00",
      "pattern": "^\\d\\d:\\d\\d$",
      "nullable": true,
      "description": "Format: hh:mm"
    },
    "project_id": {
      "type": "integer",
      "example": 5,
      "nullable": true
    },
    "start_time": {
      "type": "string",
      "example": "08:00",
      "pattern": "^\\d\\d:\\d\\d$",
      "description": "Format: hh:mm"
    },
    "skip_approval": {
      "type": "boolean",
      "description": "Optional, default value is true. If set to false, the approval status of the attendance period will be \"pending\" if an approval rule is set for the attendances type. The respective approval flow will be triggered."
    }
  }
}

object CompensationAttribute

{
  "type": "object",
  "properties": {
    "amount": {
      "type": "string",
      "example": 12.2
    },
    "data_type": {
      "enum": [
        "COMPENSATION"
      ],
      "type": "string"
    },
    "bonus_type": {
      "type": "string",
      "example": "MAX"
    },
    "employee_id": {
      "type": "integer",
      "example": 17
    },
    "attribute_id": {
      "type": "string",
      "example": "ABCXXX"
    },
    "currency_code": {
      "type": "string",
      "example": "USD"
    },
    "overtime_hours": {
      "type": "string",
      "example": 12
    },
    "currency_symbol": {
      "type": "string",
      "example": "$"
    }
  }
}

object CostCenter

{
  "type": "object",
  "properties": {
    "value": {
      "type": "string",
      "example": "Test Center"
    },
    "weight": {
      "type": "string",
      "example": "100%"
    },
    "cost_center_id": {
      "type": "string",
      "example": 1
    }
  }
}

object CostCenterAttribute

{
  "type": "object",
  "properties": {
    "data_type": {
      "enum": [
        "COST_CENTER"
      ],
      "type": "string"
    },
    "employee_id": {
      "type": "integer",
      "example": 17
    },
    "attribute_id": {
      "type": "string",
      "example": "cost_center"
    },
    "cost_centers": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/CostCenter"
      }
    }
  }
}

object CostCenterHistoricalAttribute

{
  "type": "object",
  "properties": {
    "data_type": {
      "enum": [
        "COST_CENTER"
      ],
      "type": "string"
    },
    "employee_id": {
      "type": "integer",
      "example": 17
    },
    "attribute_id": {
      "type": "string",
      "example": "cost_center"
    },
    "cost_centers": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/CostCenter"
      }
    },
    "effective_date": {
      "type": "string",
      "example": "2021-01-01T00:00:00.000Z"
    }
  }
}

object CostCenters

{
  "type": "object",
  "properties": {
    "type": {
      "$ref": "#/components/schemas/TypeEnum"
    },
    "label": {
      "example": "Cost center"
    },
    "value": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "example": "CostCenter"
          },
          "attributes": {
            "type": "object",
            "properties": {
              "id": {
                "type": "number",
                "example": 1
              },
              "name": {
                "example": "Cost Center One"
              },
              "percentage": {
                "type": "number",
                "example": 50
              }
            }
          }
        }
      }
    },
    "universal_id": {
      "example": "cost_center"
    }
  }
}

object CreateAbsencePeriodRequest

{
  "type": "object",
  "title": "Create Absence periods with **time unit** set to **hours**",
  "required": [
    "employee_id",
    "time_off_type_id",
    "start_date",
    "end_date"
  ],
  "properties": {
    "comment": {
      "type": "string",
      "example": "Some Comment",
      "description": "Optional comment"
    },
    "end_date": {
      "type": "string",
      "format": "date",
      "example": "2020-01-31",
      "description": "Absence end date. Format: yyyy-mm-dd"
    },
    "end_time": {
      "type": "string",
      "format": "date",
      "example": "15:00",
      "description": "Absence end time. Format: HH:mm (hours and minutes) and only required if the start_date and end_date are the same (partial-day absence)"
    },
    "start_date": {
      "type": "string",
      "format": "date",
      "example": "2020-01-31",
      "description": "Absence start date. Format: yyyy-mm-dd"
    },
    "start_time": {
      "type": "string",
      "format": "date",
      "example": "03:00",
      "description": "Absence start time. Format: HH:mm (hours and minutes) and only required if the start_date and end_date are the same (partial-day absence)"
    },
    "employee_id": {
      "type": "integer",
      "example": 10735,
      "description": "Employee identifier"
    },
    "half_day_end": {
      "type": "boolean",
      "example": false,
      "description": "Whether the end date is a half-day off, only considered if the start_date and end_date are not the same (more than one day absence)"
    },
    "skip_approval": {
      "type": "boolean",
      "example": false,
      "description": "Optional, default value is true. If set to false, the approval status of the absence request will be \"pending\" if an approval rule is set for the absence type in Personio. The respective approval flow will be triggered."
    },
    "half_day_start": {
      "type": "boolean",
      "example": false,
      "description": "Whether the start date is a half-day off, only considered if the start_date and end_date are not the same (more than one day absence)"
    },
    "time_off_type_id": {
      "type": "integer",
      "example": 10735,
      "description": "Time-off type identifier"
    }
  }
}

object CreateTimeOffPeriodRequest

{
  "type": "object",
  "title": "Create time-off periods",
  "required": [
    "employee_id",
    "time_off_type_id",
    "start_date",
    "end_date",
    "half_day_start",
    "half_day_end"
  ],
  "properties": {
    "comment": {
      "type": "string",
      "example": "Some Comment",
      "description": "Optional comment"
    },
    "end_date": {
      "type": "string",
      "format": "date",
      "example": "2020-01-31",
      "description": "Absence end date. Format: yyyy-mm-dd"
    },
    "start_date": {
      "type": "string",
      "format": "date",
      "example": "2020-01-31",
      "description": "Absence start date. Format: yyyy-mm-dd"
    },
    "employee_id": {
      "type": "integer",
      "description": "Employee identifier"
    },
    "half_day_end": {
      "type": "boolean",
      "example": false,
      "description": "Whether the end date is a half-day off."
    },
    "skip_approval": {
      "type": "boolean",
      "example": false,
      "description": "Optional, default value is true. If set to false, the approval status of the absence request will be \"pending\" if an approval rule is set for the absence type in Personio. The respective approval flow will be triggered."
    },
    "half_day_start": {
      "type": "boolean",
      "example": false,
      "description": "Whether the start date is a half-day off."
    },
    "time_off_type_id": {
      "type": "integer",
      "description": "Time-off type identifier"
    }
  }
}

object CustomReportsErrorResponse

{
  "type": "object",
  "properties": {
    "errors": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/ErrorDetails"
      }
    },
    "status": {
      "type": "integer",
      "example": 500
    },
    "trace_id": {
      "type": "string",
      "example": "ABCXXX"
    },
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "example": "2020-01-01T00:00:00Z"
    }
  }
}

object DefaultAttribute

{
  "type": "object",
  "properties": {
    "value": {
      "type": "string",
      "example": "Robert"
    },
    "data_type": {
      "enum": [
        "TEXT"
      ],
      "type": "string"
    },
    "employee_id": {
      "type": "integer",
      "example": 17
    },
    "attribute_id": {
      "type": "string",
      "example": "first_name"
    }
  }
}

object DefaultHistoricalAttribute

{
  "type": "object",
  "properties": {
    "value": {
      "type": "string",
      "example": "Robert"
    },
    "data_type": {
      "enum": [
        "TEXT"
      ],
      "type": "string"
    },
    "employee_id": {
      "type": "integer",
      "example": 17
    },
    "attribute_id": {
      "type": "string",
      "example": "first_name"
    },
    "effective_date": {
      "type": "string",
      "example": "2021-01-01T00:00:00.000Z"
    }
  }
}

object DeletedAbsenceResponse

{
  "type": "object",
  "title": "Default response object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "message": {
          "example": "The absence period was deleted."
        }
      }
    },
    "success": {
      "type": "boolean"
    }
  }
}

object DeletedAttendanceResponse

{
  "type": "object",
  "title": "Default response object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "message": {
          "example": "The attendance period was deleted"
        }
      }
    },
    "success": {
      "type": "boolean"
    }
  }
}

object Department

{
  "type": "object",
  "properties": {
    "type": {
      "$ref": "#/components/schemas/TypeEnum"
    },
    "label": {
      "example": "Department"
    },
    "value": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "example": "Department"
        },
        "attributes": {
          "type": "object",
          "required": [
            "id",
            "name"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "example": 1
            },
            "name": {
              "type": "string",
              "example": "Marketing"
            }
          }
        }
      }
    },
    "universal_id": {
      "example": "department"
    }
  }
}

object DocumentCategoriesResponse

{
  "type": "object",
  "allOf": [
    {
      "type": "object",
      "properties": {
        "data": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/DocumentCategory"
          }
        },
        "success": {
          "type": "boolean",
          "example": true
        }
      }
    }
  ]
}

object DocumentCategory

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "example": 1
    },
    "type": {
      "type": "string",
      "example": "DocumentCategory"
    },
    "attributes": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "example": "Certificates of employment"
        }
      }
    }
  }
}

object DocumentEmployeeResponseObject

{
  "type": "object",
  "properties": {
    "id": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "example": "standard"
        },
        "label": {
          "type": "string",
          "example": "ID"
        },
        "value": {
          "type": "integer",
          "example": 1
        },
        "universal_id": {
          "type": "string",
          "example": "id"
        }
      }
    },
    "email": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "example": "standard"
        },
        "label": {
          "type": "string",
          "example": "Email"
        },
        "value": {
          "type": "string",
          "example": "michaeldou@demo.de"
        },
        "universal_id": {
          "type": "string",
          "example": "email"
        }
      }
    },
    "last_name": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "example": "standard"
        },
        "label": {
          "type": "string",
          "example": "Last name"
        },
        "value": {
          "type": "string",
          "example": "Dou"
        },
        "universal_id": {
          "type": "string",
          "example": "last_name"
        }
      }
    },
    "first_name": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "example": "standard"
        },
        "label": {
          "type": "string",
          "example": "First name"
        },
        "value": {
          "type": "string",
          "example": "Michael"
        },
        "universal_id": {
          "type": "string",
          "example": "first_name"
        }
      }
    }
  }
}

object DocumentUploadFailedWithBadDocumentCategoryResponse

{
  "type": "object",
  "allOf": [
    {
      "type": "object",
      "properties": {
        "error": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "No query results for model [DocumentCategory] 1"
            }
          }
        },
        "success": {
          "type": "boolean",
          "example": false
        }
      }
    }
  ]
}

object DocumentUploadFailedWithUnsupportedFileTypeResponse

{
  "type": "object",
  "allOf": [
    {
      "type": "object",
      "properties": {
        "error": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "The given data was invalid."
            },
            "error_data": {
              "type": "object",
              "properties": {
                "file": {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "example": "The file must be a file of type: pdf, docx, doc, jpg, zip, png, txt, jpeg, odt, xlsx, rtf, htm, xls, p7s, pptx, pages, rar, ppt, gif, tif, html, msg, asc, tiff, wps, bmp, 7z, csv, ics, vcf, dotx, numbers, eps, gz, ods, otf, odp, odg, rtfd, txz, webarchive, xml, xps, md, fax."
                  }
                }
              }
            }
          }
        },
        "success": {
          "type": "boolean",
          "example": false
        }
      }
    }
  ]
}

object DocumentUploadRequest

{
  "type": "object",
  "required": [
    "title",
    "employee_id",
    "category_id",
    "file"
  ],
  "properties": {
    "date": {
      "type": "string",
      "format": "date",
      "description": "Optional date can be added to the uploaded document. Must follow the format: Y-m-d"
    },
    "file": {
      "type": "string",
      "format": "binary",
      "description": "The document that shall be uploaded to an employees profile. Maximum file size is 30MB."
    },
    "title": {
      "type": "string",
      "description": "Title of the document. Maximum length is 255 characters."
    },
    "comment": {
      "type": "string",
      "description": "Optional comment that can be added to the uploaded document."
    },
    "category_id": {
      "type": "integer",
      "description": "Document Category identifier"
    },
    "employee_id": {
      "type": "integer",
      "description": "Employee identifier"
    }
  }
}

object DocumentUploadSuccessResponse

{
  "type": "object",
  "allOf": [
    {
      "type": "object",
      "properties": {
        "data": {
          "type": "object",
          "properties": {
            "id": {
              "type": "integer",
              "example": 1
            },
            "type": {
              "type": "string",
              "example": "Document"
            },
            "attributes": {
              "type": "object",
              "properties": {
                "date": {
                  "type": "string",
                  "example": "2022-01-01"
                },
                "title": {
                  "type": "string",
                  "example": "Document Title"
                },
                "comment": {
                  "type": "string",
                  "example": "Optional Test Comment"
                },
                "employee": {
                  "$ref": "#/components/schemas/DocumentEmployeeResponseObject"
                },
                "category_id": {
                  "$ref": "#/components/schemas/DocumentCategory"
                }
              }
            }
          }
        },
        "success": {
          "type": "boolean",
          "example": true
        }
      }
    }
  ]
}

object DurationAttribute

{
  "type": "object",
  "properties": {
    "duration": {
      "type": "integer",
      "example": 10
    },
    "data_type": {
      "enum": [
        "DURATION"
      ],
      "type": "string"
    },
    "employee_id": {
      "type": "integer",
      "example": 17
    },
    "attribute_id": {
      "type": "string",
      "example": "attendance_contractual_target_hours"
    }
  }
}

object DurationHistoricalAttribute

{
  "type": "object",
  "properties": {
    "duration": {
      "type": "integer",
      "example": 10
    },
    "data_type": {
      "enum": [
        "DURATION"
      ],
      "type": "string"
    },
    "employee_id": {
      "type": "integer",
      "example": 17
    },
    "attribute_id": {
      "type": "string",
      "example": "attendance_contractual_target_hours"
    },
    "effective_date": {
      "type": "string",
      "example": "2021-01-01T00:00:00.000Z"
    }
  }
}

object Employee

{
  "type": "object",
  "properties": {
    "id": {
      "type": "object",
      "properties": {
        "type": {
          "$ref": "#/components/schemas/TypeEnum"
        },
        "label": {
          "example": "ID"
        },
        "value": {
          "example": 1
        },
        "universal_id": {
          "example": "id"
        }
      }
    },
    "team": {
      "$ref": "#/components/schemas/Team"
    },
    "email": {
      "type": "object",
      "properties": {
        "type": {
          "$ref": "#/components/schemas/TypeEnum"
        },
        "label": {
          "example": "Email"
        },
        "value": {
          "example": "michael.dou@personio.de"
        },
        "universal_id": {
          "example": "email"
        }
      }
    },
    "gender": {
      "type": "object",
      "properties": {
        "type": {
          "$ref": "#/components/schemas/TypeEnum"
        },
        "label": {
          "example": "Gender"
        },
        "value": {
          "example": "male"
        },
        "universal_id": {
          "example": "gender"
        }
      }
    },
    "office": {
      "$ref": "#/components/schemas/Office"
    },
    "status": {
      "type": "object",
      "properties": {
        "type": {
          "$ref": "#/components/schemas/TypeEnum"
        },
        "label": {
          "example": "Status"
        },
        "value": {
          "example": "active"
        },
        "universal_id": {
          "example": "status"
        }
      }
    },
    "position": {
      "type": "object",
      "properties": {
        "type": {
          "$ref": "#/components/schemas/TypeEnum"
        },
        "label": {
          "example": "Position"
        },
        "value": {
          "example": "Online Marketing Specialist"
        },
        "universal_id": {
          "example": "position"
        }
      }
    },
    "hire_date": {
      "type": "object",
      "properties": {
        "type": {
          "$ref": "#/components/schemas/TypeEnum"
        },
        "label": {
          "example": "Hire date"
        },
        "value": {
          "example": "2012-02-01T00:00:00.000+01:00"
        },
        "universal_id": {
          "example": "hire_date"
        }
      }
    },
    "last_name": {
      "type": "object",
      "properties": {
        "type": {
          "$ref": "#/components/schemas/TypeEnum"
        },
        "label": {
          "example": "Last name"
        },
        "value": {
          "example": "Dou"
        },
        "universal_id": {
          "example": "last_name"
        }
      }
    },
    "created_at": {
      "type": "object",
      "properties": {
        "type": {
          "$ref": "#/components/schemas/TypeEnum"
        },
        "label": {
          "example": "Created at"
        },
        "value": {
          "example": "2018-02-01T00:00:00.000+01:00"
        },
        "universal_id": {
          "example": "created_at"
        }
      }
    },
    "department": {
      "$ref": "#/components/schemas/Department"
    },
    "first_name": {
      "type": "object",
      "properties": {
        "type": {
          "$ref": "#/components/schemas/TypeEnum"
        },
        "label": {
          "example": "First name"
        },
        "value": {
          "example": "Michael"
        },
        "universal_id": {
          "example": "first_name"
        }
      }
    },
    "fix_salary": {
      "type": "object",
      "properties": {
        "type": {
          "$ref": "#/components/schemas/TypeEnum"
        },
        "label": {
          "example": "Fix salary"
        },
        "value": {
          "example": 4000
        },
        "currency": {
          "type": "string",
          "example": "EUR"
        },
        "universal_id": {
          "example": "fix_salary"
        }
      }
    },
    "subcompany": {
      "$ref": "#/components/schemas/Office"
    },
    "supervisor": {
      "$ref": "#/components/schemas/Supervisor"
    },
    "cost_centers": {
      "$ref": "#/components/schemas/CostCenters"
    },
    "dynamic_21827": {
      "type": "object",
      "properties": {
        "type": {
          "$ref": "#/components/schemas/TypeEnum",
          "description": "The type of the field."
        },
        "label": {
          "example": "IBAN"
        },
        "value": {
          "example": "DE98 8989 9898 0000 8989 00"
        },
        "universal_id": {
          "example": "iban"
        }
      }
    },
    "hourly_salary": {
      "type": "object",
      "properties": {
        "type": {
          "$ref": "#/components/schemas/TypeEnum"
        },
        "label": {
          "example": "Hourly salary"
        },
        "value": {
          "example": 0
        },
        "currency": {
          "type": "string",
          "example": "EUR"
        },
        "universal_id": {
          "example": "hourly_salary"
        }
      }
    },
    "work_schedule": {
      "$ref": "#/components/schemas/WorkSchedule"
    },
    "preferred_name": {
      "type": "object",
      "properties": {
        "type": {
          "$ref": "#/components/schemas/TypeEnum"
        },
        "label": {
          "example": "Name (preferred)"
        },
        "value": {
          "example": "Michael Dou"
        },
        "universal_id": {
          "example": "preferred_name"
        }
      }
    },
    "employment_type": {
      "type": "object",
      "properties": {
        "type": {
          "$ref": "#/components/schemas/TypeEnum"
        },
        "label": {
          "example": "Employment type"
        },
        "value": {
          "example": "internal"
        },
        "universal_id": {
          "example": "employment_type"
        }
      }
    },
    "profile_picture": {
      "type": "object",
      "properties": {
        "type": {
          "$ref": "#/components/schemas/TypeEnum"
        },
        "label": {
          "example": "Profile Picture"
        },
        "value": {
          "example": "http://api.dev.personio.de/v1/company/employees/1/profile-picture"
        },
        "universal_id": {
          "example": "profile_picture"
        }
      }
    },
    "holiday_calendar": {
      "$ref": "#/components/schemas/HolidayCalendar"
    },
    "last_modified_at": {
      "type": "object",
      "properties": {
        "type": {
          "$ref": "#/components/schemas/TypeEnum"
        },
        "label": {
          "example": "Last modified"
        },
        "value": {
          "example": "2020-11-18T17:33:55+01:00"
        },
        "universal_id": {
          "example": "last_modified_at"
        }
      }
    },
    "last_working_day": {
      "type": "object",
      "properties": {
        "type": {
          "$ref": "#/components/schemas/TypeEnum"
        },
        "label": {
          "example": "Last day of work"
        },
        "value": {
          "example": null
        },
        "universal_id": {
          "example": "last_working_day"
        }
      }
    },
    "termination_date": {
      "type": "object",
      "properties": {
        "type": {
          "$ref": "#/components/schemas/TypeEnum"
        },
        "label": {
          "example": "Termonation date"
        },
        "value": {
          "example": "2020-02-01T00:00:00.000+01:00"
        },
        "universal_id": {
          "example": "termination_date"
        }
      }
    },
    "termination_type": {
      "type": "object",
      "properties": {
        "type": {
          "$ref": "#/components/schemas/TypeEnum"
        },
        "label": {
          "example": "Termonation type"
        },
        "value": {
          "example": null
        },
        "universal_id": {
          "example": "termination_type"
        }
      }
    },
    "contract_end_date": {
      "type": "object",
      "properties": {
        "type": {
          "$ref": "#/components/schemas/TypeEnum"
        },
        "label": {
          "example": "Contact end date"
        },
        "value": {
          "example": "2020-02-01T00:00:00.000+01:00"
        },
        "universal_id": {
          "example": "contract_end_date"
        }
      }
    },
    "termination_reason": {
      "type": "object",
      "properties": {
        "type": {
          "$ref": "#/components/schemas/TypeEnum"
        },
        "label": {
          "example": "Termonation reason"
        },
        "value": {
          "example": null
        },
        "universal_id": {
          "example": "termination_reason"
        }
      }
    },
    "absence_entitlement": {
      "$ref": "#/components/schemas/AbsenceEntitlement"
    },
    "fix_salary_interval": {
      "type": "object",
      "properties": {
        "type": {
          "$ref": "#/components/schemas/TypeEnum"
        },
        "label": {
          "example": "Salary interval"
        },
        "value": {
          "example": "monthly"
        },
        "universal_id": {
          "example": "fix_salary_interval"
        }
      }
    },
    "probation_period_end": {
      "type": "object",
      "properties": {
        "type": {
          "$ref": "#/components/schemas/TypeEnum"
        },
        "label": {
          "example": "Probation period end"
        },
        "value": {
          "example": "2020-02-01T00:00:00.000+01:00"
        },
        "universal_id": {
          "example": "probation_period_end"
        }
      }
    },
    "vacation_day_balance": {
      "type": "object",
      "properties": {
        "type": {
          "$ref": "#/components/schemas/TypeEnum"
        },
        "label": {
          "example": "Vacation day balance"
        },
        "value": {
          "example": 20.5
        },
        "universal_id": {
          "example": "vacation_day_balance"
        }
      }
    },
    "weekly_working_hours": {
      "type": "object",
      "properties": {
        "type": {
          "$ref": "#/components/schemas/TypeEnum"
        },
        "label": {
          "example": "Weekly hours"
        },
        "value": {
          "example": 40
        },
        "universal_id": {
          "example": "weekly_working_hours"
        }
      }
    }
  }
}

object Employee404ErrorResponse

{
  "type": "object",
  "title": "404 [Not Found] Employee Error",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "example": 0
        },
        "message": {
          "example": "Es ist ein Problem aufgetreten"
        }
      }
    },
    "success": {
      "type": "boolean",
      "example": false
    }
  }
}

object EmployeeAbsenceBalance

{
  "type": "object",
  "title": "Employee Absence Balance",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 1234
          },
          "name": {
            "type": "string",
            "example": "Paid Vacation"
          },
          "balance": {
            "type": "number",
            "example": 10.5
          },
          "category": {
            "type": "string",
            "example": "custom_absence"
          }
        }
      }
    },
    "success": {
      "type": "boolean"
    }
  }
}

object EmployeeCreatedResponse

{
  "type": "object",
  "title": "Successfully created employee response",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "example": 1
        },
        "message": {
          "type": "string",
          "example": "success"
        }
      }
    },
    "success": {
      "type": "boolean"
    }
  }
}

object EmployeeCreationErrorResponse

{
  "type": "object",
  "title": "Employee creation failed due to invalid payload",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "number",
          "example": 422
        },
        "message": {
          "type": "string",
          "example": "Supervisor with ID 1 not found"
        }
      }
    },
    "success": {
      "type": "boolean"
    }
  }
}

object EmployeeResponse

{
  "allOf": [
    {
      "$ref": "#/components/schemas/Response"
    },
    {
      "type": "object",
      "properties": {
        "data": {
          "type": "object",
          "properties": {
            "type": {
              "example": "Employee"
            },
            "attributes": {
              "$ref": "#/components/schemas/Employee"
            }
          }
        }
      }
    }
  ],
  "title": "Employee Response"
}

object EmployeeUpdateErrorResponse

{
  "type": "object",
  "title": "Employee update failed due to invalid payload",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "number",
          "example": 422
        },
        "message": {
          "type": "string",
          "example": "Supervisor with ID 1 not found"
        }
      }
    },
    "success": {
      "type": "boolean"
    }
  }
}

object EmployeeUpdatedResponse

{
  "type": "object",
  "title": "Successfully updated employee response",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "example": 12345
        }
      }
    },
    "meta": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "default": []
    },
    "success": {
      "type": "boolean",
      "example": true
    }
  }
}

object EmployeesCreateEmployeeRequest

{
  "type": "object",
  "properties": {
    "employee": {
      "type": "object",
      "required": [
        "email",
        "first_name",
        "last_name"
      ],
      "properties": {
        "email": {
          "type": "string",
          "example": "john.dou@demo.com",
          "description": "The e-mail field is required for the employee creation. Updating of this field is not currently supported."
        },
        "gender": {
          "type": "string",
          "example": "male"
        },
        "office": {
          "type": "string",
          "example": "Madrid",
          "description": "The office employee belongs to. Should be predefined in Personio. Otherwise will be ignored with showing meta error in the response."
        },
        "status": {
          "type": "string",
          "example": "active",
          "description": "Status of the employee. Overrides the status determined based on the value of `hire_date`."
        },
        "position": {
          "type": "string",
          "example": "developer"
        },
        "hire_date": {
          "type": "string",
          "format": "date",
          "example": "2020-01-31",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
          "description": "Employee hire date. Format: \"yyyy-mm-dd\". If `status` is not provided, it will be set to `active` if the hire date is in the past, or to `onboarding` if it's in the future."
        },
        "last_name": {
          "type": "string",
          "example": "Dou"
        },
        "department": {
          "type": "string",
          "example": "IT",
          "description": "The department employee belongs to. Should be predefined in Personio. Otherwise will be ignored with showing meta error in the response."
        },
        "first_name": {
          "type": "string",
          "example": "John"
        },
        "subcompany": {
          "type": "string",
          "example": "ACME",
          "description": "The subcompany employee belongs to. Should be predefined in Personio. Otherwise will be ignored with showing meta error in the response."
        },
        "supervisor_id": {
          "type": "number",
          "example": 5,
          "description": "Employee ID of the Supervisor to be assigned. It needs to belong to a current existing employee, otherwise an error will be returned. If not present, no supervisor will be assigned."
        },
        "preferred_name": {
          "type": "string",
          "example": "John Dou"
        },
        "custom_attributes": {
          "type": "object",
          "properties": {
            "dynamic_{{ field uid }}": {
              "type": "string",
              "example": "German",
              "description": "Dynamic field, represented by unique id."
            }
          }
        },
        "weekly_working_hours": {
          "type": "number",
          "example": 40
        }
      }
    }
  }
}

Load more schemas

Versions

Version	Endpoints	Schemas	Ingested	Status
1.0	29	110	2026-05-11	current
1.0	29	110	2026-04-16