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

Clear filters

GET POST PUT PATCH DELETE

Absences 4 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

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

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 1 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

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 1 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

Employees 6 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

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}

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 1 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

Load more endpoints

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