Query structured spec data via REST or MCP. Get exactly what your agent needs.
https://api.personio.de/v1
/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!
| 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 |
Absence data
application/x-www-form-urlencoded
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 |
The absence period was successfully created
Invalid request
Employee or Absence type not found
Validation error
Internal server error
POST /company/absence-periods
/company/time-offs
Adds absence data for absence types with time unit set to days.
| 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 |
Absence data
application/x-www-form-urlencoded
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 |
The absence period is successfully created
Invalid request
Employee or Absence type not found
Validation error
POST /company/time-offs
/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.
| 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 |
List of attendance periods to create
application/json
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
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 |
The attendance periods are successfully created
Invalid request
Unauthorized Access
Forbidden Access
POST /company/attendances
/company/documents
This endpoint is responsible for uploading documents for the company employees.
| 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 |
Data necessary for document upload.
multipart/form-data
DocumentUploadRequest
| Property | Type | Required |
|---|---|---|
| date | string | optional |
| file | string | required |
| title | string | required |
| comment | string | optional |
| category_id | integer | required |
| employee_id | integer | required |
The document was successfully uploaded to the employees profile
This status code is returned if the provided employee_id or category_id are not found within the company.
This status code is returned if the provided request parameters cannot be processed or if the parameters are invalid.
POST /company/documents
/company/employees
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.
| 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 |
application/json
EmployeesCreateEmployeeRequest
| Property | Type | Required |
|---|---|---|
| employee | object | optional |
| 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
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 |
Successful creation of a employee
Employee creation failed due to invalid payload
POST /company/employees
/company/attendances/projects
Creates a project into the company account
| 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 |
application/json
ProjectsCreateProjectRequest
| Property | Type | Required |
|---|---|---|
| name | string | required |
| active | boolean | optional |
Project created successfully
Invalid data was sent
POST /company/attendances/projects
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
}
}
}
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
}
}
}
}
}
}
}
}
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
}
}
}
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"
}
}
}
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."
}
}
}
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"
}
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"
}
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
}
}
}
AbsencesAddAbsenceDataResponse
{
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/AbsencePeriodResponse"
}
}
}
AbsencesAddAbsencePeriodsDataResponse
{
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/HourlyAbsencePeriodResponse"
}
}
}
AbsencesListTimeOffTypesResponse
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TimeOffTypeResource"
}
},
"success": {
"type": "boolean"
}
}
}
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
}
}
}
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
}
}
}
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."
}
}
}
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
}
}
}
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
}
}
}
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"
}
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."
}
}
}
}
}
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."
}
}
}
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": "$"
}
}
}
CostCenter
{
"type": "object",
"properties": {
"value": {
"type": "string",
"example": "Test Center"
},
"weight": {
"type": "string",
"example": "100%"
},
"cost_center_id": {
"type": "string",
"example": 1
}
}
}
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"
}
}
}
}
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"
}
}
}
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"
}
}
}
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"
}
}
}
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"
}
}
}
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"
}
}
}
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"
}
}
}
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"
}
}
}
DeletedAbsenceResponse
{
"type": "object",
"title": "Default response object",
"properties": {
"data": {
"type": "object",
"properties": {
"message": {
"example": "The absence period was deleted."
}
}
},
"success": {
"type": "boolean"
}
}
}
DeletedAttendanceResponse
{
"type": "object",
"title": "Default response object",
"properties": {
"data": {
"type": "object",
"properties": {
"message": {
"example": "The attendance period was deleted"
}
}
},
"success": {
"type": "boolean"
}
}
}
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"
}
}
}
DocumentCategoriesResponse
{
"type": "object",
"allOf": [
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DocumentCategory"
}
},
"success": {
"type": "boolean",
"example": true
}
}
}
]
}
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"
}
}
}
}
}
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"
}
}
}
}
}
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
}
}
}
]
}
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
}
}
}
]
}
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"
}
}
}
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
}
}
}
]
}
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"
}
}
}
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"
}
}
}
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"
}
}
}
}
}
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
}
}
}
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"
}
}
}
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"
}
}
}
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"
}
}
}
EmployeeResponse
{
"allOf": [
{
"$ref": "#/components/schemas/Response"
},
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"type": {
"example": "Employee"
},
"attributes": {
"$ref": "#/components/schemas/Employee"
}
}
}
}
}
],
"title": "Employee Response"
}
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"
}
}
}
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
}
}
}
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
}
}
}
}
}
| Version | Endpoints | Schemas | Ingested | Status |
|---|---|---|---|---|
| 1.0 | 29 | 110 | 2026-05-11 | current |
| 1.0 | 29 | 110 | 2026-04-16 |