Query structured spec data via REST or MCP. Get exactly what your agent needs.
https://api.personio.de/v1
/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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| 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. |
GET /company/absence-periods
/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!
{
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"$ref": "#/components/schemas/CreateAbsencePeriodRequest"
}
}
},
"required": true,
"description": "Absence data"
}
POST /company/absence-periods
/company/absence-periods/{id}
Deletes absence period data for absence types with **time unit** set to **hours**.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| id | path | required | string | ID of the absence period to delete |
DELETE /company/absence-periods/{id}
/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'.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| 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. |
GET /company/time-off-types
/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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| 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 |
GET /company/time-offs
/company/time-offs
Adds absence data for absence types with **time unit** set to **days**.
{
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"$ref": "#/components/schemas/CreateTimeOffPeriodRequest"
}
}
},
"required": true,
"description": "Absence data"
}
POST /company/time-offs
/company/time-offs/{id}
Deletes absence period data for absence types with **time unit** set to **days**.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| id | path | required | integer | ID of the absence period to delete |
DELETE /company/time-offs/{id}
/company/time-offs/{id}
Gets an absence period for absences with **time unit** set to **days**.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| id | path | required | integer | Numeric `id` of the absence period |
GET /company/time-offs/{id}
/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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| 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]. |
GET /company/attendances
/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.
{
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AttendanceCreateRequest"
}
},
"application/x-www-form-urlencoded": {
"schema": {
"$ref": "#/components/schemas/NewAttendancePeriodParametersRequest"
}
}
},
"required": true,
"description": "List of attendance periods to create"
}
POST /company/attendances
/company/attendances/{id}
This endpoint is responsible for deleting attendance data for the company employees.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| id | path | required | integer | ID of the attendance period to delete |
| skip_approval | query | optional | boolean | Optional, default value is true. If set to false, the approval status of the attendance period will be "pending" if an approval rule is set for the attendances type. The respective approval flow will be triggered. |
DELETE /company/attendances/{id}
/company/attendances/{id}
This endpoint is responsible for updating attendance data for the company employees. Attributes are not required and if not specified, the current value will be used. It is not possible to change the employee id.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| id | path | required | integer | ID of the attendance period to update |
{
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AttendanceUpdateRequest"
}
}
},
"required": true,
"description": "Attendance period data to update. At least one of the properties (`date`, `start_time`, `end_time`, `break`, `comment`, `project_id`, `skip_approval`) is required."
}
PATCH /company/attendances/{id}
/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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| optional | ||||
| optional | ||||
| 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. |
GET /company/custom-reports/columns
/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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| optional | ||||
| optional | ||||
| 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. |
GET /company/custom-reports/reports
/company/custom-reports/reports/{report_id}
This endpoint provides you with the data of an existing Custom Report.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| optional | ||||
| optional | ||||
| 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. |
GET /company/custom-reports/reports/{report_id}
/company/document-categories
This endpoint is responsible for fetching all document categories of the company. The result contains a list of document categories.
GET /company/document-categories
/company/documents
This endpoint is responsible for uploading documents for the company employees.
{
"content": {
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/DocumentUploadRequest"
}
}
},
"description": "Data necessary for document upload."
}
POST /company/documents
/company/employees
List Company Employees
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| 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. |
| 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. <details> <summary><b>Examples with <code>updated_since</code> and <code>attributes[]</code>:</b></summary><br /> In an example company that has 17 employees:<br /><br /> <details> <summary> <code class="language-html">?updated_since=2022-12-24T08:15:30</code> will yield 10 employees that were recently updated: </summary> <p><pre class="prettyprint"><code language="json" class="language-json"> { "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" } } }, ... ], ... ... } </code></pre></p> </details><br /> <details> <summary> <code class="language-html">?attributes[]=first_name</code> will yield all 17 employees: </summary> <p><pre class="prettyprint"><code language="json" class="language-json"> { "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" } } } ] } </code></pre></p> </details><br /> <details> <summary> <code class="language-html">?attributes[]=first_name&updated_since=2022-12-24T08:15:30</code> will yield 3 employees, ones that had their <code>first_name</code> changed since <code>2022-12-24T08:15:30</code>: </summary> <p><pre class="prettyprint"><code language="json" class="language-json"> { "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" } } } ] } </code></pre></p> </details> </details> |
GET /company/employees
/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.
{
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EmployeesCreateEmployeeRequest"
}
},
"application/x-www-form-urlencoded": {
"schema": {
"$ref": "#/components/schemas/EmployeesCreateEmployeeRequest1"
}
}
}
}
POST /company/employees
/company/employees/attributes
Lists all the allowed atrributes per API credentials including custom (dynamic) attributes.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| optional | ||||
| optional |
GET /company/employees/attributes
/company/employees/custom-attributes
This endpoint is an alias for `/company/employees/attributes`.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| optional | ||||
| optional |
GET /company/employees/custom-attributes
/company/employees/{employee_id}
Show employee by ID
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| employee_id | path | required | integer | Numeric `id` of the employee |
GET /company/employees/{employee_id}
/company/employees/{employee_id}
Updates an existing employee. Note: Only the fields that are listed in the body example are updatable. Attributes that are not part of the sample request body but are present inside the request are ignored. It's not possible to update the Email field.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| employee_id | path | required | integer | Numeric `id` of the employee |
{
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EmployeesUpdateEmployeeFieldsRequest"
}
},
"application/x-www-form-urlencoded": {
"schema": {
"$ref": "#/components/schemas/EmployeesUpdateEmployeeFieldsRequest1"
}
}
}
}
PATCH /company/employees/{employee_id}
/company/employees/{employee_id}/absences/balance
Retrieve the absence balance for a specific employee
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| employee_id | path | required | integer | Numeric `id` of the employee |
GET /company/employees/{employee_id}/absences/balance
/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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| employee_id | path | required | integer | Numeric `id` of the employee |
| width | path | required | integer | Width of the image. Default is original size |
GET /company/employees/{employee_id}/profile-picture/{width}
/company/attendances/projects
Provides a list of all company projects.
GET /company/attendances/projects
/company/attendances/projects
Creates a project into the company account
{
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProjectsCreateProjectRequest"
}
}
}
}
POST /company/attendances/projects
/company/attendances/projects/{id}
Deletes a project from the company account
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| id | path | required | integer | Numeric `id` of the project |
DELETE /company/attendances/projects/{id}
/company/attendances/projects/{id}
Updates a project with the given data
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| id | path | required | integer | Numeric `id` of the project |
{
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProjectsUpdateDataRequest"
}
}
}
}
PATCH /company/attendances/projects/{id}
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
}
}
}
}
}
EmployeesCreateEmployeeRequest1
{
"type": "object",
"required": [
"employee[email]",
"employee[first_name]",
"employee[last_name]"
],
"properties": {
"employee[email]": {
"type": "string",
"description": "Employee email"
},
"employee[gender]": {
"enum": [
"male",
"female",
"diverse"
],
"type": "string",
"description": "Employee gender"
},
"employee[status]": {
"enum": [
"onboarding",
"active",
"leave",
"inactive"
],
"type": "string",
"description": "Employee status"
},
"employee[position]": {
"type": "string",
"description": "Employee position"
},
"employee[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"
},
"employee[last_name]": {
"type": "string",
"description": "Employee last name"
},
"employee[department]": {
"type": "string",
"description": "Employee department"
},
"employee[first_name]": {
"type": "string",
"description": "Employee first name"
},
"employee[supervisor_id]": {
"type": "number",
"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."
},
"employee[preferred_name]": {
"type": "string",
"description": "Employee preferred name"
},
"employee[weekly_working_hours]": {
"type": "number",
"description": "Employee weekly working hours"
}
}
}
EmployeesListAttributesResponse
{
"type": "object",
"example": {
"data": [
{
"key": "first_name",
"type": "standard",
"label": "First Name",
"universal_id": "first_name"
},
{
"key": "last_name",
"type": "standard",
"label": "Last Name",
"universal_id": "last_name"
},
{
"key": "dynamic_1",
"type": "standard",
"label": "IBAN",
"universal_id": "iban"
}
],
"success": true
},
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"example": "first_name"
},
"type": {
"type": "string",
"example": "standard"
},
"label": {
"type": "string",
"example": "First Name"
},
"universal_id": {
"type": "string",
"example": "first_name"
}
}
}
},
"success": {
"type": "boolean",
"example": true
}
}
}
EmployeesResponse
{
"allOf": [
{
"$ref": "#/components/schemas/Response"
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"example": "Employee"
},
"attributes": {
"$ref": "#/components/schemas/Employee"
}
}
}
},
"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 of Employees"
}
EmployeesShowProfilePictureResponse
{
"type": "string",
"format": "binary"
}
EmployeesUpdateEmployeeFieldsRequest
{
"type": "object",
"properties": {
"employee": {
"type": "object",
"properties": {
"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."
},
"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\". Update of the `hire_date` will not update employee status on its own (for that you'll need to update the `status` field)"
},
"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 and not the same as the one of the employee being updated, otherwise an error will be returned. If sent as null, will unset the employee's supervisor."
},
"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
}
}
}
}
}
EmployeesUpdateEmployeeFieldsRequest1
{
"type": "object",
"properties": {
"employee[gender]": {
"enum": [
"male",
"female",
"diverse"
],
"type": "string",
"description": "Employee gender"
},
"employee[status]": {
"enum": [
"onboarding",
"active",
"leave",
"inactive"
],
"type": "string",
"description": "Employee status"
},
"employee[position]": {
"type": "string",
"description": "Employee position"
},
"employee[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"
},
"employee[last_name]": {
"type": "string",
"description": "Employee last name"
},
"employee[department]": {
"type": "string",
"description": "Employee department"
},
"employee[first_name]": {
"type": "string",
"description": "Employee first name"
},
"employee[supervisor_id]": {
"type": "number",
"description": "Employee ID of the Supervisor to be assigned. It needs to belong to a current existing employee and not the same as the one of the employee being updated, otherwise an error will be returned. If sent as null, will unset the employee's supervisor."
},
"employee[preferred_name]": {
"type": "string",
"description": "Employee preferred name"
},
"employee[weekly_working_hours]": {
"type": "number",
"description": "Employee weekly working hours"
}
}
}
EntityAttribute
{
"type": "object",
"properties": {
"value": {
"type": "string",
"example": "IT"
},
"data_type": {
"enum": [
"ENTITY"
],
"type": "string"
},
"entity_id": {
"type": "string",
"example": 1
},
"employee_id": {
"type": "integer",
"example": 17
},
"attribute_id": {
"type": "string",
"example": "department"
}
}
}
EntityHistoricalAttribute
{
"type": "object",
"properties": {
"value": {
"type": "string",
"example": "IT"
},
"data_type": {
"enum": [
"ENTITY"
],
"type": "string"
},
"entity_id": {
"type": "string",
"example": 1
},
"employee_id": {
"type": "integer",
"example": 17
},
"attribute_id": {
"type": "string",
"example": "department"
},
"effective_date": {
"type": "string",
"example": "2021-01-01T00:00:00.000Z"
}
}
}
ErrorAbsenceResponse
{
"type": "object",
"title": "404 absence error",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"example": 404
},
"message": {
"example": "The absence period was not found."
}
}
},
"success": {
"type": "boolean",
"example": false
}
}
}
ErrorCreateAbsenceResponse
{
"type": "object",
"title": "Default error response",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"example": "The given data failed to pass validation."
}
}
},
"success": {
"type": "boolean",
"example": false
}
}
}
ErrorDetails
{
"type": "object",
"properties": {
"type": {
"type": "string",
"example": "search"
},
"_meta": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ErrorMeta"
}
},
"title": {
"type": "string",
"example": "Not Found"
},
"details": {
"type": "string",
"example": "Report not found"
}
}
}
ErrorInsertingAbsenceResponse
{
"type": "object",
"title": "400 absence error",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"example": 400
},
"message": {
"example": "Error when trying to insert absence period"
}
}
},
"success": {
"type": "boolean",
"example": false
}
}
}
ErrorMeta
{
"type": "object",
"properties": {
"field": {
"type": "string",
"example": "ID"
},
"description": {
"type": "string",
"example": "Report ID not found"
}
}
}
ErrorResponse
{
"type": "object",
"title": "Default error response",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"example": "Something went wrong"
}
}
},
"success": {
"type": "boolean",
"example": false
}
}
}
HolidayCalendar
{
"type": "object",
"properties": {
"type": {
"$ref": "#/components/schemas/TypeEnum"
},
"label": {
"example": "Holiday Calendar"
},
"value": {
"type": "object",
"properties": {
"type": {
"example": "HolidayCalendar"
},
"attributes": {
"type": "object",
"properties": {
"id": {
"type": "number",
"example": 1
},
"name": {
"example": "DE (Hamburg) Feiertage"
},
"state": {
"example": "Hamburg"
},
"country": {
"example": "DE"
}
}
}
}
},
"universal_id": {
"example": "holiday_calendar"
}
}
}
HourlyAbsence
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "61fe126b-a7b3-449a-b5ee-3865a6fcc546"
},
"end": {
"type": "string",
"format": "date-time",
"nullable": true
},
"start": {
"type": "string",
"format": "date-time"
},
"origin": {
"type": "string",
"example": "web"
},
"status": {
"type": "string",
"example": "approved"
},
"comment": {
"type": "string"
},
"employee": {
"$ref": "#/components/schemas/ShortEmployee"
},
"timezone": {
"type": "string",
"example": "Europe/Berlin"
},
"breakdowns": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AbsencePeriodBreakdown"
},
"description": "Breakdowns of effective duration by day of absence."
},
"created_at": {
"type": "string",
"example": "2017-01-17T10:32:18.000+01:00"
},
"created_by": {
"type": "integer",
"example": 1,
"description": "ID of the employee who created the absence period."
},
"updated_at": {
"type": "string",
"example": "2017-01-17T10:32:18.000+01:00"
},
"approved_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"certificate": {
"type": "object",
"properties": {
"status": {
"type": "string",
"example": "not-required"
}
}
},
"absence_type": {
"$ref": "#/components/schemas/AbsenceType"
},
"half_day_end": {
"type": "boolean"
},
"half_day_start": {
"type": "boolean"
},
"measurement_unit": {
"type": "string",
"example": "hours"
},
"effective_duration": {
"type": "integer",
"example": 16,
"description": "Period effective duration in minutes"
}
}
}
HourlyAbsencePeriodResponse
{
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response"
},
{
"type": "object",
"properties": {
"data": {
"type": "object",
"required": [
"type",
"attributes"
],
"properties": {
"type": {
"example": "AbsencePeriod"
},
"attributes": {
"$ref": "#/components/schemas/HourlyAbsence"
}
}
}
}
}
],
"title": "Absence Periods response"
}
HourlyAbsencePeriodResponseAttributes
{
"type": "object",
"required": [
"id",
"employee",
"absence_type_id",
"start",
"half_day_start",
"half_day_end",
"origin",
"status",
"certificate",
"created_by",
"effective_duration",
"created_at",
"updated_at",
"breakdowns"
],
"properties": {
"id": {
"type": "string",
"example": "9bba303f-0fbc-4514-9958-0befa21923fb"
},
"end": {
"type": "string",
"format": "date-time",
"nullable": true
},
"start": {
"type": "string",
"format": "date-time"
},
"origin": {
"enum": [
"web",
"api",
"mobile",
"slack",
"msteams"
],
"type": "string",
"example": "web",
"nullable": true
},
"status": {
"type": "string",
"example": "approved"
},
"comment": {
"type": "string"
},
"employee": {
"$ref": "#/components/schemas/ShortEmployee"
},
"breakdowns": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AbsencePeriodBreakdown"
},
"description": "Breakdowns of effective duration by day of absence."
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": "integer",
"example": 1,
"description": "ID of the employee who created the absence period."
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"approved_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"certificate": {
"type": "object",
"properties": {
"status": {
"type": "string",
"example": "not-required"
}
}
},
"half_day_end": {
"type": "boolean"
},
"half_day_start": {
"type": "boolean"
},
"absence_type_id": {
"$ref": "#/components/schemas/AbsenceType"
},
"measurement_unit": {
"enum": [
"minutes"
],
"type": "string",
"example": "minutes"
},
"effective_duration": {
"type": "integer",
"example": 60,
"description": "Period effective duration in minutes"
}
}
}
HourlyAbsencePeriodsResponse
{
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response"
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"type",
"attributes"
],
"properties": {
"type": {
"example": "AbsencePeriod"
},
"attributes": {
"$ref": "#/components/schemas/HourlyAbsence"
}
}
}
},
"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 Hourly Absence Periods response"
}
NewAttendancePeriodParametersRequest
{
"type": "object",
"title": "Create a New Attendance Period request",
"required": [
"attendances[][employee]",
"attendances[][date]",
"attendances[][start_time]",
"attendances[]break"
],
"properties": {
"project_id": {
"type": "integer",
"format": "int32",
"example": 5,
"nullable": true,
"description": "The ID of the project"
},
"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."
},
"attendances[]break": {
"type": "integer",
"format": "int32",
"minimum": 0,
"description": "Break in minutes"
},
"attendances[][date]": {
"type": "string",
"format": "date",
"example": "2020-01-31",
"description": "Attendance date. Format: yyyy-mm-dd"
},
"attendances[][comment]": {
"type": "string",
"nullable": true,
"description": "Optional comment"
},
"attendances[][employee]": {
"type": "integer",
"description": "Employee identifier"
},
"attendances[][end_time]": {
"type": "string",
"example": "12:00",
"pattern": "^\\d\\d:\\d\\d$",
"nullable": true,
"description": "End time. Format: hh:mm"
},
"attendances[][start_time]": {
"type": "string",
"example": "08:00",
"pattern": "^\\d\\d:\\d\\d$",
"description": "Start time. Format: hh:mm"
}
}
}
NewAttendancePeriodResponse
{
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response"
},
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "array",
"items": {
"type": "integer",
"example": 1
}
},
"message": {
"example": "Success"
}
}
}
}
}
]
}
Office
{
"type": "object",
"properties": {
"type": {
"$ref": "#/components/schemas/TypeEnum"
},
"label": {
"example": "Office"
},
"value": {
"type": "object",
"properties": {
"type": {
"type": "string",
"example": "Office"
},
"attributes": {
"type": "object",
"properties": {
"name": {
"example": "Munich"
}
}
}
}
},
"universal_id": {
"example": "office"
}
}
}
PerformanceKpi
{
"type": "object",
"properties": {
"performance_kpi_id": {
"type": "string",
"example": "kpi_123"
},
"performance_kpi_value": {
"type": "string",
"example": 14
}
}
}
PerformanceKpiAttribute
{
"type": "object",
"properties": {
"data_type": {
"enum": [
"PERFORMANCE_KPI"
],
"type": "string"
},
"employee_id": {
"type": "integer",
"example": 17
},
"attribute_id": {
"type": "string"
},
"performance_target_kpis": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PerformanceTarget"
}
}
}
}
PerformanceTarget
{
"type": "object",
"properties": {
"performance_target_id": {
"type": "string",
"example": 1
},
"performance_target_value": {
"type": "string",
"example": 20
}
}
}
PerformanceTargetAttribute
{
"type": "object",
"properties": {
"data_type": {
"enum": [
"PERFORMANCE_TARGET"
],
"type": "string"
},
"employee_id": {
"type": "integer",
"example": 17
},
"attribute_id": {
"type": "string",
"example": "performance_target_name"
},
"performance_targets": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PerformanceTarget"
}
}
}
}
PerformanceTargetKpi
{
"type": "object",
"properties": {
"performance_kpis": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PerformanceKpi"
}
},
"performance_target_id": {
"type": "string",
"example": "id_123"
}
}
}
Project
{
"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. The default value is false."
},
"created_at": {
"type": "string",
"format": "datetime",
"example": "2022-02-01T12:00:00.000+01:00"
},
"updated_at": {
"type": "string",
"format": "datetime",
"example": "2022-02-01T12:00:00.000+01:00"
}
}
}
}
}
ProjectsCreateProject400Response
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"name": {
"type": "array",
"items": {
"type": "string",
"example": "Project name cannot be empty"
}
}
}
},
"success": {
"type": "boolean",
"example": false
}
}
}
ProjectsCreateProjectRequest
{
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"example": "A project name"
},
"active": {
"type": "boolean",
"default": false,
"example": true
}
}
}
ProjectsCreateProjectResponse
{
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/Project"
},
"success": {
"type": "boolean"
}
}
}
ProjectsDeleteProjectResponse
{
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "Project 5 not found"
},
"success": {
"type": "boolean",
"example": false
}
}
}
ProjectsGetAllResponse
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Project"
}
},
"success": {
"type": "boolean"
}
}
}
ProjectsUpdateData400Response
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"active": {
"type": "array",
"items": {
"type": "string",
"example": "Active field needs to be of type boolean"
}
}
}
},
"success": {
"type": "boolean",
"example": false
}
}
}
ProjectsUpdateData404Response
{
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "Project 5 not found"
},
"success": {
"type": "boolean",
"example": false
}
}
}
ProjectsUpdateDataRequest
{
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "A project name"
},
"active": {
"type": "boolean",
"example": true,
"description": "Marks the availability of the project"
}
}
}
ProjectsUpdateDataResponse
{
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/Project"
},
"success": {
"type": "boolean"
}
}
}
PublicAPIException
{
"type": "array",
"items": {
"$ref": "#/components/schemas/CustomReportsErrorResponse"
}
}
PublicColumnAttributes
{
"type": "object",
"properties": {
"data_type": {
"type": "string",
"example": "TEXT"
},
"attribute_id": {
"type": "string",
"example": "first_name"
},
"human_readable": {
"type": "string",
"example": "First Name"
}
}
}
PublicColumnData
{
"type": "object",
"properties": {
"type": {
"type": "string",
"example": "Column"
},
"attributes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PublicColumnAttributes"
}
}
}
}
PublicHistoricalReportItemsAttributes
{
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "eb7482f3-2323-43e2-87ed-99d2399e8e22"
},
"name": {
"type": "string",
"example": "Department changes in the past year"
},
"type": {
"enum": [
"historical_data"
],
"type": "string",
"example": "historical_data"
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"employee_id": {
"type": "integer",
"example": 17
},
"historical_attributes": {
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/DefaultHistoricalAttribute"
},
{
"$ref": "#/components/schemas/EntityHistoricalAttribute"
},
{
"$ref": "#/components/schemas/DurationHistoricalAttribute"
},
{
"$ref": "#/components/schemas/CostCenterHistoricalAttribute"
},
{
"$ref": "#/components/schemas/SalaryHistoricalAttribute"
}
]
}
}
}
}
},
"status": {
"enum": [
"up_to_date",
"updating",
"update_failed"
],
"type": "string",
"example": "created"
},
"columns": {
"type": "array",
"items": {
"type": "string"
}
},
"filters": {
"type": "array",
"items": {
"type": "object",
"properties": {
"value": {
"type": "string",
"example": 1
},
"column": {
"type": "string",
"example": "office_id"
},
"comparison": {
"type": "string",
"example": "eq"
}
}
}
},
"end_date": {
"type": "string",
"format": "date-time",
"example": "2022-09-30"
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2022-04-10T17:32:28Z"
},
"start_date": {
"type": "string",
"format": "date-time",
"example": "2022-01-01"
},
"updated_at": {
"type": "string",
"format": "date-time",
"example": "2022-04-10T17:32:28Z"
},
"description": {
"type": "string",
"example": "Shows department changes of all employees over the past year"
},
"period_type": {
"enum": [
"fixed",
"today",
"yesterday",
"this_week",
"last_week",
"this_month",
"last_month",
"last_thirty_days",
"next_month",
"this_quarter",
"last_quarter",
"this_year",
"year_to_date",
"last_year",
"next_year"
],
"type": "string",
"example": "fixed"
},
"author_last_name": {
"type": "string",
"example": "Sirano",
"description": "Report author"
},
"author_first_name": {
"type": "string",
"example": "Robert",
"description": "Report author"
},
"data_refreshed_at": {
"type": "string",
"format": "date-time",
"example": "2022-04-10T17:32:28Z"
}
}
}
PublicListColumnsResponse
{
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/PublicColumnData"
},
"limit": {
"type": "integer"
},
"offset": {
"type": "integer"
},
"success": {
"type": "boolean"
},
"metadata": {
"$ref": "#/components/schemas/PublicReportMetaData"
}
}
}
PublicListReportsResponse
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PublicReportData"
}
},
"limit": {
"type": "integer"
},
"offset": {
"type": "integer"
},
"success": {
"type": "boolean"
},
"metadata": {
"$ref": "#/components/schemas/PublicReportMetaData"
}
}
}
PublicReportAttributes
{
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "eb7482f3-2323-43e2-87ed-99d2399e8e22"
},
"name": {
"type": "string",
"example": "Employee vacations past month"
},
"type": {
"enum": [
"point_in_time",
"historical_data",
"timeframe"
],
"type": "string",
"example": "point_in_time"
},
"status": {
"enum": [
"up_to_date",
"updating",
"update_failed"
],
"type": "string",
"example": "up_to_date"
},
"columns": {
"type": "array",
"items": {
"type": "string"
}
},
"filters": {
"type": "array",
"items": {
"type": "object",
"properties": {
"value": {
"type": "string",
"example": 1
},
"column": {
"type": "string",
"example": "office_id"
},
"comparison": {
"type": "string",
"example": "eq"
}
}
}
},
"end_date": {
"type": "string",
"format": "date",
"example": "2022-09-30"
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2022-04-10T17:32:28Z"
},
"start_date": {
"type": "string",
"format": "date",
"example": "2022-09-01"
},
"updated_at": {
"type": "string",
"format": "date-time",
"example": "2022-04-10T17:32:28Z"
},
"description": {
"type": "string",
"example": "Shows vacations of all employees that were taken past month"
},
"period_type": {
"enum": [
"fixed",
"today",
"last_day_of_this_month",
"this_year",
"last_month",
"last_thirty_days",
"this_month",
"year_to_date"
],
"type": "string",
"example": "fixed"
},
"author_last_name": {
"type": "string",
"example": "Sirano",
"description": "Report author"
},
"author_first_name": {
"type": "string",
"example": "Robert",
"description": "Report author"
},
"data_refreshed_at": {
"type": "string",
"format": "date-time",
"example": "2022-04-10T17:32:28Z"
}
}
}
PublicReportData
{
"type": "object",
"properties": {
"type": {
"type": "string",
"example": "Report"
},
"attributes": {
"$ref": "#/components/schemas/PublicReportAttributes"
}
}
}
PublicReportItemsAttributes
{
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "eb7482f3-2323-43e2-87ed-99d2399e8e22"
},
"name": {
"type": "string",
"example": "Employee vacations at a specific point in time"
},
"type": {
"enum": [
"point_in_time"
],
"type": "string",
"example": "point_in_time"
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"attributes": {
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/DefaultAttribute"
},
{
"$ref": "#/components/schemas/EntityAttribute"
},
{
"$ref": "#/components/schemas/DurationAttribute"
},
{
"$ref": "#/components/schemas/CostCenterAttribute"
},
{
"$ref": "#/components/schemas/AbsenceOverviewAttribute"
},
{
"$ref": "#/components/schemas/AbsencePeriodAttribute"
},
{
"$ref": "#/components/schemas/PerformanceTargetAttribute"
},
{
"$ref": "#/components/schemas/PerformanceKpiAttribute"
},
{
"$ref": "#/components/schemas/SalaryAttribute"
},
{
"$ref": "#/components/schemas/CompensationAttribute"
}
]
}
},
"employee_id": {
"type": "integer",
"example": 17
}
}
}
},
"status": {
"enum": [
"up_to_date",
"updating",
"update_failed"
],
"type": "string",
"example": "created"
},
"columns": {
"type": "array",
"items": {
"type": "string"
}
},
"filters": {
"type": "array",
"items": {
"type": "object",
"properties": {
"value": {
"type": "string",
"example": 1
},
"column": {
"type": "string",
"example": "office_id"
},
"comparison": {
"type": "string",
"example": "eq"
}
}
}
},
"end_date": {
"type": "string",
"format": "date-time",
"example": "2022-04-10"
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2022-04-10T17:32:28Z"
},
"start_date": {
"type": "string",
"format": "date-time",
"example": "2022-04-10"
},
"updated_at": {
"type": "string",
"format": "date-time",
"example": "2022-04-10T17:32:28Z"
},
"description": {
"type": "string",
"example": "Shows vacations of all employees on a specific date"
},
"period_type": {
"enum": [
"fixed",
"today",
"yesterday",
"last_day_of_this_week",
"last_day_of_last_week",
"last_day_of_this_month",
"last_day_of_last_month",
"last_day_of_this_quarter",
"last_day_of_last_quarter",
"last_day_of_this_year",
"last_day_of_last_year"
],
"type": "string",
"example": "fixed"
},
"author_last_name": {
"type": "string",
"example": "Sirano",
"description": "Report author"
},
"author_first_name": {
"type": "string",
"example": "Robert",
"description": "Report author"
},
"data_refreshed_at": {
"type": "string",
"format": "date-time",
"example": "2022-04-10T17:32:28Z"
}
}
}
PublicReportItemsData
{
"type": "object",
"properties": {
"type": {
"type": "string",
"example": "Report"
},
"attributes": {
"oneOf": [
{
"$ref": "#/components/schemas/PublicReportItemsAttributes"
},
{
"$ref": "#/components/schemas/PublicTimeframeReportItemsAttributes"
},
{
"$ref": "#/components/schemas/PublicHistoricalReportItemsAttributes"
}
]
}
}
}
PublicReportMetaData
{
"type": "object",
"properties": {
"total_pages": {
"type": "integer"
},
"current_page": {
"type": "integer"
},
"total_elements": {
"type": "integer"
}
}
}
PublicReportResponse
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PublicReportItemsData"
}
},
"limit": {
"type": "integer"
},
"offset": {
"type": "integer",
"deprecated": true
},
"success": {
"type": "boolean"
},
"metadata": {
"$ref": "#/components/schemas/PublicReportMetaData"
}
}
}
PublicTimeframeReportItemsAttributes
{
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "eb7482f3-2323-43e2-87ed-99d2399e8e22"
},
"name": {
"type": "string",
"example": "Employee vacations past month"
},
"type": {
"enum": [
"timeframe"
],
"type": "string",
"example": "timeframe"
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"attributes": {
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/DefaultAttribute"
},
{
"$ref": "#/components/schemas/EntityAttribute"
},
{
"$ref": "#/components/schemas/DurationAttribute"
},
{
"$ref": "#/components/schemas/CostCenterAttribute"
},
{
"$ref": "#/components/schemas/AbsenceOverviewAttribute"
},
{
"$ref": "#/components/schemas/AbsencePeriodAttribute"
},
{
"$ref": "#/components/schemas/PerformanceTargetAttribute"
},
{
"$ref": "#/components/schemas/PerformanceKpiAttribute"
},
{
"$ref": "#/components/schemas/SalaryAttribute"
},
{
"$ref": "#/components/schemas/CompensationAttribute"
}
]
}
},
"employee_id": {
"type": "integer",
"example": 17
}
}
}
},
"status": {
"enum": [
"up_to_date",
"updating",
"update_failed"
],
"type": "string",
"example": "created"
},
"columns": {
"type": "array",
"items": {
"type": "string"
}
},
"filters": {
"type": "array",
"items": {
"type": "object",
"properties": {
"value": {
"type": "string",
"example": 1
},
"column": {
"type": "string",
"example": "office_id"
},
"comparison": {
"type": "string",
"example": "eq"
}
}
}
},
"end_date": {
"type": "string",
"format": "date-time",
"example": "2022-04-10"
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2022-04-10T17:32:28Z"
},
"start_date": {
"type": "string",
"format": "date-time",
"example": "2022-04-01"
},
"updated_at": {
"type": "string",
"format": "date-time",
"example": "2022-04-10T17:32:28Z"
},
"description": {
"type": "string",
"example": "Shows vacations of all employees that were taken past month"
},
"period_type": {
"enum": [
"fixed",
"today",
"yesterday",
"this_week",
"last_week",
"this_month",
"last_month",
"last_thirty_days",
"next_month",
"this_quarter",
"last_quarter",
"this_year",
"year_to_date",
"last_year",
"next_year"
],
"type": "string",
"example": "fixed"
},
"author_last_name": {
"type": "string",
"example": "Sirano",
"description": "Report author"
},
"author_first_name": {
"type": "string",
"example": "Robert",
"description": "Report author"
},
"data_refreshed_at": {
"type": "string",
"format": "date-time",
"example": "2022-04-10T17:32:28Z"
}
}
}
Response
{
"type": "object",
"title": "Default response object",
"required": [
"success",
"data"
],
"properties": {
"data": {
"type": "object"
},
"success": {
"type": "boolean"
}
}
}
SalaryAttribute
{
"type": "object",
"properties": {
"amount": {
"type": "string",
"example": 12.2
},
"data_type": {
"enum": [
"SALARY"
],
"type": "string"
},
"employee_id": {
"type": "integer",
"example": 17
},
"attribute_id": {
"type": "string",
"example": "salary_123"
},
"currency_symbol": {
"type": "string",
"example": "$"
}
}
}
SalaryHistoricalAttribute
{
"type": "object",
"properties": {
"amount": {
"type": "string",
"example": 12.2
},
"data_type": {
"enum": [
"SALARY"
],
"type": "string"
},
"employee_id": {
"type": "integer",
"example": 17
},
"attribute_id": {
"type": "string",
"example": "salary_123"
},
"effective_date": {
"type": "string",
"example": "2021-01-01T00:00:00.000Z"
},
"currency_symbol": {
"type": "string",
"example": "$"
}
}
}
ShortEmployee
{
"type": "object",
"properties": {
"type": {
"type": "string",
"example": "Employee"
},
"attributes": {
"type": "object",
"properties": {
"id": {
"type": "object",
"properties": {
"type": {
"$ref": "#/components/schemas/TypeEnum"
},
"label": {
"example": 1
},
"value": {
"example": "id"
},
"universal_id": {
"example": "id"
}
}
},
"email": {
"type": "object",
"properties": {
"type": {
"$ref": "#/components/schemas/TypeEnum"
},
"label": {
"example": "Email"
},
"value": {
"example": "michael.dou@personio.de"
},
"universal_id": {
"example": "email"
}
}
},
"last_name": {
"type": "object",
"properties": {
"type": {
"$ref": "#/components/schemas/TypeEnum"
},
"label": {
"example": "Last Name"
},
"value": {
"example": "Dou"
},
"universal_id": {
"example": "last_name"
}
}
},
"first_name": {
"type": "object",
"properties": {
"type": {
"$ref": "#/components/schemas/TypeEnum"
},
"label": {
"example": "First Name"
},
"value": {
"example": "Michael"
},
"universal_id": {
"example": "first_name"
}
}
}
}
}
}
}
Supervisor
{
"type": "object",
"properties": {
"label": {
"type": "string",
"example": "Supervisor"
},
"value": {
"$ref": "#/components/schemas/ShortEmployee"
}
}
}
Team
{
"type": "object",
"properties": {
"type": {
"$ref": "#/components/schemas/TypeEnum"
},
"label": {
"example": "Team"
},
"value": {
"type": "object",
"properties": {
"type": {
"type": "string",
"example": "Team"
},
"attributes": {
"type": "object",
"properties": {
"name": {
"example": "Management"
}
}
}
}
},
"universal_id": {
"example": "team"
}
}
}
TimeOffTypeResource
{
"type": "object",
"title": "Type of time-off resource",
"properties": {
"type": {
"enum": [
"TimeOffType"
],
"type": "string",
"description": "Time-off type resource name"
},
"attributes": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"example": 1,
"description": "identifier"
},
"name": {
"type": "string",
"example": "Paid vacation"
},
"unit": {
"enum": [
"day",
"hour"
],
"type": "string",
"example": "day"
},
"category": {
"enum": [
"family_care",
"maternity_parental_leave",
"child_care",
"short_time_allowance",
"quarantine",
"lockout",
"irrevocable_exemption",
"sick_leave",
"voluntary_military_service",
"unlawful_strike",
"lawful_strike",
"paid_vacation",
"unpaid_vacation",
"unexcused_absence",
"offsite_work",
"other",
"undefined"
],
"type": "string",
"example": "offsite_work",
"nullable": true
},
"legacy_category": {
"enum": [
"family_care_sick_leave",
"individual_prohibition_of_employment",
"maternity_protection_period",
"other",
"paid_vacation",
"parental_leave",
"sick_leave",
"lawful_strike",
"unlawful_strike",
"treatment",
"unexcused_absence",
"unpaid_vacation",
"voluntary_military_service",
"offsite_work",
"family_care_long_term",
"paid_child_sick",
"unpaid_child_sick",
"undefined"
],
"type": "string",
"example": "offsite_work",
"nullable": true
},
"approval_required": {
"type": "boolean",
"example": true
},
"substitute_option": {
"enum": [
"disabled",
"optional",
"required"
],
"type": "string",
"example": "optional"
},
"certification_required": {
"type": "boolean",
"example": false
},
"half_day_requests_enabled": {
"type": "boolean",
"example": true
},
"certification_submission_timeframe": {
"type": "integer",
"example": 2,
"description": "The timeframe in days under which the employee needs to submit the certification"
}
}
}
}
}
TypeEnum
{
"enum": [
"standard",
"date",
"integer",
"decimal",
"list",
"link",
"tags",
"multiline"
],
"type": "string",
"example": "standard"
}
UpdatedAttendanceResponse
{
"type": "object",
"title": "Default response object",
"properties": {
"data": {
"type": "object",
"properties": {
"message": {
"example": "The attendance period was updated."
}
}
},
"success": {
"type": "boolean"
}
}
}
WorkSchedule
{
"type": "object",
"properties": {
"type": {
"$ref": "#/components/schemas/TypeEnum"
},
"label": {
"example": "WorkSchedule"
},
"value": {
"type": "object",
"properties": {
"type": {
"example": "WorkSchedule"
},
"attributes": {
"type": "object",
"properties": {
"id": {
"type": "number",
"example": 1
},
"name": {
"example": "Standard Hours"
},
"friday": {
"example": "08:30",
"pattern": "^\\d\\d:\\d\\d$"
},
"monday": {
"example": "08:30",
"pattern": "^\\d\\d:\\d\\d$"
},
"sunday": {
"example": "00:00",
"pattern": "^\\d\\d:\\d\\d$"
},
"tuesday": {
"example": "08:30",
"pattern": "^\\d\\d:\\d\\d$"
},
"saturday": {
"example": "00:00",
"pattern": "^\\d\\d:\\d\\d$"
},
"thursday": {
"example": "08:30",
"pattern": "^\\d\\d:\\d\\d$"
},
"wednesday": {
"example": "08:30",
"pattern": "^\\d\\d:\\d\\d$"
}
}
}
}
},
"universal_id": {
"example": "work_schedule"
}
}
}