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 - 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 - 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: updated_since in: query required: false description: "Find all employees that have been updated since the provided date. The format is `ISO 8601` (2022-12-24T08:15:30). NOTE: when using the updated_since filter, the email, limit, and offset parameters are ignored." schema: type: string example: 2022-12-24T08:15:30 - name: attributes[] in: query description: Define a list of whitelisted attributes that shall be returned for all employees. required: false schema: type: array items: type: string description: List Company Employees responses: "200": description: "" content: application/json: schema: $ref: "#/components/schemas/EmployeesResponse" examples: response: value: success: true metadata: total_elements: 2 current_page: 0 total_pages: 3 offset: 0 limit: 20 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.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 vacation_day_balance: label: Vacation day balance value: 2 type: decimal universal_id: vacation_day_balance 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 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" 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[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 an employee description: > Update existing employee. Note: Updating of Email field is not currently supported. 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" 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[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: Show 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 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 vacation_day_balance: label: Vacation day balance value: 2 type: decimal universal_id: vacation_day_balance 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 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" examples: response: value: success: true data: - id: 21799 name: "Paid Vacation" category: null balance: 14 - id: 33523 name: "Sick Days" category: null balance: 0 "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`." 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. 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 - key: last_name label: Last Name type: standard universal_id: last_name - key: dynamic_1 label: IBAN type: standard universal_id: iban "/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." 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. 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: "" 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 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. 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 successfullycreated content: application/json: schema: $ref: "#/components/schemas/NewAttendancePeriodResponse" examples: response: value: success: true data: id: [ 1, 2, ] message: 'success' "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/ErrorCreateAttendanceResponse" 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. 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/DeletedAtendanceResponse" examples: response: value: success: true data: message: 'The attendance period was deleted.' "404": description: Not found response content: application/json: schema: $ref: "#/components/schemas/ErrorAttendanceResponse" 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. 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 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. "404": description: Not found response content: application/json: schema: $ref: "#/components/schemas/ErrorAttendanceResponse" 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. 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 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 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 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 **tracked in days and hours**. For example 'Paid vacation', 'Parental leave' or 'Home office'. 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 **tracked in days**. The result can be `paginated` and `filtered` by period and/or specific employee/employees. The result contains a list of absence periods. 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 **tracked in days**. 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 **tracked in days**. 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 **tracked in days**. 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 **tracked in hours**. The result can be `paginated` and `filtered` by period and/or specific employee/employees. The result contains a list of hourly absence periods. parameters: - name: start_date in: query required: false description: Filter by absence periods that start at or before given date. schema: type: string format: date - name: end_date in: query required: false description: Filter by absence periods that start at or before given date. 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" 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 **tracked in hours**. 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 **tracked in hours**. 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. 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. 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. 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 description: This endpoint provides you with the data of an existing Custom Report. operationId: listReportItems responses: 200: description: Ok content: "application/json": schema: $ref: "#/components/schemas/PublicReportResponse" 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. 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. DeletedAtendanceResponse: 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 absense 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 ErrorCreateAttendanceResponse: title: 400 attendances 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 ErrorAttendanceResponse: title: 404 absense 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 absense 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 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 vacation_day_balance: type: object properties: label: example: Vacation day balance value: example: 20.5 type: $ref: '#/components/schemas/TypeEnum' universal_id: example: vacation_day_balance 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 allOf: - $ref: "#/components/schemas/Response" - type: object properties: data: type: array items: 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 example: 10.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 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 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 properties: employee: type: integer 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 pattern: ^\d\d:\d\d$ example: "17:00" description: "Format: hh:mm" break: type: integer example: 60 comment: type: string 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." 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 pattern: ^\d\d:\d\d$ example: "17:00" description: "Format: hh:mm" break: type: integer example: 60 comment: type: string 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 Attenance 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 pattern: ^\d\d:\d\d$ description: "End time. Format: hh:mm" example: '12:00' attendances[]break: type: integer format: int32 description: Break in minutes attendances[][comment]: type: string 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 format: int32 description: The ID of the project example: 5 required: - attendances[][employee] - attendances[][date] - attendances[][start_time] - attendances[][end_time] - attendances[]break - attendances[][comment] 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 **tracked in 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 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