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: /auth: post: tags: - Auth description: 'Request Authentication Token' parameters: - $ref: "#/components/parameters/XPersonioPartnerID" - $ref: "#/components/parameters/XPersonioAppID" - name: client_id in: query required: true description: Client id of the downloaded credentials file schema: type: string - name: client_secret in: query required: true description: Client secret of the downloaded credentials file schema: type: string responses: "200": description: Bearer token content: application/json: schema: allOf: - $ref: "#/components/schemas/AuthenticationTokenResponse" examples: response: value: success: true data: token: "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOi8vYXBpLmRldi5wZXJzb25pby5kZTozMDAwMS92MS9hdXRoIiwiaWF0IjoxNDg5MDkxMzA2LCJleHAiOjE0ODkxNzc3MDYsIm5iZiI6MTQ4OTA5MTMwNiwianRpIjoiZmU1ZjkxOGY2MDZjOWI4OGMwMzM0ZmJkZjkyYzkwMzgiLCJzdWIiOiJPR014TVdRd1kySmxZbVF6Tm1RNVpqQmxOell6WmpsaSJ9.QZZCdlDjmL-LYdoDx2XLUfhwTdcjDgm9h4t-6JoACiM" /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: 200 - 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. schema: 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 new employee. Status of the employee will be set to `active` if `hire_date` provided is in the past. Otherwise status will be set to `onboarding`. This endpoint responds with `id` of 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" pattern: ^\d{4}-\d{2}-\d{2}$ weekly_hours: type: number example: 40 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_hours]": description: Employee weekly working hours type: number 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" "/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" pattern: ^\d{4}-\d{2}-\d{2}$ weekly_hours: type: number example: 40 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[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_hours]": description: Employee weekly working hours type: number responses: "200": description: Employee is updated content: application/json: schema: allOf: - $ref: "#/components/schemas/EmployeeCreatedResponse" examples: response: value: success: true data: id: 81723 message: "success" 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 absences 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: 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/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 available absences types. 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 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' 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: This endpoint is responsible for fetching absence data for the company employees.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 how many attendances is returning 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/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: This endpoint is responsible for adding absence data for the company employees. requestBody: content: application/x-www-form-urlencoded: schema: $ref: "#/components/schemas/CreateTimeOffPeriodRequest" description: Absense data required: true responses: "201": 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' 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: 'Something went wrong' "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: This endpoint is responsible for deleting absence period data for the company employees. 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. "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: Show Absence Period 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/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: Needed data to upload a document x-readme: code-samples: - language: "powershell" code: "This languange is not supported" name: "This languange is not 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." ] 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 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 absense 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: Sucsefully created employee response type: object properties: success: type: boolean data: type: object properties: id: type: number example: 1 message: example: success 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 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: Weather the start date is a half-day off. half_day_end: type: boolean example: false description: Weather 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 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" 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" 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 updated_at: type: string example: 2017-01-17T10:32:18+0100 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 AuthenticationTokenResponse: title: Request Authentication Token response allOf: - $ref: '#/components/schemas/Response' - type: object properties: data: type: object required: - token properties: token: type: string TypeEnum: type: string example: standard enum: - standard - date - integer - decimal - list - link - tags - multiline