openapi: 3.0.0
info:
version: "1.0"
title: Personnel Data
description: API for reading and writing personnel data including data about attendances, absences, documents, etc
x-readme:
samples-languages:
- "curl"
- "python"
- "ruby"
- "java"
- "php"
- "node"
paths:
/company/employees:
parameters:
- $ref: "#/components/parameters/XPersonioPartnerID"
- $ref: "#/components/parameters/XPersonioAppID"
get:
security:
- BearerAuth: []
tags:
- Employees
parameters:
- name: limit
in: query
required: false
description: Pagination attribute to limit the number of employees returned per page.
schema:
type: integer
minimum: 1
default: 10
example: 10
- name: offset
in: query
required: false
description: Pagination attribute to identify the first item in the collection to return.
schema:
type: integer
minimum: 0
default: 0
example: 0
- name: email
in: query
required: false
description: "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."
schema:
type: string
- name: attributes[]
in: query
description: |-
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.
example: "?attributes[]=first_name&attributes[]=last_name"
required: false
schema:
type: array
items:
type: string
example: ["first_name", "last_name"]
- name: updated_since
in: query
required: false
description: >2- # indentation is 2 spaces (so code is aligned); strip LF at the end
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) or `YYYY-MM-DD`. NOTE: when using the `updated_since` filter, the `email`, `limit`, and `offset` parameters are ignored.
Examples with updated_since
and attributes[]
:
In an example company that has 17 employees:
?updated_since=2022-12-24T08:15:30
will yield 10 employees that were recently updated:
{
"success": true,
"metadata": {
"total_elements": 10,
"current_page": 0,
"total_pages": 10
},
"offset": 0,
"limit": 1,
"data": [
{
"type": "Employee",
"attributes": {
"id": {
"label": "ID",
"value": 1,
"type": "integer",
"universal_id": "id"
},
"first_name": {
"label": "First name",
"value": "Alexander",
"type": "standard",
"universal_id": "first_name"
},
"last_name": {
"label": "Last name",
"value": "Bergmann",
"type": "standard",
"universal_id": "last_name"
},
"email": {
"label": "Email",
"value": "alexander.bergmann@demo.com",
"type": "standard",
"universal_id": "email"
}
}
}, ...
],
...
...
}
?attributes[]=first_name
will yield all 17 employees:
{
"success": true,
"metadata": {
"total_elements": 17,
"current_page": 0,
"total_pages": 17
},
"offset": 0,
"limit": 1,
"data": [
{
"type": "Employee",
"attributes": {
"id": {
"label": "ID",
"value": 1,
"type": "integer",
"universal_id": "id"
},
"first_name": {
"label": "First name",
"value": "Alexander",
"type": "standard",
"universal_id": "first_name"
}
}
}
]
}
?attributes[]=first_name&updated_since=2022-12-24T08:15:30
will yield 3 employees, ones that had their first_name
changed since 2022-12-24T08:15:30
:
{
"success": true,
"metadata": {
"total_elements": 3,
"current_page": 0,
"total_pages": 3
},
"offset": 0,
"limit": 1,
"data": [
{
"type": "Employee",
"attributes": {
"id": {
"label": "ID",
"value": 1,
"type": "integer",
"universal_id": "id"
},
"first_name": {
"label": "First name",
"value": "Alexander",
"type": "standard",
"universal_id": "first_name"
}
}
}
]
}
example: "2022-12-24T08:15:30"
schema:
type: string
example: 2022-12-24T08:15:30
description: List Company Employees
summary: List Employees
responses:
"200":
description: ""
content:
application/json:
schema:
$ref: "#/components/schemas/EmployeesResponse"
post:
security:
- BearerAuth: []
tags:
- Employees
summary: Create an Employee
description: >
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.
requestBody:
content:
application/json:
schema:
type: object
properties:
employee:
type: object
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.
first_name:
type: string
example: "John"
last_name:
type: string
example: "Dou"
preferred_name:
type: string
example: "John Dou"
gender:
type: string
example: male
position:
type: string
example: developer
subcompany:
type: string
description: The subcompany employee belongs to. Should be predefined in Personio. Otherwise will be ignored with showing meta error in the response.
example: ACME
department:
type: string
description: The department employee belongs to. Should be predefined in Personio. Otherwise will be ignored with showing meta error in the response.
example: IT
office:
type: string
description: The office employee belongs to. Should be predefined in Personio. Otherwise will be ignored with showing meta error in the response.
example: Madrid
hire_date:
type: string
example: '2020-01-31'
format: date
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."
pattern: ^\d{4}-\d{2}-\d{2}$
weekly_working_hours:
type: number
example: 40
status:
type: string
description: "Status of the employee. Overrides the status determined based on the value of `hire_date`."
example: "active"
"supervisor_id":
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.
type: number
example: 5
custom_attributes:
type: object
properties:
dynamic_{{ field uid }}:
type: string
description: Dynamic field, represented by unique id.
example: "German"
required:
- email
- first_name
- last_name
application/x-www-form-urlencoded:
schema:
type: object
properties:
"employee[email]":
description: Employee email
type: string
"employee[first_name]":
description: Employee first name
type: string
"employee[last_name]":
description: Employee last name
type: string
"employee[preferred_name]":
description: Employee preferred name
type: string
"employee[gender]":
description: Employee gender
type: string
enum:
- male
- female
- diverse
"employee[position]":
description: Employee position
type: string
"employee[department]":
description: Employee department
type: string
"employee[hire_date]":
type: string
example: '2020-01-31'
format: date
description: "Employee hire date. Format: yyyy-mm-dd"
pattern: ^\d{4}-\d{2}-\d{2}$
"employee[weekly_working_hours]":
description: Employee weekly working hours
type: number
"employee[supervisor_id]":
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.
type: number
"employee[status]":
description: Employee status
type: string
enum:
- onboarding
- active
- leave
- inactive
required:
- employee[email]
- employee[first_name]
- employee[last_name]
responses:
"200":
description: Successful creation of a employee
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/EmployeeCreatedResponse"
examples:
response:
value:
success: true
data:
id: 81723
message: "success"
"422":
description: Employee creation failed due to invalid payload
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/EmployeeCreationErrorResponse"
examples:
response:
value:
success: false
error:
code: 422
message: "Supervisor with ID 1 not found"
/company/employees/{employee_id}:
parameters:
- $ref: "#/components/parameters/XPersonioPartnerID"
- $ref: "#/components/parameters/XPersonioAppID"
patch:
security:
- BearerAuth: []
tags:
- Employees
summary: Update Employee by ID
description: >
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.
parameters:
- name: employee_id
in: path
required: true
description: Numeric `id` of the employee
schema:
type: integer
format: int32
requestBody:
content:
application/json:
schema:
type: object
properties:
employee:
type: object
properties:
first_name:
type: string
example: "John"
last_name:
type: string
example: "Dou"
preferred_name:
type: string
example: "John Dou"
gender:
type: string
example: male
position:
type: string
example: developer
subcompany:
type: string
description: The subcompany employee belongs to. Should be predefined in Personio. Otherwise will be ignored with showing meta error in the response.
example: ACME
department:
type: string
description: The department employee belongs to. Should be predefined in Personio. Otherwise will be ignored with showing meta error in the response.
example: IT
office:
type: string
description: The office employee belongs to. Should be predefined in Personio. Otherwise will be ignored with showing meta error in the response.
example: Madrid
hire_date:
type: string
example: '2020-01-31'
format: date
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)"
pattern: ^\d{4}-\d{2}-\d{2}$
weekly_working_hours:
type: number
example: 40
status:
type: string
description: "Status of the employee."
example: "active"
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.
example: 5
custom_attributes:
type: object
properties:
dynamic_{{ field uid }}:
type: string
description: Dynamic field, represented by unique id.
example: "German"
application/x-www-form-urlencoded:
schema:
type: object
properties:
"employee[first_name]":
description: Employee first name
type: string
"employee[last_name]":
description: Employee last name
type: string
"employee[preferred_name]":
description: Employee preferred name
type: string
"employee[gender]":
description: Employee gender
type: string
enum:
- male
- female
- diverse
"employee[position]":
description: Employee position
type: string
"employee[department]":
description: Employee department
type: string
"employee[hire_date]":
type: string
example: '2020-01-31'
format: date
description: "Employee hire date. Format: yyyy-mm-dd"
pattern: ^\d{4}-\d{2}-\d{2}$
"employee[weekly_working_hours]":
description: Employee weekly working hours
type: number
"employee[supervisor_id]":
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.
type: number
"employee[status]":
description: Employee status
type: string
enum:
- onboarding
- active
- leave
- inactive
responses:
"200":
description: Employee is updated
content:
application/json:
schema:
$ref: "#/components/schemas/EmployeeUpdatedResponse"
"422":
description: Employee update failed due to invalid payload
content:
application/json:
schema:
$ref: "#/components/schemas/EmployeeUpdateErrorResponse"
get:
security:
- BearerAuth: []
tags:
- Employees
description: Get Employee by ID
summary: Get Employee by ID
parameters:
- name: employee_id
in: path
required: true
description: Numeric `id` of the employee
schema:
type: integer
format: int32
responses:
"200":
description: ""
content:
application/json:
schema:
$ref: "#/components/schemas/EmployeeResponse"
examples:
response:
value:
success: true
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
preferred_name:
label: Name (preferred)
value: Alexander Bergmann
type: standard
universal_id: preferred_name
email:
label: Email
value: alexander.bergmann@demo.email
type: standard
universal_id: email
gender:
label: Gender
value: male
type: standard
universal_id: gender
status:
label: Status
value: active
type: standard
universal_id: status
position:
label: Position
value: CTO
type: standard
universal_id: position
supervisor:
label: Supervisor
value:
type: Employee
attributes:
id:
label: ID
value: 2
type: integer
universal_id: id
type: standard
universal_id: supervisor
employment_type:
label: Employment type
value: external
type: standard
universal_id: employment_type
weekly_working_hours:
label: Weekly hours
value: '40'
type: standard
universal_id: weekly_working_hours
hire_date:
label: Hire date
value: 2014-11-09T00:00:00+01:00
type: date
universal_id: hire_date
contract_end_date:
label: Contract ends
value: null
type: date
universal_id: contract_end_date
termination_date:
label: Termination date
value: null
type: date
universal_id: termination_date
termination_type:
label: Termination type
value: null
type: standard
universal_id: termination_type
termination_reason:
label: Termination reason
value: null
type: standard
universal_id: termination_reason
probation_period_end:
label: Probation period end
value: null
type: date
universal_id: probation_period_end
created_at:
label: created_at
value: '2017-05-23T09:49:03+02:00'
type: date
universal_id: created_at
last_modified_at:
label: Last modified
value: '2020-11-18T17:33:55+01:00'
type: date
universal_id: last_modified_at
subcompany:
label: Subcompany
value:
type: Subcompany
attributes:
id: 7033
name: CS Demo GmbH
type: standard
universal_id: subcompany
office:
label: Office
value:
type: Office
attributes:
id: 131014
name: Munich
type: standard
universal_id: office
department:
label: Department
value:
type: Department
attributes:
id: 281521
name: Customer Support
type: standard
universal_id: department
cost_centers:
label: Cost center
value:
- type: CostCenter
attributes:
id: 82957
name: Cost center 1
percentage: 100
type: standard
universal_id: cost_centers
holiday_calendar:
label: Public holidays
value:
type: HolidayCalendar
attributes:
id: 2
name: Deutschland (Bayern) Feiertage
country: DE
state: Bayern
type: standard
universal_id: holiday_calendar
absence_entitlement:
label: Absence entitlement
value:
- type: TimeOffType
attributes:
id: 113437
name: Paid vacation
category: paid_vacation
entitlement: 24
type: standard
universal_id: absence_entitlement
work_schedule:
label: Work schedule
value:
type: WorkSchedule
attributes:
id: 97188
name: Full-time, 40 hours without time tracking, (mon,tue,wed,thu,fri)
valid_from:
monday: '08:00'
tuesday: '08:00'
wednesday: '08:00'
thursday: '08:00'
friday: '08:00'
saturday: '00:00'
sunday: '00:00'
type: standard
universal_id: work_schedule
fix_salary:
label: Fix salary
value: 3000
type: decimal
universal_id: fix_salary
currency: EUR
fix_salary_interval:
label: Salary interval
value: monthly
type: standard
universal_id: fix_salary_interval
hourly_salary:
label: Hourly salary
value: 0
type: decimal
universal_id: hourly_salary
currency: EUR
last_working_day:
label: Last day of work
value:
type: date
universal_id: last_working_day
profile_picture:
label: Profile Picture
value: https://api.personio.de/v1/company/employees/1132888/profile-picture
type: standard
universal_id: profile_picture
team:
label: Team
value:
type: Team
attributes:
id: 59026
name: T_X
type: standard
universal_id: team
dynamic_24407:
label: Titel
value: Dr
universal_id: null
type: standard
dynamic_21827:
label: IBAN
value: DE98 8989 9898 0000 8989 00
universal_id: iban
type: standard
dynamic_33400:
label: Anniversary Date
value: 2021-01-01
universal_id: null
type: date
dynamic_180883:
label: Birthday
value: 1983-08-18
universal_id: date_of_birth
type: date
"404":
description: ""
content:
application/json:
schema:
$ref: "#/components/schemas/Employee404ErrorResponse"
examples:
response:
value:
success: false
error:
code: 404
message: 'Es ist ein Problem aufgetreten '
/company/employees/{employee_id}/absences/balance:
parameters:
- $ref: "#/components/parameters/XPersonioPartnerID"
- $ref: "#/components/parameters/XPersonioAppID"
get:
security:
- BearerAuth: []
tags:
- Employees
description: Retrieve the absence balance for a specific employee
summary: Get Absence Balance for Employee
parameters:
- name: employee_id
in: path
required: true
description: Numeric `id` of the employee
schema:
type: integer
format: int32
responses:
"200":
description: ""
content:
application/json:
schema:
$ref: "#/components/schemas/EmployeeAbsenceBalance"
"404":
description: ""
content:
application/json:
schema:
$ref: "#/components/schemas/Employee404ErrorResponse"
examples:
response:
value:
success: false
error:
code: 404
message: 'Es ist ein Problem aufgetreten '
/company/employees/custom-attributes:
get:
security:
- BearerAuth: []
tags:
- Employees
description: "This endpoint is an alias for `/company/employees/attributes`."
summary: List Allowed Custom Attributes
parameters:
- $ref: "#/components/parameters/XPersonioPartnerID"
- $ref: "#/components/parameters/XPersonioAppID"
responses:
"200":
description: "Please refer to `/company/employees/attributes`"
/company/employees/attributes:
get:
security:
- BearerAuth: []
tags:
- Employees
description: Lists all the allowed atrributes per API credentials including custom (dynamic) attributes.
summary: List Allowed Attributes
parameters:
- $ref: "#/components/parameters/XPersonioPartnerID"
- $ref: "#/components/parameters/XPersonioAppID"
responses:
"200":
description: ""
content:
application/json:
examples:
response:
value:
success: true
data:
- key: first_name
label: First Name
type: standard
universal_id: first_name
options: []
- key: last_name
label: Last Name
type: standard
universal_id: last_name
options: []
- key: dynamic_1
label: IBAN
type: standard
universal_id: iban
options: []
- key: dynamic_2
label: Marital status
type: list
universal_id: null
options: [
"married",
"single",
]
- key: dynamic_3
label: Language Skills
type: tags
universal_id: null
options: [
"English",
"French",
"Spanish",
"German"
]
/company/employees/{employee_id}/profile-picture/{width}:
parameters:
- $ref: "#/components/parameters/XPersonioPartnerID"
- $ref: "#/components/parameters/XPersonioAppID"
get:
security:
- BearerAuth: []
tags:
- Employees
description: "Show employee's profile picture. If profile picture is missing, the 404 error will be thrown. The `Profile Picture` attribute has to be whitelisted."
summary: Get Employee Profile Picture
parameters:
- name: employee_id
in: path
required: true
description: Numeric `id` of the employee
schema:
type: integer
format: int32
- name: width
in: path
required: true
description: Width of the image. Default is original size
schema:
type: integer
format: int32
responses:
"200":
description: OK
content:
image/png:
schema:
type: string
format: binary
"404":
description: "When the employee doesn't exist or employee doesn't have profile picture set or Profile Picture attribute is not whitelisted, this error occurs."
content:
application/json:
schema:
$ref: "#/components/schemas/Employee404ErrorResponse"
examples:
response:
value:
success: false
error:
code: 404
message: 'Etwas ist schiefgelaufen ...'
/company/attendances:
parameters:
- $ref: "#/components/parameters/XPersonioPartnerID"
- $ref: "#/components/parameters/XPersonioAppID"
get:
security:
- BearerAuth: []
tags:
- Attendances
description: 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.
summary: List Attendances
parameters:
- name: start_date
in: query
required: true
description: 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
schema:
type: string
format: date
- name: end_date
in: query
required: true
description: 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.
schema:
type: string
format: date
- name: updated_from
in: query
required: false
description: 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.
schema:
type: string
format: datetime
- name: updated_to
in: query
required: false
schema:
type: string
format: datetime
description: 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.
- name: includePending
in: query
required: false
description: 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.
schema:
type: boolean
- name: employees[]
in: query
required: false
description: A list of Personio employee ID's to filter the results. The result filters including only attendances of provided employees.
explode: true
schema:
type: array
items:
type: integer
example: ?employees[]=1&employees[]=2
allowReserved: true
- name: limit
in: query
required: false
description: Pagination attribute to limit how many attendances are per page
schema:
type: integer
minimum: 1
default: 200
- name: offset
in: query
required: false
description: 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].
schema:
type: integer
minimum: 0
default: 0
responses:
"200":
description: "The Attendance periods matching the provided filters"
content:
application/json:
schema:
$ref: "#/components/schemas/AttendancePeriodsResponse"
examples:
response:
value:
success: true
metadata:
total_elements: 2
current_page: 0
total_pages: 3
offset: 0
limit: 200
data:
- id: 1234
type: AttendancePeriod
attributes:
employee: 325659
date: '2017-01-17'
start_time: '09:00'
end_time: '18:00'
updated_at: '2017-01-17T16:41:08+00:00'
status: 'confirmed'
break: 50
comment: I was super productive
is_holiday: false
is_on_time_off: false,
project:
id: 567
type: "Project"
attributes:
name: "A project name"
active: true
- id: 1235
type: AttendancePeriod
attributes:
employee: 325660
date: '2017-01-18'
start_time: '09:30'
end_time: '18:30'
updated_at: '2017-01-18T16:41:08+01:00'
status: 'pending'
break: 60
comment: I wasn't productive
is_holiday: false
is_on_time_off: true
project: null
"401":
$ref: "#/components/responses/401UnauthorizedResponse"
"403":
$ref: "#/components/responses/403ForbiddenResponse"
post:
security:
- BearerAuth: []
tags:
- Attendances
description: 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.
summary: Create an Attendance
requestBody:
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/AttendanceCreateRequest"
application/x-www-form-urlencoded:
schema:
$ref: "#/components/schemas/NewAttendancePeriodParametersRequest"
description: List of attendance periods to create
required: true
responses:
"200":
description: The attendance periods are successfully created
content:
application/json:
schema:
$ref: "#/components/schemas/NewAttendancePeriodResponse"
examples:
response:
value:
success: true
data:
id: [
1,
2,
]
message: 'success'
"401":
$ref: "#/components/responses/401UnauthorizedResponse"
"403":
$ref: "#/components/responses/403ForbiddenResponse"
"400":
description: Invalid request
content:
application/json:
schema:
$ref: "#/components/schemas/AttendanceCreateUpdate400ErrorResponse"
examples:
response:
value:
success: false
error:
code: 400
message: 'Error when trying to insert Attendances periods rows'
detailed_message: [
{
success: true,
error_msg: null,
id: 1,
employee: 1234,
date: "2017-01-01",
start_time: "09:00",
end_time: "18:00",
break: 60,
comment: "",
project_id: 5
},
{
success: false,
error_msg: "Existing overlapping attendances periods",
id: null,
employee: 1234,
date: "2017-01-01",
start_time: "09:00",
end_time: "18:00",
break: 60,
comment: "",
project_id: null
}
]
/company/attendances/{id}:
parameters:
- $ref: "#/components/parameters/XPersonioPartnerID"
- $ref: "#/components/parameters/XPersonioAppID"
delete:
security:
- BearerAuth: []
tags:
- Attendances
description: This endpoint is responsible for deleting attendance data for the
company employees.
summary: Delete Attendance by ID
parameters:
- name: id
in: path
description: ID of the attendance period to delete
required: true
schema:
type: integer
format: int32
- name: skip_approval
in: query
required: false
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."
schema:
type: boolean
default: true
responses:
"200":
description: Success response
content:
application/json:
schema:
$ref: "#/components/schemas/DeletedAttendanceResponse"
examples:
response:
value:
success: true
data:
message: 'The attendance period was deleted.'
"400":
description: "Bad Request"
content:
application/json:
schema:
$ref: "#/components/schemas/AttendanceDelete400ErrorResponse"
examples:
response:
value:
success: false
error:
code: 400
message: 'Bad Request'
"401":
$ref: "#/components/responses/401UnauthorizedResponse"
"403":
$ref: "#/components/responses/403ForbiddenResponse"
"404":
description: Not Found
content:
application/json:
schema:
$ref: "#/components/schemas/Attendance404ErrorResponse"
examples:
response:
value:
success: false
error:
code: 404
message: 'The attendance period was not found.'
patch:
security:
- BearerAuth: []
tags:
- Attendances
description: 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.
summary: Update Attendance by ID
parameters:
- name: id
in: path
description: ID of the attendance period to update
required: true
schema:
type: integer
format: int32
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/AttendanceUpdateRequest"
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.
required: true
responses:
"200":
description: Success response
content:
application/json:
schema:
$ref: "#/components/schemas/UpdatedAttendanceResponse"
examples:
response:
value:
success: true
data:
message: The attendance period was updated.
"400":
description: "Bad Request"
content:
application/json:
schema:
$ref: "#/components/schemas/AttendanceCreateUpdate400ErrorResponse"
examples:
response:
value:
success: false
error:
code: 400
message: Error when trying to insert Attendances periods rows.
"401":
$ref: "#/components/responses/401UnauthorizedResponse"
"403":
$ref: "#/components/responses/403ForbiddenResponse"
"404":
description: Not found response
content:
application/json:
schema:
$ref: "#/components/schemas/Attendance404ErrorResponse"
examples:
response:
value:
success: false
error:
code: 404
message: 'The attendance period was not found.'
/company/attendances/projects:
parameters:
- $ref: "#/components/parameters/XPersonioPartnerID"
- $ref: "#/components/parameters/XPersonioAppID"
get:
security:
- BearerAuth: []
tags:
- Projects
description: Provides a list of all company projects.
summary: List Projects
responses:
"200":
description: List of projects returned
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
type: array
items:
$ref: "#/components/schemas/Project"
post:
security:
- BearerAuth: []
tags:
- Projects
description: Creates a project into the company account
summary: Create a Project
requestBody:
content:
application/json:
schema:
type: object
required:
- name
properties:
name:
type: string
example: "A project name"
active:
type: boolean
example: true
default: false
responses:
"200":
description: Project created successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
$ref: "#/components/schemas/Project"
"400":
description: Invalid data was sent
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
error:
type: object
properties:
name:
type: array
items:
type: string
example: "Project name cannot be empty"
/company/attendances/projects/{id}:
delete:
security:
- BearerAuth: []
tags:
- Projects
description: Deletes a project from the company account
summary: Delete Project by ID
parameters:
- name: id
in: path
required: true
description: Numeric `id` of the project
schema:
type: integer
format: int32
responses:
"204":
description: Project was successfully deleted
"404":
description: Project does not exist
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
message:
type: string
example: "Project 5 not found"
patch:
security:
- BearerAuth: []
tags:
- Projects
description: Updates a project with the given data
summary: Update Project by ID
parameters:
- name: id
in: path
required: true
description: Numeric `id` of the project
schema:
type: integer
format: int32
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
example: "A project name"
active:
type: boolean
description: "Marks the availability of the project"
example: true
responses:
"200":
description: Project updated successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
$ref: "#/components/schemas/Project"
"400":
description: Invalid data was sent
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
error:
type: object
properties:
active:
type: array
items:
type: string
example: "Active field needs to be of type boolean"
"404":
description: Project not found
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
message:
type: string
example: "Project 5 not found"
/company/time-off-types:
parameters:
- $ref: "#/components/parameters/XPersonioPartnerID"
- $ref: "#/components/parameters/XPersonioAppID"
get:
security:
- BearerAuth: []
tags:
- Absences
description: 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'.
summary: List Time-Off Types
parameters:
- name: limit
in: query
required: false
description: Pagination attribute to limit how many records will be returned per page
schema:
type: integer
minimum: 1
default: 200
- name: offset
in: query
required: false
description: Pagination attribute to identify which page you are requesting, by the form of telling an offset from the first record that would be returned.
schema:
type: integer
minimum: 0
default: 0
responses:
"200":
description: ""
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
type: array
items:
$ref: "#/components/schemas/TimeOffTypeResource"
examples:
response:
value:
success: true
data:
- type: TimeOffType
attributes:
id: 1234
name: 'Paid vacation'
category: null
legacy_category: null
unit: 'day'
half_day_requests_enabled: true
certification_required: false
substitute_option: disabled
approval_required: true
- type: TimeOffType
attributes:
id: 1235
name: 'Home office'
category: 'offsite_work'
legacy_category: 'offsite_work'
unit: 'hour'
half_day_requests_enabled: true
certification_required: true
certification_submission_timeframe: 2
substitute_option: optional
approval_required: true
/company/time-offs:
parameters:
- $ref: "#/components/parameters/XPersonioPartnerID"
- $ref: "#/components/parameters/XPersonioAppID"
get:
security:
- BearerAuth: []
tags:
- Absences
description: 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.
summary: List Time-Offs
parameters:
- name: start_date
in: query
required: false
description: First day of the period to be queried. It is inclusive, so the result starts from and including the provided `start_date`
schema:
type: string
format: date
- name: end_date
in: query
required: false
description: Last day of the period to be queried. It is inclusive, so the result ends on `end_date` including absences from the `end_date`
schema:
type: string
format: date
- name: updated_from
in: query
required: false
description: 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
schema:
type: string
format: date
- name: updated_to
in: query
required: false
description: 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
schema:
type: string
format: date
- name: employees[]
in: query
required: false
description: A list of Personio employee ID's to filter the results. The result filters including only absences of provided employees
explode: true
schema:
type: array
items:
type: integer
allowReserved: true
- name: limit
in: query
required: false
description: Pagination attribute to limit the number of absence periods per page
schema:
type: integer
minimum: 1
default: 200
- name: offset
in: query
required: false
description: Pagination attribute to identify which page number you are requesting
schema:
type: integer
minimum: 0
default: 0
responses:
"200":
description: ""
content:
application/json:
schema:
$ref: "#/components/schemas/AbsencePeriodsResponse"
examples:
response:
value:
success: true
metadata:
total_elements: 1
current_page: 1
total_pages: 1
data:
- type: TimeOffPeriod
attributes:
id: 12345
status: approved
start_date: '2017-12-27T00:00:00+0100'
end_date: '2017-12-29T00:00:00+0100'
days_count: 3
half_day_start: false
half_day_end: false
time_off_type:
type: TimeOffType
attributes:
id: 54321
name: Vacation
category: offsite_work
employee:
type: Employee
attributes:
id:
label: id
value: 4567
type: integer
universal_id: id
first_name:
label: First name
value: Michael
type: standard
universal_id: first_name
last_name:
label: Last name
value: Miller
type: standard
universal_id: last_name
email:
label: Email
value: michael.miller@demo.com
type: standard
universal_id: email
certificate:
status: not-required
created_at: '2017-01-17T10:32:18+0100'
updated_at: '2017-01-17T10:32:18+0100'
offset: 0,
limit: 200,
post:
security:
- BearerAuth: []
tags:
- Absences
description: Adds absence data for absence types with **time unit** set to **days**.
summary: Create a Time-Off
requestBody:
content:
application/x-www-form-urlencoded:
schema:
$ref: "#/components/schemas/CreateTimeOffPeriodRequest"
description: Absence data
required: true
x-readme:
code-samples:
- language: "powershell"
code: "Auto-generated code snippets for this language may not be supported"
- language: "php"
code: "Auto-generated code snippets for this language may not be supported"
responses:
"200":
description: The absence period is successfully created
content:
application/json:
schema:
type: object
properties:
data:
$ref: "#/components/schemas/AbsencePeriodResponse"
examples:
response:
value:
success: true
data:
type: TimeOffPeriod
attributes:
id: 12345
status: approved
start_date: '2017-12-27T00:00:00+0100'
end_date: '2017-12-29T00:00:00+0100'
days_count: 3
half_day_start: false
half_day_end: false
time_off_type:
type: TimeOffType
attributes:
id: 54321
name: Vacation
category: offsite_work
employee:
type: Employee
attributes:
id:
label: id
value: 4567
type: integer
universal_id: id
first_name:
label: First name
value: Michael
type: standard
universal_id: first_name
last_name:
label: Last name
value: Miller
type: standard
universal_id: last_name
email:
label: Email
value: michael.miller@demo.com
type: standard
universal_id: email
certificate:
status: not-required
created_at: '2017-01-17T10:32:18+0100'
created_by: 'API'
updated_at: '2017-01-17T10:32:18+0100'
"400":
description: Invalid request
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorInsertingAbsenceResponse"
examples:
response:
value:
success: false
error:
code: 400
message: 'Error when trying to insert absence period'
"404":
description: Employee or Absence type not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
response:
value:
success: false
error:
code: 0
message: 'Time-off type not found.'
"422":
description: Validation error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorCreateAbsenceResponse"
examples:
response:
value:
success: false
error:
code: 0
message: 'The given data failed to pass validation.'
error_data: '{...}'
/company/time-offs/{id}:
parameters:
- $ref: "#/components/parameters/XPersonioPartnerID"
- $ref: "#/components/parameters/XPersonioAppID"
delete:
security:
- BearerAuth: []
tags:
- Absences
description: Deletes absence period data for absence types with **time unit** set to **days**.
summary: Delete Time-Off by ID
parameters:
- name: id
in: path
description: ID of the absence period to delete
required: true
schema:
type: integer
format: int32
responses:
"200":
description: Success response
content:
application/json:
schema:
$ref: "#/components/schemas/DeletedAbsenceResponse"
examples:
response:
value:
success: true
data:
message: The absence period was deleted.
"400":
description: Bad request response
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorAbsenceResponse"
examples:
response:
value:
success: false
error:
code: 400
message: 'The absence period id is invalid.'
"404":
description: Not found response
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorAbsenceResponse"
examples:
response:
value:
success: false
error:
code: 404
message: 'The absence period was not found.'
get:
security:
- BearerAuth: []
tags:
- Absences
description: Gets an absence period for absences with **time unit** set to **days**.
summary: Get Time-Off by ID
parameters:
- name: id
in: path
required: true
description: Numeric `id` of the absence period
schema:
type: integer
format: int32
responses:
"200":
description: ""
content:
application/json:
schema:
$ref: "#/components/schemas/AbsencePeriodResponse"
examples:
response:
value:
success: true
data:
type: TimeOffPeriod
attributes:
id: 12345
status: approved
start_date: '2017-12-27T00:00:00+0100'
end_date: '2017-12-29T00:00:00+0100'
days_count: 3
half_day_start: false
half_day_end: false
time_off_type:
type: TimeOffType
attributes:
id: 45678
name: Vacation
category: offsite_work
employee:
type: Employee
attributes:
id:
label: id
value: 2367
type: integer
universal_id: id
first_name:
label: First name
value: Michael
type: standard
universal_id: first_name
last_name:
label: Last name
value: Miller
type: standard
universal_id: last_name
email:
label: Email
value: michael.miller@demo.com
type: standard
universal_id: email
certificate:
status: not-required
created_at: '2017-01-17T10:32:18+0100'
updated_at: '2017-01-17T10:32:18+0100'
"404":
description: Not found response
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorAbsenceResponse"
examples:
response:
value:
success: false
error:
code: 404
message: 'The absence period was not found.'
/company/absence-periods:
parameters:
- $ref: "#/components/parameters/XPersonioPartnerID"
- $ref: "#/components/parameters/XPersonioAppID"
get:
security:
- BearerAuth: [ ]
tags:
- Absences
description: 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.
summary: List Absence Periods
parameters:
- name: start_date
in: query
required: false
description: When both start_date and end_date values are provided, the list of absences returned is a set that has all absences that intersects the window expressed as [start_date, end_date]. When either value is unspecified, the list of absences returned are unbounded in the direction of the unspecified value.
schema:
type: string
format: date
- name: end_date
in: query
required: false
description: When both start_date and end_date values are provided, the list of absences returned is a set that has all absences that intersects the window expressed as [start_date, end_date]. When either value is unspecified, the list of absences returned are unbounded in the direction of the unspecified value.
schema:
type: string
format: date
- name: updated_from
in: query
required: false
description: 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.
schema:
type: string
format: date-time
- name: updated_to
in: query
required: false
description: 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.
schema:
type: string
format: date-time
- name: employees[]
in: query
required: false
description: A list of Personio employee ID's to filter the results. The result filters including only absences of provided employees
explode: true
schema:
type: array
items:
type: integer
allowReserved: true
- name: absence_types[]
in: query
required: false
description: A list of Personio absence type IDs to filter the results. The result filters including only absences of provided absence types.
explode: true
schema:
type: array
items:
type: string
allowReserved: true
- name: absence_periods[]
in: query
required: false
description: A list of Personio absence period IDs to filter the results. The result filters including only absences containing the provided ids.
explode: true
schema:
type: array
items:
type: string
allowReserved: true
- name: limit
in: query
required: false
description: Pagination attribute to limit how many absence periods are returned per page.
schema:
type: integer
minimum: 1
default: 200
- name: offset
in: query
required: false
description: Pagination attribute to identify which page you are requesting, by the form of telling an offset from the first record that would be returned.
schema:
type: integer
minimum: 0
default: 0
responses:
"200":
description: ""
content:
application/json:
schema:
$ref: "#/components/schemas/HourlyAbsencePeriodsResponse"
examples:
response:
value:
success: true
metadata:
total_elements: 1
current_page: 1
total_pages: 1
data:
- type: AbsencePeriod
attributes:
id: 9bba303f-0fbc-4514-9958-0befa21923fb
measurement_unit: "hour"
effective_duration: 960
employee:
type: Employee
attributes:
id:
label: id
value: 2367
type: integer
universal_id: id
first_name:
label: First name
value: Michael
type: standard
universal_id: first_name
last_name:
label: Last name
value: Miller
type: standard
universal_id: last_name
email:
label: Email
value: michael.miller@demo.com
type: standard
universal_id: email
absence_type:
type: AbsenceType
attributes:
id: "9bba303f-0fbc-4514-9958-0befa21923fb"
name: "Absence Type Name"
time_off_type_id: 45678
certificate:
status: not-required
start: "2022-05-31T22:00:00.0Z"
end: "2022-06-02T22:00:00.0Z"
half_day_start: true
half_day_end: false
comment: "this is a comment"
origin: "web"
status: "approved"
created_by: 1
created_at: "2022-06-20T14:29:56.510Z"
updated_at: "2022-06-20T14:29:56.510Z"
approved_at: "2022-06-20T14:29:56.510Z"
breakdowns:
- date: "2022-06-01"
effective_duration: 480
- date: "2022-06-02"
effective_duration: 480
offset: 0,
limit: 200,
"400":
description: Bad request
content:
problem+json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"500":
description: Internal server error
content:
problem+json:
schema:
$ref: "#/components/schemas/ErrorResponse"
post:
security:
- BearerAuth: [ ]
tags:
- Absences
description: 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!
summary: Create an Absence Period
requestBody:
content:
application/x-www-form-urlencoded:
schema:
$ref: "#/components/schemas/CreateAbsencePeriodRequest"
description: Absence data
required: true
x-readme:
code-samples:
- language: "powershell"
code: "Auto-generated code snippets for this language may not be supported"
- language: "php"
code: "Auto-generated code snippets for this language may not be supported"
responses:
"201":
description: The absence period was successfully created
content:
application/json:
schema:
type: object
properties:
data:
$ref: "#/components/schemas/HourlyAbsencePeriodResponse"
examples:
response:
value:
success: true
data:
- type: AbsencePeriod
attributes:
id: 9bba303f-0fbc-4514-9958-0befa21923fb
measurement_unit: "hour"
effective_duration: 960
employee:
type: Employee
attributes:
id:
label: id
value: 2367
type: integer
universal_id: id
first_name:
label: First name
value: Michael
type: standard
universal_id: first_name
last_name:
label: Last name
value: Miller
type: standard
universal_id: last_name
email:
label: Email
value: michael.miller@demo.com
type: standard
universal_id: email
absence_type:
type: AbsenceType
attributes:
id: "9bba303f-0fbc-4514-9958-0befa21923fb"
name: "Absence Type Name"
time_off_type_id: 45678
certificate:
status: not-required
start: "2022-05-31T22:00:00.0Z"
end: "2022-06-02T22:00:00.0Z"
half_day_start: true
half_day_end: false
comment: "this is a comment"
origin: "web"
status: "approved"
timezone: "Europe/Berlin"
created_by: 1
created_at: "2022-06-20T14:29:56.510Z"
updated_at: "2022-06-20T14:29:56.510Z"
approved_at: "2022-06-20T14:29:56.510Z"
breakdowns:
- date: "2022-06-01"
effective_duration: 480
- date: "2022-06-02"
effective_duration: 480
"400":
description: Invalid request
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorInsertingAbsenceResponse"
examples:
response:
value:
success: false
error:
code: 400
message: 'Error when trying to insert absence period'
"404":
description: Employee or Absence type not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
response:
value:
success: false
error:
code: 0
message: 'Absence type not found.'
"422":
description: Validation error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorCreateAbsenceResponse"
examples:
response:
value:
success: false
error:
code: 0
message: 'The given data failed to pass validation.'
error_data: '{...}'
"500":
description: Internal server error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
response:
value:
success: false
error:
code: 0
message: 'Something went wrong'
/company/absence-periods/{id}:
parameters:
- $ref: "#/components/parameters/XPersonioPartnerID"
- $ref: "#/components/parameters/XPersonioAppID"
delete:
security:
- BearerAuth: []
tags:
- Absences
description: Deletes absence period data for absence types with **time unit** set to **hours**.
summary: Delete Absence Period by ID
parameters:
- name: id
in: path
description: ID of the absence period to delete
required: true
schema:
type: string
format: uuid
example: 61fe126b-a7b3-449a-b5ee-3865a6fcc546
responses:
"200":
description: Success response
content:
application/json:
schema:
$ref: "#/components/schemas/DeletedAbsenceResponse"
examples:
response:
value:
success: true
data:
message: The absence period was deleted.
"404":
description: Not found response
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorAbsenceResponse"
examples:
response:
value:
success: false
error:
code: 404
message: 'The absence period was not found.'
"400":
description: Bad request response
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorAbsenceResponse"
examples:
response:
value:
success: false
error:
code: 400
message: 'The absence period id is invalid.'
/company/document-categories:
parameters:
- $ref: "#/components/parameters/XPersonioPartnerID"
- $ref: "#/components/parameters/XPersonioAppID"
get:
security:
- BearerAuth: []
tags:
- Documents
description: This endpoint is responsible for fetching all document categories of the company. The result contains a list of document categories.
summary: List Document Categories
responses:
"200":
description: ""
content:
application/json:
schema:
$ref: "#/components/schemas/DocumentCategoriesResponse"
examples:
response:
value:
success: true
data:
- id: 1
type: "DocumentCategory"
attributes:
name: "Certificates of employment"
- id: 2
type: "DocumentCategory"
attributes:
name: "Other documents"
/company/documents:
parameters:
- $ref: "#/components/parameters/XPersonioPartnerID"
- $ref: "#/components/parameters/XPersonioAppID"
post:
security:
- BearerAuth: []
tags:
- Documents
description: This endpoint is responsible for uploading documents for the company employees.
summary: Upload Document
requestBody:
content:
multipart/form-data:
schema:
$ref: "#/components/schemas/DocumentUploadRequest"
description: Data necessary for document upload.
x-readme:
code-samples:
- language: "powershell"
code: "Auto-generated code snippets for this language may not be supported"
- language: "php"
code: "Auto-generated code snippets for this language may not be supported"
- language: "ruby"
code: "Auto-generated code snippets for this language may not be supported"
- language: "java"
code: "Auto-generated code snippets for this language may not be supported"
responses:
"201":
description: "The document was successfully uploaded to the employees profile"
content:
application/json:
schema:
$ref: "#/components/schemas/DocumentUploadSuccessResponse"
examples:
response:
value:
success: true
data:
id: 1
type: "Document"
attributes:
title: "Personio"
date: "2022-02-02"
comment: "Enable better organisations"
employee:
type: "Employee"
attributes:
id:
label: "ID"
value: 1
type: integer
universal_id: "id"
first_name:
label: "First name"
value: "Demo"
type: standard
universal_id: "first_name"
last_name:
label: "Last name"
value: "Account"
type: standard
universal_id: "last_name"
email:
label: "Email"
value: "demo.account@demo.de"
type: standard
universal_id: "email"
category:
id: 1
type: "DocumentCategory"
attributes:
name: "Other documents"
"404":
description: "This status code is returned if the provided employee_id or category_id are not found within the company."
content:
application/json:
schema:
$ref: "#/components/schemas/DocumentUploadFailedWithBadDocumentCategoryResponse"
examples:
response:
value:
success: false
error:
message: "No query results for model [DocumentCategory] 1"
code: 0
"422":
description: "This status code is returned if the provided request parameters cannot be processed or if the parameters are invalid."
content:
application/json:
schema:
$ref: "#/components/schemas/DocumentUploadFailedWithUnsupportedFileTypeResponse"
examples:
response:
value:
success: false
error:
message: "The given data was invalid."
code: 0
error_data:
file: [
"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."
]
/company/custom-reports/reports:
get:
tags:
- Custom Reports
parameters:
- $ref: "#/components/parameters/XPersonioPartnerID"
- $ref: "#/components/parameters/XPersonioAppID"
- name: report_ids
in: query
schema:
type: array
items:
type: string
example: eea50309-d1b1-47d6-bc7e-27de7a3ab491, baa50309-d1b1-47d6-bc76-27de7a3ab491
required: false
description: A list of report ID's to filter the results.
- name: status
in: query
schema:
type: string
example: "up_to_date"
required: false
description: The status of the report to filter the results.
description: This endpoint provides you with metadata about existing custom reports in your Personio account, such as report name, report type, report date / timeframe.
summary: List Custom Reports
operationId: listReports
responses:
200:
description: Ok
content:
"application/json":
schema:
$ref: "#/components/schemas/PublicListReportsResponse"
500:
description: Internal Server Error
content:
"application/json":
schema:
$ref: "#/components/schemas/PublicAPIException"
/company/custom-reports/reports/{report_id}:
get:
tags:
- Custom Reports
parameters:
- $ref: "#/components/parameters/XPersonioPartnerID"
- $ref: "#/components/parameters/XPersonioAppID"
- name: report_id
in: path
schema:
type: string
example: "eea50309-d1b1-47d6-bc7e-27de7a3ab491"
description: The ID of the report to filter the result.
required: true
- name: locale
in: query
description: locale used to translate localized fields.
schema:
type: string
example: "de"
required: false
- name: page
in: query
description: Pagination parameter to identify the page to return.
schema:
type: integer
example: 1
required: false
- name: limit
in: query
description: Pagination parameter to limit the number of employees returned per page.
schema:
type: integer
example: 10
required: false
description: This endpoint provides you with the data of an existing Custom Report.
summary: Get Custom Report by ID
operationId: listReportItems
responses:
200:
description: Ok
content:
"application/json":
schema:
$ref: "#/components/schemas/PublicReportResponse"
400:
description: Bad request
content:
"application/json":
schema:
$ref: "#/components/schemas/PublicAPIException"
404:
description: Report not found
content:
"application/json":
schema:
$ref: "#/components/schemas/PublicAPIException"
500:
description: Internal Server Error
content:
"application/json":
schema:
$ref: "#/components/schemas/PublicAPIException"
/company/custom-reports/columns:
get:
tags:
- Custom Reports
parameters:
- $ref: "#/components/parameters/XPersonioPartnerID"
- $ref: "#/components/parameters/XPersonioAppID"
- name: columns
in: query
schema:
type: array
items:
type: string
example: first_name,last_name
description: The columns to filter the results.
required: false
- name: locale
in: query
schema:
type: string
example: "en"
description: locale used to translate localized fields.
required: false
- name: report_id
in: query
schema:
type: string
example: "eea50309-d1b1-47d6-bc7e-27de7a3ab491"
description: The ID of the report to filter the result of the columns. If no ID is passed, all columns for the company are returned.
required: false
description: 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.
summary: List Custom Report Column Labels
operationId: listColumns
responses:
200:
description: Ok
content:
"application/json":
schema:
$ref: "#/components/schemas/PublicListColumnsResponse"
500:
description: Internal Server Error
content:
"application/json":
schema:
$ref: "#/components/schemas/PublicAPIException"
servers:
- url: https://api.personio.de/v1
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
parameters:
XPersonioPartnerID:
name: X-Personio-Partner-ID
in: header
required: false
description: The partner identifier
schema:
type: string
XPersonioAppID:
name: X-Personio-App-ID
in: header
required: false
description: The application identifier
schema:
type: string
schemas:
Response:
title: Default response object
type: object
properties:
success:
type: boolean
data:
type: object
required:
- success
- data
DocumentUploadRequest:
type: object
properties:
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.
employee_id:
type: integer
description: Employee identifier
category_id:
type: integer
description: Document Category identifier
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.
required:
- title
- employee_id
- category_id
- file
DocumentUploadFailedWithBadDocumentCategoryResponse:
type: object
allOf:
- type: object
properties:
success:
type: boolean
example: false
error:
type: object
properties:
message:
type: string
example: "No query results for model [DocumentCategory] 1"
code:
type: integer
example: 0
DocumentUploadFailedWithUnsupportedFileTypeResponse:
type: object
allOf:
- type: object
properties:
success:
type: boolean
example: false
error:
type: object
properties:
message:
type: string
example: "The given data was invalid."
code:
type: integer
example: 0
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."
DocumentUploadSuccessResponse:
type: object
allOf:
- type: object
properties:
success:
type: boolean
example: true
data:
type: object
properties:
id:
type: integer
example: 1
type:
type: string
example: "Document"
attributes:
type: object
properties:
title:
type: string
example: "Document Title"
date:
type: string
example: "2022-01-01"
comment:
type: string
example: "Optional Test Comment"
employee:
$ref: "#/components/schemas/DocumentEmployeeResponseObject"
category_id:
$ref: "#/components/schemas/DocumentCategory"
DocumentEmployeeResponseObject:
type: object
properties:
id:
type: object
properties:
label:
type: string
example: "ID"
value:
type: integer
example: 1
type:
type: string
example: "standard"
universal_id:
type: string
example: "id"
first_name:
type: object
properties:
label:
type: string
example: "First name"
value:
type: string
example: "Michael"
type:
type: string
example: "standard"
universal_id:
type: string
example: "first_name"
last_name:
type: object
properties:
label:
type: string
example: "Last name"
value:
type: string
example: "Dou"
type:
type: string
example: "standard"
universal_id:
type: string
example: "last_name"
email:
type: object
properties:
label:
type: string
example: "Email"
value:
type: string
example: "michaeldou@demo.de"
type:
type: string
example: "standard"
universal_id:
type: string
example: "email"
DocumentCategoriesResponse:
type: object
allOf:
- type: object
properties:
success:
type: boolean
example: true
data:
type: array
items:
$ref: "#/components/schemas/DocumentCategory"
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"
DeletedAbsenceResponse:
title: Default response object
type: object
properties:
success:
type: boolean
data:
type: object
properties:
message:
example: The absence period was deleted.
DeletedAttendanceResponse:
title: Default response object
type: object
properties:
success:
type: boolean
data:
type: object
properties:
message:
example: The attendance period was deleted
UpdatedAttendanceResponse:
title: Default response object
type: object
properties:
success:
type: boolean
data:
type: object
properties:
message:
example: The attendance period was updated.
ErrorResponse:
title: Default error response
type: object
properties:
success:
type: boolean
example: false
error:
type: object
properties:
code:
type: integer
example: 0
message:
example: Something went wrong
ErrorCreateAbsenceResponse:
title: Default error response
type: object
properties:
success:
type: boolean
example: false
error:
type: object
properties:
code:
type: integer
example: 0
message:
example: The given data failed to pass validation.
ErrorAbsenceResponse:
title: 404 absence error
type: object
properties:
success:
type: boolean
example: false
error:
type: object
properties:
code:
type: integer
example: 404
message:
example: The absence period was not found.
ErrorInsertingAbsenceResponse:
title: 400 absence error
type: object
properties:
success:
type: boolean
example: false
error:
type: object
properties:
code:
type: integer
example: 400
message:
example: Error when trying to insert absence period
AttendanceCreateUpdate400ErrorResponse:
title: 400 [Bad Request] Attendances Creation Error
type: object
properties:
success:
type: boolean
example: false
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:
success:
type: boolean
example: false
error_msg:
type: string
example: Existing overlapping attendances periods
'id':
type: integer
nullable: true
example: null
employee:
type: integer
example: 1234
date:
type: string
example: 2017-01-01
start_time:
type: string
example: 09:00
end_time:
type: string
example: 18:00
break:
type: integer
example: 60
comment:
type: string
example: "Optional Test Comment"
project_id:
type: integer
nullable: true
example: null
AttendanceDelete400ErrorResponse:
title: 400 [Bad Request] Attendance Error
type: object
properties:
success:
type: boolean
example: false
error:
type: object
properties:
code:
type: integer
example: 400
message:
example: Bad Request
Attendance404ErrorResponse:
title: 404 [Not Found] Attendance Error
type: object
properties:
success:
type: boolean
example: false
error:
type: object
properties:
code:
type: integer
example: 404
message:
example: The attendance period was not found.
Employee404ErrorResponse:
title: 404 [Not Found] Employee Error
type: object
properties:
success:
type: boolean
example: false
error:
type: object
properties:
code:
type: integer
example: 0
message:
example: Es ist ein Problem aufgetreten
EmployeeCreatedResponse:
title: Successfully created employee response
type: object
properties:
success:
type: boolean
data:
type: object
properties:
id:
type: number
example: 1
message:
type: string
example: success
EmployeeCreationErrorResponse:
title: Employee creation failed due to invalid payload
type: object
properties:
success:
type: boolean
error:
type: object
properties:
code:
type: number
example: 422
message:
type: string
example: "Supervisor with ID 1 not found"
EmployeeUpdatedResponse:
title: Successfully updated employee response
type: object
properties:
success:
type: boolean
example: true
data:
type: object
properties:
id:
type: number
example: 12345
meta:
type: array
items:
type: string
default: []
EmployeeUpdateErrorResponse:
title: Employee update failed due to invalid payload
type: object
properties:
success:
type: boolean
error:
type: object
properties:
code:
type: number
example: 422
message:
type: string
example: "Supervisor with ID 1 not found"
Office:
type: object
properties:
label:
example: Office
value:
type: object
properties:
type:
type: string
example: Office
attributes:
type: object
properties:
name:
example: Munich
type:
$ref: '#/components/schemas/TypeEnum'
universal_id:
example: office
Department:
type: object
properties:
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
type:
$ref: '#/components/schemas/TypeEnum'
universal_id:
example: department
CostCenters:
type: object
properties:
label:
example: Cost center
value:
type: array
items:
type: object
properties:
type:
example: CostCenter
attributes:
type: object
properties:
name:
example: Cost Center One
id:
type: number
example: 1
percentage:
type: number
example: 50
type:
$ref: '#/components/schemas/TypeEnum'
universal_id:
example: cost_center
HolidayCalendar:
type: object
properties:
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
country:
example: DE
state:
example: Hamburg
type:
$ref: '#/components/schemas/TypeEnum'
universal_id:
example: holiday_calendar
WorkSchedule:
type: object
properties:
label:
example: WorkSchedule
value:
type: object
properties:
type:
example: WorkSchedule
attributes:
type: object
properties:
id:
type: number
example: 1
name:
example: Standard Hours
monday:
example: 08:30
pattern: ^\d\d:\d\d$
tuesday:
example: 08:30
pattern: ^\d\d:\d\d$
wednesday:
example: 08:30
pattern: ^\d\d:\d\d$
thursday:
example: 08:30
pattern: ^\d\d:\d\d$
friday:
example: 08:30
pattern: ^\d\d:\d\d$
saturday:
example: 00:00
pattern: ^\d\d:\d\d$
sunday:
example: 00:00
pattern: ^\d\d:\d\d$
type:
$ref: '#/components/schemas/TypeEnum'
universal_id:
example: work_schedule
Team:
type: object
properties:
label:
example: Team
value:
type: object
properties:
type:
type: string
example: Team
attributes:
type: object
properties:
name:
example: Management
type:
$ref: '#/components/schemas/TypeEnum'
universal_id:
example: team
AbsenceEntitlement:
type: object
properties:
label:
example: Absence entitlement
value:
type: array
items:
type: object
properties:
type:
type: string
enum:
- TimeOffType
attributes:
type: object
properties:
id:
type: integer
example: 1
name:
example: Paid Vacation
entitlement:
example: 30
required:
- label
- value
Supervisor:
type: object
properties:
label:
type: string
example: Supervisor
value:
$ref: "#/components/schemas/ShortEmployee"
Employee:
type: object
properties:
id:
type: object
properties:
label:
example: ID
value:
example: 1
type:
$ref: '#/components/schemas/TypeEnum'
universal_id:
example: id
first_name:
type: object
properties:
label:
example: First name
value:
example: Michael
type:
$ref: '#/components/schemas/TypeEnum'
universal_id:
example: first_name
last_name:
type: object
properties:
label:
example: Last name
value:
example: Dou
type:
$ref: '#/components/schemas/TypeEnum'
universal_id:
example: last_name
preferred_name:
type: object
properties:
label:
example: Name (preferred)
value:
example: Michael Dou
type:
$ref: '#/components/schemas/TypeEnum'
universal_id:
example: preferred_name
email:
type: object
properties:
label:
example: Email
value:
example: michael.dou@personio.de
type:
$ref: '#/components/schemas/TypeEnum'
universal_id:
example: email
gender:
type: object
properties:
label:
example: Gender
value:
example: male
type:
$ref: '#/components/schemas/TypeEnum'
universal_id:
example: gender
status:
type: object
properties:
label:
example: Status
value:
example: active
type:
$ref: '#/components/schemas/TypeEnum'
universal_id:
example: status
position:
type: object
properties:
label:
example: Position
value:
example: Online Marketing Specialist
type:
$ref: '#/components/schemas/TypeEnum'
universal_id:
example: position
supervisor:
$ref: "#/components/schemas/Supervisor"
employment_type:
type: object
properties:
label:
example: Employment type
value:
example: internal
type:
$ref: '#/components/schemas/TypeEnum'
universal_id:
example: employment_type
weekly_working_hours:
type: object
properties:
label:
example: Weekly hours
value:
example: 40
type:
$ref: '#/components/schemas/TypeEnum'
universal_id:
example: weekly_working_hours
hire_date:
type: object
properties:
label:
example: Hire date
value:
example: 2012-02-01T00:00:00+0100
type:
$ref: '#/components/schemas/TypeEnum'
universal_id:
example: hire_date
contract_end_date:
type: object
properties:
label:
example: Contact end date
value:
example: 2020-02-01T00:00:00+0100
type:
$ref: '#/components/schemas/TypeEnum'
universal_id:
example: contract_end_date
termination_date:
type: object
properties:
label:
example: Termonation date
value:
example: 2020-02-01T00:00:00+0100
type:
$ref: '#/components/schemas/TypeEnum'
universal_id:
example: termination_date
termination_type:
type: object
properties:
label:
example: Termonation type
value:
example:
type:
$ref: '#/components/schemas/TypeEnum'
universal_id:
example: termination_type
termination_reason:
type: object
properties:
label:
example: Termonation reason
value:
example:
type:
$ref: '#/components/schemas/TypeEnum'
universal_id:
example: termination_reason
probation_period_end:
type: object
properties:
label:
example: Probation period end
value:
example: 2020-02-01T00:00:00+0100
type:
$ref: '#/components/schemas/TypeEnum'
universal_id:
example: probation_period_end
created_at:
type: object
properties:
label:
example: Created at
value:
example: 2018-02-01T00:00:00+0100
type:
$ref: '#/components/schemas/TypeEnum'
universal_id:
example: created_at
last_modified_at:
type: object
properties:
label:
example: Last modified
value:
example: '2020-11-18T17:33:55+01:00'
type:
$ref: '#/components/schemas/TypeEnum'
universal_id:
example: last_modified_at
subcompany:
$ref: "#/components/schemas/Office"
office:
$ref: "#/components/schemas/Office"
department:
$ref: "#/components/schemas/Department"
cost_centers:
$ref: "#/components/schemas/CostCenters"
holiday_calendar:
$ref: "#/components/schemas/HolidayCalendar"
work_schedule:
$ref: "#/components/schemas/WorkSchedule"
absence_entitlement:
$ref: "#/components/schemas/AbsenceEntitlement"
team:
$ref: "#/components/schemas/Team"
fix_salary:
type: object
properties:
label:
example: Fix salary
value:
example: 4000
type:
$ref: '#/components/schemas/TypeEnum'
universal_id:
example: fix_salary
currency:
example: EUR
type: string
fix_salary_interval:
type: object
properties:
label:
example: Salary interval
value:
example: monthly
type:
$ref: '#/components/schemas/TypeEnum'
universal_id:
example: fix_salary_interval
hourly_salary:
type: object
properties:
label:
example: Hourly salary
value:
example: 0
type:
$ref: '#/components/schemas/TypeEnum'
universal_id:
example: hourly_salary
currency:
example: EUR
type: string
last_working_day:
type: object
properties:
label:
example: Last day of work
value:
example:
type:
$ref: '#/components/schemas/TypeEnum'
universal_id:
example: last_working_day
profile_picture:
type: object
properties:
label:
example: Profile Picture
value:
example: http://api.dev.personio.de/v1/company/employees/1/profile-picture
type:
$ref: '#/components/schemas/TypeEnum'
universal_id:
example: profile_picture
dynamic_21827:
type: object
properties:
label:
example: IBAN
value:
example: DE98 8989 9898 0000 8989 00
type:
description: The type of the field.
$ref: '#/components/schemas/TypeEnum'
universal_id:
example: iban
EmployeesResponse:
title: List of Employees
allOf:
- $ref: "#/components/schemas/Response"
- type: object
properties:
metadata:
type: object
required:
- total_elements
- current_page
- total_pages
properties:
total_elements:
type: integer
description: The total number of items matching the query filters.
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
offset:
type: integer
limit:
type: integer
data:
type: array
items:
type: object
properties:
type:
example: Employee
attributes:
$ref: "#/components/schemas/Employee"
EmployeeResponse:
title: Employee Response
allOf:
- $ref: "#/components/schemas/Response"
- type: object
properties:
data:
type: object
properties:
type:
example: Employee
attributes:
$ref: "#/components/schemas/Employee"
EmployeeAbsenceBalance:
title: Employee Absence Balance
type: object
properties:
success:
type: boolean
data:
type: array
items:
type: object
properties:
id:
type: integer
example: 1234
name:
type: string
example: Paid Vacation
category:
type: string
example: custom_absence
balance:
type: number
description: >
Effective balance, as of request date; not deducting any upcoming absence periods,
but only what has been taken. If the absence period is currently ongoing,
the effective balance only considers the part of the period until today.
example: 10.5
available_balance:
type: number
description: Available balance is what actually left to be planned (where upcoming absence periods are already deducted).
example: 8.5
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:
example: true
description: "Marks the availability of the project. The default value is false."
type: boolean
created_at:
example: "2022-02-01T12:00:00+0100"
type: string
format: datetime
updated_at:
example: "2022-02-01T12:00:00+0100"
type: string
format: datetime
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:
example: true
description: "Marks the availability of the project. When a new project is created, it's set by default to false."
type: boolean
Attendance:
type: object
properties:
employee:
example: 1
type: integer
date:
type: string
format: date
start_time:
type: string
pattern: ^\d\d:\d\d$
example: "08:00"
end_time:
type: string
nullable: true
pattern: ^\d\d:\d\d$
example: "17:00"
break:
type: integer
example: 60
comment:
type: string
example: "I was productive as hell"
is_holiday:
type: boolean
example: false
is_on_time_off:
type: boolean
example: false
status:
type: string
enum:
- confirmed
- pending
- rejected
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
AttendanceCreateRequest:
type: object
properties:
attendances:
type: array
items:
type: object
required: [employee, date, start_time, break]
properties:
employee:
type: integer
minimum: 1
example: 1
date:
type: string
format: date
start_time:
type: string
pattern: ^\d\d:\d\d$
example: "08:00"
description: "Format: hh:mm"
end_time:
type: string
nullable: true
pattern: ^\d\d:\d\d$
example: "17:00"
description: "Format: hh:mm"
break:
type: integer
minimum: 0
example: 60
comment:
type: string
nullable: true
example: "I was productive as hell"
project_id:
type: integer
nullable: true
example: 5
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."
AttendanceUpdateRequest:
type: object
properties:
date:
type: string
format: date
start_time:
type: string
pattern: ^\d\d:\d\d$
example: "08:00"
description: "Format: hh:mm"
end_time:
type: string
nullable: true
pattern: ^\d\d:\d\d$
example: "17:00"
description: "Format: hh:mm"
break:
type: integer
minimum: 0
example: 60
comment:
type: string
nullable: true
example: "I was productive as hell"
project_id:
type: integer
nullable: true
example: 5
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."
AttendancePeriodsResponse:
title: List All Attendance Periods response
type: object
allOf:
- $ref: "#/components/schemas/Response"
- type: object
properties:
metadata:
type: object
required:
- total_elements
- current_page
- total_pages
properties:
total_elements:
type: integer
description: The total number of items matching the query filters.
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
offset:
type: integer
limit:
type: integer
data:
type: array
items:
type: object
required:
- id
- type
- attributes
properties:
id:
type: integer
example: 1
type:
example: AttendancePeriod
attributes:
$ref: "#/components/schemas/Attendance"
NewAttendancePeriodParametersRequest:
title: Create a New Attendance Period request
type: object
properties:
attendances[][employee]:
type: integer
description: Employee identifier
attendances[][date]:
type: string
format: date
description: "Attendance date. Format: yyyy-mm-dd"
example: '2020-01-31'
attendances[][start_time]:
type: string
pattern: ^\d\d:\d\d$
description: "Start time. Format: hh:mm"
example: '08:00'
attendances[][end_time]:
type: string
nullable: true
pattern: ^\d\d:\d\d$
description: "End time. Format: hh:mm"
example: '12:00'
attendances[]break:
type: integer
minimum: 0
format: int32
description: Break in minutes
attendances[][comment]:
type: string
nullable: true
description: Optional comment
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."
project_id:
type: integer
nullable: true
format: int32
description: The ID of the project
example: 5
required:
- attendances[][employee]
- attendances[][date]
- attendances[][start_time]
- attendances[]break
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
TimeOffTypeResource:
title: Type of time-off resource
type: object
properties:
type:
type: string
enum:
- TimeOffType
description: Time-off type resource name
attributes:
type: object
properties:
id:
type: integer
description: identifier
example: 1
name:
type: string
example: Paid vacation
category:
type: string
nullable: true
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
example: offsite_work
legacy_category:
type: string
nullable: true
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
example: offsite_work
unit:
type: string
enum:
- day
- hour
example: day
half_day_requests_enabled:
type: boolean
example: true
certification_required:
type: boolean
example: false
certification_submission_timeframe:
description: The timeframe in days under which the employee needs to submit the certification
type: integer
example: 2
substitute_option:
type: string
enum:
- disabled
- optional
- required
example: optional
approval_required:
type: boolean
example: true
CreateTimeOffPeriodRequest:
title: Create time-off periods
type: object
properties:
employee_id:
type: integer
description: Employee identifier
time_off_type_id:
type: integer
description: Time-off type identifier
start_date:
type: string
format: date
description: "Absence start date. Format: yyyy-mm-dd"
example: '2020-01-31'
end_date:
type: string
format: date
description: "Absence end date. Format: yyyy-mm-dd"
example: '2020-01-31'
half_day_start:
type: boolean
example: false
description: Whether the start date is a half-day off.
half_day_end:
type: boolean
example: false
description: Whether the end date is a half-day off.
comment:
type: string
example: Some Comment
description: Optional comment
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.
required:
- employee_id
- time_off_type_id
- start_date
- end_date
- half_day_start
- half_day_end
CreateAbsencePeriodRequest:
title: Create Absence periods with **time unit** set to **hours**
type: object
properties:
employee_id:
type: integer
description: Employee identifier
example: 10735
time_off_type_id:
type: integer
description: Time-off type identifier
example: 10735
start_date:
type: string
format: date
description: "Absence start date. Format: yyyy-mm-dd"
example: '2020-01-31'
end_date:
type: string
format: date
description: "Absence end date. Format: yyyy-mm-dd"
example: '2020-01-31'
start_time:
type: string
format: date
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)"
example: '03:00'
end_time:
type: string
format: date
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)"
example: '15:00'
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)
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)
comment:
type: string
example: Some Comment
description: Optional comment
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.
required:
- employee_id
- time_off_type_id
- start_date
- end_date
AbsencePeriodsResponse:
title: List All Absence Periods response
type: object
allOf:
- $ref: "#/components/schemas/Response"
- type: object
properties:
metadata:
type: object
required:
- total_elements
- current_page
- total_pages
properties:
total_elements:
type: integer
description: The total number of items matching the query filters.
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
offset:
type: integer
limit:
type: integer
data:
type: array
items:
type: object
required:
- type
- attributes
properties:
type:
example: TimeOffPeriod
attributes:
$ref: "#/components/schemas/Absence"
HourlyAbsencePeriodsResponse:
title: List All Hourly Absence Periods response
type: object
allOf:
- $ref: "#/components/schemas/Response"
- type: object
properties:
metadata:
type: object
required:
- total_elements
- current_page
- total_pages
properties:
total_elements:
type: integer
description: The total number of items matching the query filters.
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
offset:
type: integer
limit:
type: integer
data:
type: array
items:
type: object
required:
- type
- attributes
properties:
type:
example: AbsencePeriod
attributes:
$ref: "#/components/schemas/HourlyAbsence"
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
measurement_unit:
type: string
enum: [minutes]
example: "minutes"
effective_duration:
type: integer
example: 60
description: Period effective duration in minutes
employee:
$ref: "#/components/schemas/ShortEmployee"
absence_type_id:
$ref: "#/components/schemas/AbsenceType"
certificate:
type: object
properties:
status:
example: not-required
type: string
start:
type: string
format: date-time
end:
type: string
format: date-time
nullable: true
half_day_start:
type: boolean
half_day_end:
type: boolean
comment:
type: string
origin:
type: string
nullable: true
enum: [web,api,mobile,slack,msteams]
example: web
status:
type: string
example: approved
created_by:
type: integer
example: 1
description: "ID of the employee who created the absence period."
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
approved_at:
type: string
format: date-time
nullable: true
breakdowns:
type: array
description: "Breakdowns of effective duration by day of absence."
items:
$ref: "#/components/schemas/AbsencePeriodBreakdown"
AbsencePeriodResponse:
title: Absence Periods response
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"
HourlyAbsencePeriodResponse:
title: Absence Periods response
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"
Absence:
type: object
properties:
id:
type: integer
example: 1
status:
type: string
example: approved
start_date:
type: string
example: 2017-12-27T00:00:00+0100
end_date:
type: string
example: 2017-12-79T00:00:00+0100
days_count:
type: number
example: 3
half_day_start:
type: boolean
example: false
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
employee:
$ref: "#/components/schemas/ShortEmployee"
certificate:
type: object
properties:
status:
example: not-required
type: string
created_at:
type: string
example: 2017-01-17T10:32:18+0100
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"
updated_at:
type: string
example: 2017-01-17T10:32:18+0100
HourlyAbsence:
type: object
properties:
id:
type: string
format: uuid
example: 61fe126b-a7b3-449a-b5ee-3865a6fcc546
measurement_unit:
type: string
example: "hours"
effective_duration:
type: integer
example: 16
description: Period effective duration in minutes
employee:
$ref: "#/components/schemas/ShortEmployee"
absence_type:
$ref: "#/components/schemas/AbsenceType"
certificate:
type: object
properties:
status:
example: not-required
type: string
start:
type: string
format: date-time
end:
type: string
format: date-time
nullable: true
half_day_start:
type: boolean
half_day_end:
type: boolean
comment:
type: string
origin:
type: string
example: web
status:
type: string
example: approved
timezone:
type: string
example: "Europe/Berlin"
created_by:
type: integer
example: 1
description: "ID of the employee who created the absence period."
created_at:
type: string
example: 2017-01-17T10:32:18+0100
updated_at:
type: string
example: 2017-01-17T10:32:18+0100
approved_at:
type: string
format: date-time
nullable: true
breakdowns:
type: array
description: "Breakdowns of effective duration by day of absence."
items:
$ref: "#/components/schemas/AbsencePeriodBreakdown"
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
AbsencePeriodBreakdown:
type: object
required:
- date
- effective_duration
properties:
date:
type: string
format: date
effective_duration:
description: Number representing the value of duration in minutes.
type: integer
example: 60
ShortEmployee:
type: object
properties:
type:
type: string
example: Employee
attributes:
type: object
properties:
id:
type: object
properties:
label:
example: 1
value:
example: id
type:
$ref: '#/components/schemas/TypeEnum'
universal_id:
example: id
first_name:
type: object
properties:
label:
example: First Name
value:
example: Michael
type:
$ref: '#/components/schemas/TypeEnum'
universal_id:
example: first_name
last_name:
type: object
properties:
label:
example: Last Name
value:
example: Dou
type:
$ref: '#/components/schemas/TypeEnum'
universal_id:
example: last_name
email:
type: object
properties:
label:
example: Email
value:
example: michael.dou@personio.de
type:
$ref: '#/components/schemas/TypeEnum'
universal_id:
example: email
TypeEnum:
type: string
example: standard
enum:
- standard
- date
- integer
- decimal
- list
- link
- tags
- multiline
PublicListReportsResponse:
type: object
properties:
success:
type: boolean
metadata:
$ref: "#/components/schemas/PublicReportMetaData"
offset:
type: integer
limit:
type: integer
data:
type: array
items:
$ref: "#/components/schemas/PublicReportData"
PublicReportResponse:
type: object
properties:
success:
type: boolean
metadata:
$ref: "#/components/schemas/PublicReportMetaData"
offset:
type: integer
deprecated: true
limit:
type: integer
data:
type: array
items:
$ref: "#/components/schemas/PublicReportItemsData"
PublicListColumnsResponse:
type: object
properties:
success:
type: boolean
metadata:
$ref: "#/components/schemas/PublicReportMetaData"
offset:
type: integer
limit:
type: integer
data:
$ref: "#/components/schemas/PublicColumnData"
PublicReportMetaData:
type: object
properties:
total_elements:
type: integer
current_page:
type: integer
total_pages:
type: integer
PublicReportData:
type: object
properties:
type:
type: string
example: "Report"
attributes:
$ref: "#/components/schemas/PublicReportAttributes"
PublicReportItemsData:
type: object
properties:
type:
type: string
example: "Report"
attributes:
oneOf:
- $ref: "#/components/schemas/PublicReportItemsAttributes"
- $ref: "#/components/schemas/PublicTimeframeReportItemsAttributes"
- $ref: "#/components/schemas/PublicHistoricalReportItemsAttributes"
PublicColumnData:
type: object
properties:
type:
type: string
example: "Column"
attributes:
type: array
items:
$ref: "#/components/schemas/PublicColumnAttributes"
PublicColumnAttributes:
type: object
properties:
attribute_id:
type: string
example: first_name
human_readable:
type: string
example: First Name
data_type:
type: string
example: "TEXT"
PublicReportAttributes:
type: object
properties:
id:
type: string
example: "eb7482f3-2323-43e2-87ed-99d2399e8e22"
name:
type: string
example: Employee vacations past month
description:
type: string
example: Shows vacations of all employees that were taken past month
author_first_name:
type: string
description: Report author
example: Robert
author_last_name:
type: string
description: Report author
example: Sirano
type:
type: string
example: point_in_time
enum:
- point_in_time
- historical_data
- timeframe
status:
type: string
example: up_to_date
enum:
- up_to_date
- updating
- update_failed
start_date:
type: string
format: date
example: "2022-09-01"
end_date:
type: string
format: date
example: "2022-09-30"
created_at:
type: string
format: date-time
example: "2022-04-10T17:32:28Z"
updated_at:
type: string
format: date-time
example: "2022-04-10T17:32:28Z"
data_refreshed_at:
type: string
format: date-time
example: "2022-04-10T17:32:28Z"
columns:
type: array
items:
type: string
filters:
type: array
items:
type: object
properties:
column:
type: string
example: office_id
comparison:
type: string
example: eq
value:
type: string
example: 1
period_type:
type: string
example: fixed
enum:
- fixed
- today
- last_day_of_this_month
- this_year
- last_month
- last_thirty_days
- this_month
- year_to_date
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
description:
type: string
example: Shows vacations of all employees on a specific date
author_first_name:
type: string
description: Report author
example: Robert
author_last_name:
type: string
description: Report author
example: Sirano
type:
type: string
example: point_in_time
enum:
- point_in_time
status:
type: string
example: created
enum:
- up_to_date
- updating
- update_failed
start_date:
type: string
format: date-time
example: "2022-04-10"
end_date:
type: string
format: date-time
example: "2022-04-10"
created_at:
type: string
format: date-time
example: "2022-04-10T17:32:28Z"
updated_at:
type: string
format: date-time
example: "2022-04-10T17:32:28Z"
data_refreshed_at:
type: string
format: date-time
example: "2022-04-10T17:32:28Z"
columns:
type: array
items:
type: string
filters:
type: array
items:
type: object
properties:
column:
type: string
example: office_id
comparison:
type: string
example: eq
value:
type: string
example: 1
period_type:
type: string
example: fixed
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
items:
type: array
items:
type: object
properties:
employee_id:
type: integer
example: 17
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"
PublicTimeframeReportItemsAttributes:
type: object
properties:
id:
type: string
example: "eb7482f3-2323-43e2-87ed-99d2399e8e22"
name:
type: string
example: Employee vacations past month
description:
type: string
example: Shows vacations of all employees that were taken past month
author_first_name:
type: string
description: Report author
example: Robert
author_last_name:
type: string
description: Report author
example: Sirano
type:
type: string
example: timeframe
enum:
- timeframe
status:
type: string
example: created
enum:
- up_to_date
- updating
- update_failed
start_date:
type: string
format: date-time
example: "2022-04-01"
end_date:
type: string
format: date-time
example: "2022-04-10"
created_at:
type: string
format: date-time
example: "2022-04-10T17:32:28Z"
updated_at:
type: string
format: date-time
example: "2022-04-10T17:32:28Z"
data_refreshed_at:
type: string
format: date-time
example: "2022-04-10T17:32:28Z"
columns:
type: array
items:
type: string
filters:
type: array
items:
type: object
properties:
column:
type: string
example: office_id
comparison:
type: string
example: eq
value:
type: string
example: 1
period_type:
type: string
example: fixed
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
items:
type: array
items:
type: object
properties:
employee_id:
type: integer
example: 17
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"
PublicHistoricalReportItemsAttributes:
type: object
properties:
id:
type: string
example: "eb7482f3-2323-43e2-87ed-99d2399e8e22"
name:
type: string
example: Department changes in the past year
description:
type: string
example: Shows department changes of all employees over the past year
author_first_name:
type: string
description: Report author
example: Robert
author_last_name:
type: string
description: Report author
example: Sirano
type:
type: string
example: historical_data
enum:
- historical_data
status:
type: string
example: created
enum:
- up_to_date
- updating
- update_failed
start_date:
type: string
format: date-time
example: "2022-01-01"
end_date:
type: string
format: date-time
example: "2022-09-30"
created_at:
type: string
format: date-time
example: "2022-04-10T17:32:28Z"
updated_at:
type: string
format: date-time
example: "2022-04-10T17:32:28Z"
data_refreshed_at:
type: string
format: date-time
example: "2022-04-10T17:32:28Z"
columns:
type: array
items:
type: string
filters:
type: array
items:
type: object
properties:
column:
type: string
example: office_id
comparison:
type: string
example: eq
value:
type: string
example: 1
period_type:
type: string
example: fixed
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
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"
DefaultAttribute:
type: object
properties:
attribute_id:
type: string
example: first_name
data_type:
type: string
enum:
- TEXT
value:
type: string
example: Robert
employee_id:
type: integer
example: 17
EntityAttribute:
type: object
properties:
attribute_id:
type: string
example: department
entity_id:
type: string
example: 1
data_type:
type: string
enum:
- ENTITY
value:
type: string
example: IT
employee_id:
type: integer
example: 17
CostCenterAttribute:
type: object
properties:
attribute_id:
type: string
example: cost_center
data_type:
type: string
enum:
- COST_CENTER
employee_id:
type: integer
example: 17
cost_centers:
type: array
items:
$ref: "#/components/schemas/CostCenter"
CostCenter:
type: object
properties:
cost_center_id:
type: string
example: 1
value:
type: string
example: Test Center
weight:
type: string
example: 100%
AbsenceOverviewAttribute:
type: object
properties:
attribute_id:
type: string
example: absence_123
data_type:
type: string
enum:
- ABSENCE_OVERVIEW
start_date:
type: string
format: date
example: "2022-03-01"
end_date:
type: string
format: date
example: "2022-03-03"
duration_days:
type: string
example: 2
duration_hours:
type: string
example: 5
employee_id:
type: integer
example: 17
AbsencePeriodAttribute:
type: object
properties:
attribute_id:
type: string
example: "absence_123:periods"
data_type:
type: string
enum:
- ABSENCE_PERIOD
start_date:
type: string
format: date
example: "2022-03-01"
end_date:
type: string
format: date
example: "2022-03-03"
half_day_at_start:
type: boolean
half_day_at_end:
type: boolean
employee_id:
type: integer
example: 17
DurationAttribute:
type: object
properties:
attribute_id:
type: string
example: attendance_contractual_target_hours
data_type:
type: string
enum:
- DURATION
duration:
type: integer
example: 10
employee_id:
type: integer
example: 17
PerformanceTargetAttribute:
type: object
properties:
attribute_id:
type: string
example: performance_target_name
data_type:
type: string
enum:
- PERFORMANCE_TARGET
employee_id:
type: integer
example: 17
performance_targets:
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
PerformanceKpiAttribute:
type: object
properties:
attribute_id:
type: string
data_type:
type: string
enum:
- PERFORMANCE_KPI
employee_id:
type: integer
example: 17
performance_target_kpis:
type: array
items:
$ref: "#/components/schemas/PerformanceTarget"
PerformanceTargetKpi:
type: object
properties:
performance_target_id:
type: string
example: id_123
performance_kpis:
type: array
items:
$ref: "#/components/schemas/PerformanceKpi"
PerformanceKpi:
type: object
properties:
performance_kpi_id:
type: string
example: kpi_123
performance_kpi_value:
type: string
example: 14
SalaryAttribute:
type: object
properties:
attribute_id:
type: string
example: salary_123
data_type:
type: string
enum:
- SALARY
amount:
type: string
example: 12.20
currency_symbol:
type: string
example: $
employee_id:
type: integer
example: 17
CompensationAttribute:
type: object
properties:
attribute_id:
type: string
example: ABCXXX
data_type:
type: string
enum:
- COMPENSATION
amount:
type: string
example: 12.20
currency_code:
type: string
example: USD
currency_symbol:
type: string
example: $
overtime_hours:
type: string
example: 12
bonus_type:
type: string
example: MAX
employee_id:
type: integer
example: 17
DefaultHistoricalAttribute:
type: object
properties:
attribute_id:
type: string
example: first_name
data_type:
type: string
enum:
- TEXT
value:
type: string
example: Robert
employee_id:
type: integer
example: 17
effective_date:
type: string
example: 2021-01-01
DurationHistoricalAttribute:
type: object
properties:
attribute_id:
type: string
example: attendance_contractual_target_hours
data_type:
type: string
enum:
- DURATION
duration:
type: integer
example: 10
employee_id:
type: integer
example: 17
effective_date:
type: string
example: 2021-01-01
EntityHistoricalAttribute:
type: object
properties:
attribute_id:
type: string
example: department
entity_id:
type: string
example: 1
data_type:
type: string
enum:
- ENTITY
value:
type: string
example: IT
employee_id:
type: integer
example: 17
effective_date:
type: string
example: 2021-01-01
CostCenterHistoricalAttribute:
type: object
properties:
attribute_id:
type: string
example: cost_center
data_type:
type: string
enum:
- COST_CENTER
employee_id:
type: integer
example: 17
cost_centers:
type: array
items:
$ref: "#/components/schemas/CostCenter"
effective_date:
type: string
example: 2021-01-01
SalaryHistoricalAttribute:
type: object
properties:
attribute_id:
type: string
example: salary_123
data_type:
type: string
enum:
- SALARY
amount:
type: string
example: 12.20
currency_symbol:
type: string
example: $
employee_id:
type: integer
example: 17
effective_date:
type: string
example: 2021-01-01
PublicAPIException:
type: array
items:
$ref: "#/components/schemas/CustomReportsErrorResponse"
CustomReportsErrorResponse:
type: object
properties:
status:
type: integer
example: 500
trace_id:
type: string
example: ABCXXX
timestamp:
type: string
format: date-time
example: "2020-01-01T00:00:00Z"
errors:
type: array
items:
$ref: "#/components/schemas/ErrorDetails"
ErrorDetails:
type: object
properties:
title:
type: string
example: Not Found
details:
type: string
example: Report not found
type:
type: string
example: search
_meta:
type: array
items:
$ref: "#/components/schemas/ErrorMeta"
ErrorMeta:
type: object
properties:
field:
type: string
example: ID
description:
type: string
example: Report ID not found
examples:
401UnauthorizedErrorExample:
value:
{
"success": false,
"error": {
"message": "Authorization is not provided",
"code": 401
}
}
403ForbiddenErrorExample:
value:
{
"success": false,
"error": {
"message": "Provided authorization is not valid",
"code": 403
}
}
responses:
401UnauthorizedResponse:
description: "Unauthorized Access"
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
response:
$ref: "#/components/examples/401UnauthorizedErrorExample"
403ForbiddenResponse:
description: "Forbidden Access"
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
response:
$ref: "#/components/examples/403ForbiddenErrorExample"