personio-personnel-data-api-oa3.yaml

openapi: 3.0.0
info:
  version: "1.0"
  title: Personnel Data
  description: API for reading and writing personnel data including data about attendances, absences, documents, etc
x-readme:
  samples-languages:
    - "curl"
    - "python"
    - "ruby"
    - "java"
    - "php"
    - "node"
paths:
  /company/employees:
    parameters:
      - $ref: "#/components/parameters/XPersonioPartnerID"
      - $ref: "#/components/parameters/XPersonioAppID"
    get:
      security:
        - BearerAuth: []
      tags:
        - Employees
      parameters:
        - name: limit
          in: query
          required: false
          description: Pagination attribute to limit the number of employees returned per page.
          schema:
            type: integer
            minimum: 1
            default: 10
            example: 10
        - name: offset
          in: query
          required: false
          description: Pagination attribute to identify the first item in the collection to return.
          schema:
            type: integer
            minimum: 0
            default: 0
            example: 0
        - name: email
          in: query
          required: false
          description: "Find an employee with the given email address. The response is still a list, containing only the filtered employee. NOTE: when using the updated_since filter, the email filter is ignored."
          schema:
            type: string
        - name: attributes[]
          in: query
          description: |-
            A list of attributes that will be returned for the employees, ie. a projection of the employee fields and relationships. In case `updated_since` query parameter is used, this list will additionally be used to exclude the employees that had none of the provided `attributes[]` updated since `updated_since`, ie. a selection filter.
          example: "?attributes[]=first_name&attributes[]=last_name"
          required: false
          schema:
            type: array
            items:
              type: string
            example: ["first_name", "last_name"]
        - name: updated_since
          in: query
          required: false
          description: >2- # indentation is 2 spaces (so code is aligned); strip LF at the end
            Filter to select and return only the employees that have been updated after `updated_since`. When it is used together with the `attributes[]` query parameter, the filter will select only the employees that have had any of the provided `attributes[]` updated since `updated_since`. The format is `ISO 8601` (2022-12-24T08:15:30) or `YYYY-MM-DD`. NOTE: when using the `updated_since` filter, the `email`, `limit`, and `offset` parameters are ignored.

            <details>
            <summary><b>Examples with <code>updated_since</code> and <code>attributes[]</code>:</b></summary><br />
            In an example company that has 17 employees:<br /><br />
            <details>
              <summary>
              <code class="language-html">?updated_since=2022-12-24T08:15:30</code>
              will yield 10 employees that were recently updated:
              </summary>
            <p><pre class="prettyprint"><code language="json" class="language-json">
            {
              "success": true,
              "metadata": {
                "total_elements": 10,
                "current_page": 0,
                "total_pages": 10
              },
              "offset": 0,
              "limit": 1,
              "data": [
                {
                  "type": "Employee",
                  "attributes": {
                    "id": {
                      "label": "ID",
                      "value": 1,
                      "type": "integer",
                      "universal_id": "id"
                    },
                    "first_name": {
                      "label": "First name",
                      "value": "Alexander",
                      "type": "standard",
                      "universal_id": "first_name"
                    },
                    "last_name": {
                      "label": "Last name",
                      "value": "Bergmann",
                      "type": "standard",
                      "universal_id": "last_name"
                    },
                    "email": {
                      "label": "Email",
                      "value": "alexander.bergmann@demo.com",
                      "type": "standard",
                      "universal_id": "email"
                    }
                  }
                }, ...
              ],
              ...
              ...
            }
            </code></pre></p>
            </details><br />
            <details>
              <summary>
              <code class="language-html">?attributes[]=first_name</code>
              will yield all 17 employees:
              </summary>
            <p><pre class="prettyprint"><code language="json" class="language-json">
            {
              "success": true,
              "metadata": {
                "total_elements": 17,
                "current_page": 0,
                "total_pages": 17
              },
              "offset": 0,
              "limit": 1,
              "data": [
                {
                  "type": "Employee",
                  "attributes": {
                    "id": {
                      "label": "ID",
                      "value": 1,
                      "type": "integer",
                      "universal_id": "id"
                    },
                    "first_name": {
                      "label": "First name",
                      "value": "Alexander",
                      "type": "standard",
                      "universal_id": "first_name"
                    }
                  }
                }
              ]
            }
            </code></pre></p>
            </details><br />
            <details>
              <summary>
              <code class="language-html">?attributes[]=first_name&updated_since=2022-12-24T08:15:30</code>
              will yield 3 employees, ones that had their <code>first_name</code> changed since <code>2022-12-24T08:15:30</code>:
              </summary>
            <p><pre class="prettyprint"><code language="json" class="language-json">
            {
              "success": true,
              "metadata": {
                "total_elements": 3,
                "current_page": 0,
                "total_pages": 3
              },
              "offset": 0,
              "limit": 1,
              "data": [
                {
                  "type": "Employee",
                  "attributes": {
                    "id": {
                      "label": "ID",
                      "value": 1,
                      "type": "integer",
                      "universal_id": "id"
                    },
                    "first_name": {
                      "label": "First name",
                      "value": "Alexander",
                      "type": "standard",
                      "universal_id": "first_name"
                    }
                  }
                }
              ]
            }
            </code></pre></p>
            </details>
            </details>
          example: "2022-12-24T08:15:30"
          schema:
            type: string
            example: 2022-12-24T08:15:30
      description: List Company Employees
      summary: List Employees
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EmployeesResponse"
              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
                          preferred_name:
                            label: Name (preferred)
                            value: Alexander Bergmann
                            type: standard
                            universal_id: preferred_name
                          email:
                            label: Email
                            value: alexander.bergmann@demo.email
                            type: standard
                            universal_id: email
                          gender:
                            label: Gender
                            value: male
                            type: standard
                            universal_id: gender
                          status:
                            label: Status
                            value: active
                            type: standard
                            universal_id: status
                          position:
                            label: Position
                            value: CTO
                            type: standard
                            universal_id: position
                          supervisor:
                            label: Supervisor
                            value:
                              type: Employee
                              attributes:
                                id:
                                  label: ID
                                  value: 2
                                  type: integer
                                  universal_id: id
                            type: standard
                            universal_id: supervisor
                          employment_type:
                            label: Employment type
                            value: external
                            type: standard
                            universal_id: employment_type
                          weekly_working_hours:
                            label: Weekly hours
                            value: '40'
                            type: standard
                            universal_id: weekly_working_hours
                          hire_date:
                            label: Hire date
                            value: 2014-11-09T00:00:00+01:00
                            type: date
                            universal_id: hire_date
                          contract_end_date:
                            label: Contract ends
                            value: null
                            type: date
                            universal_id: contract_end_date
                          termination_date:
                            label: Termination date
                            value: null
                            type: date
                            universal_id: termination_date
                          termination_type:
                            label: Termination type
                            value: null
                            type: standard
                            universal_id: termination_type
                          termination_reason:
                            label: Termination reason
                            value: null
                            type: standard
                            universal_id: termination_reason
                          probation_period_end:
                            label: Probation period end
                            value: null
                            type: date
                            universal_id: probation_period_end
                          created_at:
                            label: created_at
                            value: '2017-05-23T09:49:03+02:00'
                            type: date
                            universal_id: created_at
                          last_modified_at:
                            label: Last modified
                            value: '2020-11-18T17:33:55+01:00'
                            type: date
                            universal_id: last_modified_at
                          subcompany:
                            label: Subcompany
                            value:
                              type: Subcompany
                              attributes:
                                id: 7033
                                name: CS Demo GmbH
                            type: standard
                            universal_id: subcompany
                          office:
                            label: Workplace
                            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"
                    preferred_name:
                      type: string
                      example: "John Dou"
                    gender:
                      type: string
                      example: male
                    position:
                      type: string
                      example: developer
                    subcompany:
                      type: string
                      description: The subcompany employee belongs to. Should be predefined in Personio. Otherwise will be ignored with showing meta error in the response.
                      example: ACME
                    department:
                      type: string
                      description: The department employee belongs to. Should be predefined in Personio. Otherwise will be ignored with showing meta error in the response.
                      example: IT
                    office:
                      type: string
                      description: The workplace employee belongs to. Should be predefined in Personio. Otherwise will be ignored with showing meta error in the response.
                      example: Madrid
                    hire_date:
                      type: string
                      example: '2020-01-31'
                      format: date
                      description: "Employee hire date. Format: \"yyyy-mm-dd\". If `status` is not provided, it will be set to `active` if the hire date is in the past, or to `onboarding` if it's in the future."
                      pattern: ^\d{4}-\d{2}-\d{2}$
                    weekly_working_hours:
                      type: number
                      example: 40
                    status:
                      type: string
                      description: "Status of the employee. Overrides the status determined based on the value of `hire_date`."
                      example: "active"
                    "supervisor_id":
                      description: Employee ID of the Supervisor to be assigned. It needs to belong to a current existing employee, otherwise an error will be returned. If not present, no supervisor will be assigned.
                      type: number
                      example: 5
                    custom_attributes:
                      type: object
                      properties:
                        dynamic_{{ field uid }}:
                          type: string
                          description: Dynamic field, represented by unique id.
                          example: "German"
                  required:
                    - email
                    - first_name
                    - last_name
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                "employee[email]":
                  description: Employee email
                  type: string
                "employee[first_name]":
                  description: Employee first name
                  type: string
                "employee[last_name]":
                  description: Employee last name
                  type: string
                "employee[preferred_name]":
                  description: Employee preferred name
                  type: string
                "employee[gender]":
                  description: Employee gender
                  type: string
                  enum:
                    - male
                    - female
                    - diverse
                "employee[position]":
                  description: Employee position
                  type: string
                "employee[department]":
                  description: Employee department
                  type: string
                "employee[hire_date]":
                  type: string
                  example: '2020-01-31'
                  format: date
                  description: "Employee hire date. Format: yyyy-mm-dd"
                  pattern: ^\d{4}-\d{2}-\d{2}$
                "employee[weekly_working_hours]":
                  description: Employee weekly working hours
                  type: number
                "employee[supervisor_id]":
                  description: Employee ID of the Supervisor to be assigned. It needs to belong to a current existing employee, otherwise an error will be returned. If not present, no supervisor will be assigned.
                  type: number
                "employee[status]":
                  description: Employee status
                  type: string
                  enum:
                    - onboarding
                    - active
                    - leave
                    - inactive
              required:
                - employee[email]
                - employee[first_name]
                - employee[last_name]
      responses:
        "200":
          description: Successful creation of a employee
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/EmployeeCreatedResponse"
              examples:
                response:
                  value:
                    success: true
                    data:
                      id: 81723
                      message: "success"
        "422":
          description: Employee creation failed due to invalid payload
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/EmployeeCreationErrorResponse"
              examples:
                response:
                  value:
                    success: false
                    error:
                      code: 422
                      message: "Supervisor with ID 1 not found"
  /company/employees/{employee_id}:
    parameters:
      - $ref: "#/components/parameters/XPersonioPartnerID"
      - $ref: "#/components/parameters/XPersonioAppID"
    patch:
      security:
        - BearerAuth: []
      tags:
        - Employees
      summary: Update Employee by ID
      description: >
        Updates an existing employee. Note: Only the fields that are listed in the body example
        are updatable. Attributes that are not part of the sample request body but are present
        inside the request are ignored. It's not possible to update the Email field.
      parameters:
        - name: employee_id
          in: path
          required: true
          description: Numeric `id` of the employee
          schema:
            type: integer
            format: int32
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                employee:
                  type: object
                  properties:
                    first_name:
                      type: string
                      example: "John"
                    last_name:
                      type: string
                      example: "Dou"
                    preferred_name:
                      type: string
                      example: "John Dou"
                    gender:
                      type: string
                      example: male
                    position:
                      type: string
                      example: developer
                    subcompany:
                      type: string
                      description: The subcompany employee belongs to. Should be predefined in Personio. Otherwise will be ignored with showing meta error in the response.
                      example: ACME
                    department:
                      type: string
                      description: The department employee belongs to. Should be predefined in Personio. Otherwise will be ignored with showing meta error in the response.
                      example: IT
                    office:
                      type: string
                      description: The workplace employee belongs to. Should be predefined in Personio. Otherwise will be ignored with showing meta error in the response.
                      example: Madrid
                    hire_date:
                      type: string
                      example: '2020-01-31'
                      format: date
                      description: "Employee hire date. Format: \"yyyy-mm-dd\". Update of the `hire_date` will not update employee status on its own (for that you'll need to update the `status` field)"
                      pattern: ^\d{4}-\d{2}-\d{2}$
                    weekly_working_hours:
                      type: number
                      example: 40
                    status:
                      type: string
                      description: "Status of the employee."
                      example: "active"
                    supervisor_id:
                      type: number
                      description: Employee ID of the Supervisor to be assigned. It needs to belong to a current existing employee and not the same as the one of the employee being updated, otherwise an error will be returned. If sent as null, will unset the employee's supervisor.
                      example: 5
                    custom_attributes:
                      type: object
                      properties:
                        dynamic_{{ field uid }}:
                          type: string
                          description: Dynamic field, represented by unique id.
                          example: "German"
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                "employee[first_name]":
                  description: Employee first name
                  type: string
                "employee[last_name]":
                  description: Employee last name
                  type: string
                "employee[preferred_name]":
                  description: Employee preferred name
                  type: string
                "employee[gender]":
                  description: Employee gender
                  type: string
                  enum:
                    - male
                    - female
                    - diverse
                "employee[position]":
                  description: Employee position
                  type: string
                "employee[department]":
                  description: Employee department
                  type: string
                "employee[hire_date]":
                  type: string
                  example: '2020-01-31'
                  format: date
                  description: "Employee hire date. Format: yyyy-mm-dd"
                  pattern: ^\d{4}-\d{2}-\d{2}$
                "employee[weekly_working_hours]":
                  description: Employee weekly working hours
                  type: number
                "employee[supervisor_id]":
                  description: Employee ID of the Supervisor to be assigned. It needs to belong to a current existing employee and not the same as the one of the employee being updated, otherwise an error will be returned. If sent as null, will unset the employee's supervisor.
                  type: number
                "employee[status]":
                  description: Employee status
                  type: string
                  enum:
                    - onboarding
                    - active
                    - leave
                    - inactive
      responses:
        "200":
          description: Employee is updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EmployeeUpdatedResponse"
        "422":
          description: Employee update failed due to invalid payload
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EmployeeUpdateErrorResponse"

    get:
      security:
        - BearerAuth: []
      tags:
        - Employees
      description: Get Employee by ID
      summary: Get Employee by ID
      parameters:
        - name: employee_id
          in: path
          required: true
          description: Numeric `id` of the employee
          schema:
            type: integer
            format: int32
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EmployeeResponse"
              examples:
                response:
                  value:
                    success: true
                    data:
                      type: Employee
                      attributes:
                        id:
                          label: ID
                          value: 1
                          type: integer
                          universal_id: id
                        first_name:
                          label: First name
                          value: Alexander
                          type: standard
                          universal_id: first_name
                        last_name:
                          label: Last name
                          value: Bergmann
                          type: standard
                          universal_id: last_name
                        preferred_name:
                          label: Name (preferred)
                          value: Alexander Bergmann
                          type: standard
                          universal_id: preferred_name
                        email:
                          label: Email
                          value: alexander.bergmann@demo.email
                          type: standard
                          universal_id: email
                        gender:
                          label: Gender
                          value: male
                          type: standard
                          universal_id: gender
                        status:
                          label: Status
                          value: active
                          type: standard
                          universal_id: status
                        position:
                          label: Position
                          value: CTO
                          type: standard
                          universal_id: position
                        supervisor:
                          label: Supervisor
                          value:
                            type: Employee
                            attributes:
                              id:
                                label: ID
                                value: 2
                                type: integer
                                universal_id: id
                          type: standard
                          universal_id: supervisor
                        employment_type:
                          label: Employment type
                          value: external
                          type: standard
                          universal_id: employment_type
                        weekly_working_hours:
                          label: Weekly hours
                          value: '40'
                          type: standard
                          universal_id: weekly_working_hours
                        hire_date:
                          label: Hire date
                          value: 2014-11-09T00:00:00+01:00
                          type: date
                          universal_id: hire_date
                        contract_end_date:
                          label: Contract ends
                          value: null
                          type: date
                          universal_id: contract_end_date
                        termination_date:
                          label: Termination date
                          value: null
                          type: date
                          universal_id: termination_date
                        termination_type:
                          label: Termination type
                          value: null
                          type: standard
                          universal_id: termination_type
                        termination_reason:
                          label: Termination reason
                          value: null
                          type: standard
                          universal_id: termination_reason
                        probation_period_end:
                          label: Probation period end
                          value: null
                          type: date
                          universal_id: probation_period_end
                        created_at:
                          label: created_at
                          value: '2017-05-23T09:49:03+02:00'
                          type: date
                          universal_id: created_at
                        last_modified_at:
                          label: Last modified
                          value: '2020-11-18T17:33:55+01:00'
                          type: date
                          universal_id: last_modified_at
                        subcompany:
                          label: Subcompany
                          value:
                            type: Subcompany
                            attributes:
                              id: 7033
                              name: CS Demo GmbH
                          type: standard
                          universal_id: subcompany
                        office:
                          label: Workplace
                          value:
                            type: Office
                            attributes:
                              id: 131014
                              name: Munich
                          type: standard
                          universal_id: office
                        department:
                          label: Department
                          value:
                            type: Department
                            attributes:
                              id: 281521
                              name: Customer Support
                          type: standard
                          universal_id: department
                        cost_centers:
                          label: Cost center
                          value:
                            - type: CostCenter
                              attributes:
                                id: 82957
                                name: Cost center 1
                                percentage: 100
                          type: standard
                          universal_id: cost_centers
                        holiday_calendar:
                          label: Public holidays
                          value:
                            type: HolidayCalendar
                            attributes:
                              id: 2
                              name: Deutschland (Bayern) Feiertage
                              country: DE
                              state: Bayern
                          type: standard
                          universal_id: holiday_calendar
                        absence_entitlement:
                          label: Absence entitlement
                          value:
                            - type: TimeOffType
                              attributes:
                                id: 113437
                                name: Paid vacation
                                category: paid_vacation
                                entitlement: 24
                          type: standard
                          universal_id: absence_entitlement
                        work_schedule:
                          label: Work schedule
                          value:
                            type: WorkSchedule
                            attributes:
                              id: 97188
                              name: Full-time, 40 hours without time tracking, (mon,tue,wed,thu,fri)
                              valid_from:
                              monday: '08:00'
                              tuesday: '08:00'
                              wednesday: '08:00'
                              thursday: '08:00'
                              friday: '08:00'
                              saturday: '00:00'
                              sunday: '00:00'
                          type: standard
                          universal_id: work_schedule
                        fix_salary:
                          label: Fix salary
                          value: 3000
                          type: decimal
                          universal_id: fix_salary
                          currency: EUR
                        fix_salary_interval:
                          label: Salary interval
                          value: monthly
                          type: standard
                          universal_id: fix_salary_interval
                        hourly_salary:
                          label: Hourly salary
                          value: 0
                          type: decimal
                          universal_id: hourly_salary
                          currency: EUR
                        last_working_day:
                          label: Last day of work
                          value:
                          type: date
                          universal_id: last_working_day
                        profile_picture:
                          label: Profile Picture
                          value: https://api.personio.de/v1/company/employees/1132888/profile-picture
                          type: standard
                          universal_id: profile_picture
                        team:
                          label: Team
                          value:
                            type: Team
                            attributes:
                              id: 59026
                              name: T_X
                          type: standard
                          universal_id: team
                        dynamic_24407:
                          label: Titel
                          value: Dr
                          universal_id: null
                          type: standard
                        dynamic_21827:
                          label: IBAN
                          value: DE98 8989 9898 0000 8989 00
                          universal_id: iban
                          type: standard
                        dynamic_33400:
                          label: Anniversary Date
                          value: 2021-01-01
                          universal_id: null
                          type: date
                        dynamic_180883:
                          label: Birthday
                          value: 1983-08-18
                          universal_id: date_of_birth
                          type: date
        "404":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Employee404ErrorResponse"
              examples:
                response:
                  value:
                    success: false
                    error:
                      code: 404
                      message: 'Es ist ein Problem aufgetreten '

  /company/employees/{employee_id}/absences/balance:
    parameters:
      - $ref: "#/components/parameters/XPersonioPartnerID"
      - $ref: "#/components/parameters/XPersonioAppID"
    get:
      security:
        - BearerAuth: []
      tags:
        - Employees
      description: Retrieve the absence balance for a specific employee
      summary: Get Absence Balance for Employee
      parameters:
        - name: employee_id
          in: path
          required: true
          description: Numeric `id` of the employee
          schema:
            type: integer
            format: int32
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EmployeeAbsenceBalance"
        "404":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Employee404ErrorResponse"
              examples:
                response:
                  value:
                    success: false
                    error:
                      code: 404
                      message: 'Es ist ein Problem aufgetreten '

  /company/employees/custom-attributes:
    get:
      security:
        - BearerAuth: []
      tags:
        - Employees
      description: "This endpoint is an alias for `/company/employees/attributes`."
      summary: List Allowed Custom Attributes
      parameters:
        - $ref: "#/components/parameters/XPersonioPartnerID"
        - $ref: "#/components/parameters/XPersonioAppID"
      responses:
        "200":
          description: "Please refer to `/company/employees/attributes`"

  /company/employees/attributes:
    get:
      security:
        - BearerAuth: []
      tags:
        - Employees
      description: Lists all the allowed atrributes per API credentials including custom (dynamic) attributes.
      summary: List Allowed Attributes
      parameters:
        - $ref: "#/components/parameters/XPersonioPartnerID"
        - $ref: "#/components/parameters/XPersonioAppID"
      responses:
        "200":
          description: ""
          content:
            application/json:
              examples:
                response:
                  value:
                    success: true
                    data:
                      - key: first_name
                        label: First Name
                        type: standard
                        universal_id: first_name
                        options: []
                      - key: last_name
                        label: Last Name
                        type: standard
                        universal_id: last_name
                        options: []
                      - key: dynamic_1
                        label: IBAN
                        type: standard
                        universal_id: iban
                        options: []
                      - key: dynamic_2
                        label: Marital status
                        type: list
                        universal_id: null
                        options: [
                          "married",
                          "single",
                        ]
                      - key: dynamic_3
                        label: Language Skills
                        type: tags
                        universal_id: null
                        options: [
                          "English",
                          "French",
                          "Spanish",
                          "German"
                        ]

  /company/employees/{employee_id}/profile-picture/{width}:
    parameters:
      - $ref: "#/components/parameters/XPersonioPartnerID"
      - $ref: "#/components/parameters/XPersonioAppID"
    get:
      security:
        - BearerAuth: []
      tags:
        - Employees
      description: "Show employee's profile picture. If profile picture is missing, the 404 error will be thrown. The `Profile Picture` attribute has to be whitelisted."
      summary: Get Employee Profile Picture
      parameters:
        - name: employee_id
          in: path
          required: true
          description: Numeric `id` of the employee
          schema:
            type: integer
            format: int32
        - name: width
          in: path
          required: true
          description: Width of the image. Default is original size
          schema:
            type: integer
            format: int32
      responses:
        "200":
          description: OK
          content:
            image/png:
              schema:
                type: string
                format: binary
        "404":
          description: "When the employee doesn't exist or employee doesn't have profile picture set or Profile Picture attribute is not whitelisted, this error occurs."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Employee404ErrorResponse"
              examples:
                response:
                  value:
                    success: false
                    error:
                      code: 404
                      message: 'Etwas ist schiefgelaufen ...'

  /company/attendances:
    parameters:
      - $ref: "#/components/parameters/XPersonioPartnerID"
      - $ref: "#/components/parameters/XPersonioAppID"
    get:
      security:
        - BearerAuth: []
      tags:
        - Attendances
      description: Fetch attendance data for the company employees. The result can be `paginated` and `filtered` by period, the date and/or time they were updated, and/or specific employee/employees. The result contains a list of attendances.
      summary: List Attendances
      parameters:
        - name: start_date
          in: query
          required: true
          description: First day of the period to be queried. It is inclusive, so the day specified as start_date will also be considered on the results
          schema:
            type: string
            format: date
        - name: end_date
          in: query
          required: true
          description: Last day of the period to be queried. It is inclusive, so the day specified as end_date will also be considered on the results.
          schema:
            type: string
            format: date
        - name: updated_from
          in: query
          required: false
          description: Datetime from when the queried periods have been updated. Same format as updated_at.
            It is inclusive, so the day specified as updated_from will also be considered on the results.
            Can be just the date, or the date and the time, with or without the timezone.
          schema:
            type: string
            format: datetime
        - name: updated_to
          in: query
          required: false
          schema:
            type: string
            format: datetime
          description: Datetime until when the queried periods have been updated. Same format as updated_at.
            It is inclusive, so the day specified as updated_to will also be considered on the results.
            Can be just the date, or the date and the time, with or without the timezone.
        - name: includePending
          in: query
          required: false
          description: Returns AttendancePeriods with a status of pending, rejected and confirmed. For pending periods, the end_date attribute is nullable. The status of each period is included in the response.
          schema:
            type: boolean
        - name: employees[]
          in: query
          required: false
          description: A list of Personio employee ID's to filter the results. The result filters including only attendances of provided employees.
          explode: true
          schema:
            type: array
            items:
              type: integer
            example: ?employees[]=1&employees[]=2
          allowReserved: true
        - name: limit
          in: query
          required: false
          description: Pagination attribute to limit how many attendances are per page
          schema:
            type: integer
            minimum: 1
            default: 200
        - name: offset
          in: query
          required: false
          description: The offset from the first record that would be returned. With 3 results [A, B, C] and an offset of 1, the following two results will be returned [B, C].
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        "200":
          description: "The Attendance periods matching the provided filters"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AttendancePeriodsResponse"
              examples:
                response:
                  value:
                    success: true
                    metadata:
                      total_elements: 2
                      current_page: 0
                      total_pages: 3
                    offset: 0
                    limit: 200
                    data:
                      - id: 1234
                        type: AttendancePeriod
                        attributes:
                          employee: 325659
                          date: '2017-01-17'
                          start_time: '09:00'
                          end_time: '18:00'
                          updated_at: '2017-01-17T16:41:08+00:00'
                          status: 'confirmed'
                          break: 50
                          comment: I was super productive
                          is_holiday: false
                          is_on_time_off: false,
                          project:
                            id: 567
                            type: "Project"
                            attributes:
                              name: "A project name"
                              active: true
                      - id: 1235
                        type: AttendancePeriod
                        attributes:
                          employee: 325660
                          date: '2017-01-18'
                          start_time: '09:30'
                          end_time: '18:30'
                          updated_at: '2017-01-18T16:41:08+01:00'
                          status: 'pending'
                          break: 60
                          comment: I wasn't productive
                          is_holiday: false
                          is_on_time_off: true
                          project: null
        "401":
          $ref: "#/components/responses/401UnauthorizedResponse"
        "403":
          $ref: "#/components/responses/403ForbiddenResponse"

    post:
      security:
        - BearerAuth: []
      tags:
        - Attendances
      description: This endpoint is responsible for adding attendance data for the company employees. It is possible to add attendances for one or many employees at the same time. The payload sent on the request should be a list of attendance periods, in the form of an array containing attendance period objects.
      summary: Create an Attendance
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/AttendanceCreateRequest"
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/NewAttendancePeriodParametersRequest"
        description: List of attendance periods to create
        required: true
      responses:
        "200":
          description: The attendance periods are successfully created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NewAttendancePeriodResponse"
              examples:
                response:
                  value:
                    success: true
                    data:
                      id: [
                        1,
                        2,
                      ]
                      message: 'success'
        "401":
          $ref: "#/components/responses/401UnauthorizedResponse"
        "403":
          $ref: "#/components/responses/403ForbiddenResponse"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AttendanceCreateUpdate400ErrorResponse"
              examples:
                response:
                  value:
                    success: false
                    error:
                      code: 400
                      message: 'Error when trying to insert Attendances periods rows'
                      detailed_message: [
                        {
                          success: true,
                          error_msg: null,
                          id: 1,
                          employee: 1234,
                          date: "2017-01-01",
                          start_time: "09:00",
                          end_time: "18:00",
                          break: 60,
                          comment: "",
                          project_id: 5
                        },
                        {
                          success: false,
                          error_msg: "Existing overlapping attendances periods",
                          id: null,
                          employee: 1234,
                          date: "2017-01-01",
                          start_time: "09:00",
                          end_time: "18:00",
                          break: 60,
                          comment: "",
                          project_id: null
                        }
                      ]

  /company/attendances/{id}:
    parameters:
      - $ref: "#/components/parameters/XPersonioPartnerID"
      - $ref: "#/components/parameters/XPersonioAppID"
    delete:
      security:
        - BearerAuth: []
      tags:
        - Attendances
      description: This endpoint is responsible for deleting attendance data for the
        company employees.
      summary: Delete Attendance by ID
      parameters:
        - name: id
          in: path
          description: ID of the attendance period to delete
          required: true
          schema:
            type: integer
            format: int32
        - name: skip_approval
          in: query
          required: false
          description: "Optional, default value is true. If set to false, the approval status of the attendance period will be \"pending\" if an approval rule is set for the attendances type. The respective approval flow will be triggered."
          schema:
            type: boolean
            default: true
      responses:
        "200":
          description: Success response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeletedAttendanceResponse"
              examples:
                response:
                  value:
                    success: true
                    data:
                      message: 'The attendance period was deleted.'
        "400":
          description: "Bad Request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AttendanceDelete400ErrorResponse"
              examples:
                response:
                  value:
                    success: false
                    error:
                      code: 400
                      message: 'Bad Request'
        "401":
          $ref: "#/components/responses/401UnauthorizedResponse"
        "403":
          $ref: "#/components/responses/403ForbiddenResponse"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Attendance404ErrorResponse"
              examples:
                response:
                  value:
                    success: false
                    error:
                      code: 404
                      message: 'The attendance period was not found.'

    patch:
      security:
        - BearerAuth: []
      tags:
        - Attendances
      description: This endpoint is responsible for updating attendance data for the company employees. Attributes are not required and if not specified, the current value will be used. It is not possible to change the employee id.
      summary: Update Attendance by ID
      parameters:
        - name: id
          in: path
          description: ID of the attendance period to update
          required: true
          schema:
            type: integer
            format: int32
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AttendanceUpdateRequest"
        description: Attendance period data to update. At least one of the properties (`date`, `start_time`, `end_time`, `break`, `comment`, `project_id`, `skip_approval`) is required.
        required: true
      responses:
        "200":
          description: Success response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UpdatedAttendanceResponse"
              examples:
                response:
                  value:
                    success: true
                    data:
                      message: The attendance period was updated.
        "400":
          description: "Bad Request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AttendanceCreateUpdate400ErrorResponse"
              examples:
                response:
                  value:
                    success: false
                    error:
                      code: 400
                      message: Error when trying to insert Attendances periods rows.
        "401":
          $ref: "#/components/responses/401UnauthorizedResponse"
        "403":
          $ref: "#/components/responses/403ForbiddenResponse"
        "404":
          description: Not found response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Attendance404ErrorResponse"
              examples:
                response:
                  value:
                    success: false
                    error:
                      code: 404
                      message: 'The attendance period was not found.'

  /company/attendances/projects:
    parameters:
      - $ref: "#/components/parameters/XPersonioPartnerID"
      - $ref: "#/components/parameters/XPersonioAppID"
    get:
      security:
        - BearerAuth: []
      tags:
        - Projects
      description: Provides a list of all company projects.
      summary: List Projects
      responses:
        "200":
          description: List of projects returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Project"
    post:
      security:
        - BearerAuth: []
      tags:
        - Projects
      description: Creates a project into the company account
      summary: Create a Project
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  example: "A project name"
                active:
                  type: boolean
                  example: true
                  default: false
      responses:
        "200":
          description: Project created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: "#/components/schemas/Project"
        "400":
          description: Invalid data was sent
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: object
                    properties:
                      name:
                        type: array
                        items:
                          type: string
                          example: "Project name cannot be empty"

  /company/attendances/projects/{id}:
    delete:
      security:
        - BearerAuth: []
      tags:
        - Projects
      description: Deletes a project from the company account
      summary: Delete Project by ID
      parameters:
        - name: id
          in: path
          required: true
          description: Numeric `id` of the project
          schema:
            type: integer
            format: int32
      responses:
        "204":
          description: Project was successfully deleted
        "404":
          description: Project does not exist
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: object
                    properties:
                      code:
                        type: integer
                      message:
                        type: string
                        example: "Project 5 not found"
        "409":
          description: There are existing attendances for this project
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: object
                    properties:
                      code:
                        type: integer
                      message:
                        type: string
                        example: "There are existing attendances for this project."

    patch:
      security:
        - BearerAuth: []
      tags:
        - Projects
      description: Updates a project with the given data
      summary: Update Project by ID
      parameters:
        - name: id
          in: path
          required: true
          description: Numeric `id` of the project
          schema:
            type: integer
            format: int32
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: "A project name"
                active:
                  type: boolean
                  description: "Marks the availability of the project"
                  example: true
      responses:
        "200":
          description: Project updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: "#/components/schemas/Project"
        "400":
          description: Invalid data was sent
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: object
                    properties:
                      active:
                        type: array
                        items:
                          type: string
                          example: "Active field needs to be of type boolean"
                      name:
                        type: string
                        description: This field would be included only if the new name is already used by another project
                        example: "Project name already exists"
        "404":
          description: Project not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: "Project 5 not found"


  /company/time-off-types:
    parameters:
      - $ref: "#/components/parameters/XPersonioPartnerID"
      - $ref: "#/components/parameters/XPersonioAppID"
    get:
      security:
        - BearerAuth: []
      tags:
        - Absences
      description: Provides a list of absence types for absences **time unit** set to either **days** or **hours**. For example 'Paid vacation', 'Parental leave' or 'Home office'.
      summary: List Time-Off Types
      parameters:
        - name: limit
          in: query
          required: false
          description: Pagination attribute to limit how many records will be returned per page
          schema:
            type: integer
            minimum: 1
            default: 200
        - name: offset
          in: query
          required: false
          description: Pagination attribute to identify which page you are requesting, by the form of telling an offset from the first record that would be returned.
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/TimeOffTypeResource"
              examples:
                response:
                  value:
                    success: true
                    data:
                      - type: TimeOffType
                        attributes:
                          id: 1234
                          name: 'Paid vacation'
                          category: 'paid_vacation'
                          unit: 'day'
                          approval_required: true

                      - type: TimeOffType
                        attributes:
                          id: 1235
                          name: 'Home office'
                          category: 'offsite_work'
                          unit: 'hour'
                          approval_required: true

  /company/time-offs:
    parameters:
      - $ref: "#/components/parameters/XPersonioPartnerID"
      - $ref: "#/components/parameters/XPersonioAppID"
    get:
      security:
        - BearerAuth: []
      tags:
        - Absences
      description: Fetches absence periods for absences with **time unit** set to **days**. The result can be `paginated` and `filtered` by period and/or specific employee/employees. The result contains a list of absence periods.
      summary: List Time-Offs
      parameters:
        - name: start_date
          in: query
          required: false
          description: First day of the period to be queried. It is inclusive, so the result starts from and including the provided `start_date`
          schema:
            type: string
            format: date
        - name: end_date
          in: query
          required: false
          description: Last day of the period to be queried. It is inclusive, so the result ends on `end_date` including absences from the `end_date`
          schema:
            type: string
            format: date
        - name: updated_from
          in: query
          required: false
          description: Query the periods that created or modified from the date `updated_from`. It is inclusive, so all the periods created or modified from the beginning of the `updated_from` will be included in the results
          schema:
            type: string
            format: date
        - name: updated_to
          in: query
          required: false
          description: Query the periods that created or modified until the date `updated_to`. It is inclusive, so all the periods created or modified until the end of the `updated_to` will be included in the results
          schema:
            type: string
            format: date
        - name: employees[]
          in: query
          required: false
          description: A list of Personio employee ID's to filter the results. The result filters including only absences of provided employees
          explode: true
          schema:
            type: array
            items:
              type: integer
          allowReserved: true
        - name: limit
          in: query
          required: false
          description: Pagination attribute to limit the number of absence periods per page
          schema:
            type: integer
            minimum: 1
            default: 200
        - name: offset
          in: query
          required: false
          description: Pagination attribute to identify which page number you are requesting
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AbsencePeriodsResponse"
              examples:
                response:
                  value:
                    success: true
                    metadata:
                      total_elements: 1
                      current_page: 1
                      total_pages: 1
                    data:
                      - type: TimeOffPeriod
                        attributes:
                          id: 12345
                          status: approved
                          start_date: '2017-12-27T00:00:00+0100'
                          end_date: '2017-12-29T00:00:00+0100'
                          days_count: 3
                          half_day_start: false
                          half_day_end: false
                          time_off_type:
                            type: TimeOffType
                            attributes:
                              id: 54321
                              name: Vacation
                              category: offsite_work
                          employee:
                            type: Employee
                            attributes:
                              id:
                                label: id
                                value: 4567
                                type: integer
                                universal_id: id
                              first_name:
                                label: First name
                                value: Michael
                                type: standard
                                universal_id: first_name
                              last_name:
                                label: Last name
                                value: Miller
                                type: standard
                                universal_id: last_name
                              email:
                                label: Email
                                value: michael.miller@demo.com
                                type: standard
                                universal_id: email
                          certificate:
                            status: not-required
                          created_at: '2017-01-17T10:32:18+0100'
                          updated_at: '2017-01-17T10:32:18+0100'
                    offset: 0,
                    limit: 200,
    post:
      security:
        - BearerAuth: []
      tags:
        - Absences
      description: Adds absence data for absence types with **time unit** set to **days**.
      summary: Create a Time-Off
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/CreateTimeOffPeriodRequest"
        description: Absence data
        required: true
      x-readme:
        code-samples:
          - language: "powershell"
            code: "Auto-generated code snippets for this language may not be supported"
          - language: "php"
            code: "Auto-generated code snippets for this language may not be supported"
      responses:
        "200":
          description: The absence period is successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/AbsencePeriodResponse"
              examples:
                response:
                  value:
                    success: true
                    data:
                      type: TimeOffPeriod
                      attributes:
                        id: 12345
                        status: approved
                        start_date: '2017-12-27T00:00:00+0100'
                        end_date: '2017-12-29T00:00:00+0100'
                        days_count: 3
                        half_day_start: false
                        half_day_end: false
                        time_off_type:
                          type: TimeOffType
                          attributes:
                            id: 54321
                            name: Vacation
                            category: offsite_work
                        employee:
                          type: Employee
                          attributes:
                            id:
                              label: id
                              value: 4567
                              type: integer
                              universal_id: id
                            first_name:
                              label: First name
                              value: Michael
                              type: standard
                              universal_id: first_name
                            last_name:
                              label: Last name
                              value: Miller
                              type: standard
                              universal_id: last_name
                            email:
                              label: Email
                              value: michael.miller@demo.com
                              type: standard
                              universal_id: email
                        certificate:
                          status: not-required
                        created_at: '2017-01-17T10:32:18+0100'
                        created_by: 'API'
                        updated_at: '2017-01-17T10:32:18+0100'
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInsertingAbsenceResponse"
              examples:
                response:
                  value:
                    success: false
                    error:
                      code: 400
                      message: 'Error when trying to insert absence period'

        "404":
          description: Employee or Absence type not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    success: false
                    error:
                      code: 0
                      message: 'Time-off type not found.'

        "422":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorCreateAbsenceResponse"
              examples:
                response:
                  value:
                    success: false
                    error:
                      code: 0
                      message: 'The given data failed to pass validation.'
                      error_data: '{...}'

  /company/time-offs/{id}:
    parameters:
      - $ref: "#/components/parameters/XPersonioPartnerID"
      - $ref: "#/components/parameters/XPersonioAppID"
    delete:
      security:
        - BearerAuth: []
      tags:
        - Absences
      description: Deletes absence period data for absence types with **time unit** set to **days**.
      summary: Delete Time-Off by ID
      parameters:
        - name: id
          in: path
          description: ID of the absence period to delete
          required: true
          schema:
            type: integer
            format: int32
      responses:
        "200":
          description: Success response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeletedAbsenceResponse"
              examples:
                response:
                  value:
                    success: true
                    data:
                      message: The absence period was deleted.
        "400":
          description: Bad request response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorAbsenceResponse"
              examples:
                response:
                  value:
                    success: false
                    error:
                      code: 400
                      message: 'The absence period id is invalid.'
        "404":
          description: Not found response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorAbsenceResponse"
              examples:
                response:
                  value:
                    success: false
                    error:
                      code: 404
                      message: 'The absence period was not found.'
    get:
      security:
        - BearerAuth: []
      tags:
        - Absences
      description: Gets an absence period for absences with **time unit** set to **days**.
      summary: Get Time-Off by ID
      parameters:
        - name: id
          in: path
          required: true
          description: Numeric `id` of the absence period
          schema:
            type: integer
            format: int32
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AbsencePeriodResponse"
              examples:
                response:
                  value:
                    success: true
                    data:
                      type: TimeOffPeriod
                      attributes:
                        id: 12345
                        status: approved
                        start_date: '2017-12-27T00:00:00+0100'
                        end_date: '2017-12-29T00:00:00+0100'
                        days_count: 3
                        half_day_start: false
                        half_day_end: false
                        time_off_type:
                          type: TimeOffType
                          attributes:
                            id: 45678
                            name: Vacation
                            category: offsite_work
                        employee:
                          type: Employee
                          attributes:
                            id:
                              label: id
                              value: 2367
                              type: integer
                              universal_id: id
                            first_name:
                              label: First name
                              value: Michael
                              type: standard
                              universal_id: first_name
                            last_name:
                              label: Last name
                              value: Miller
                              type: standard
                              universal_id: last_name
                            email:
                              label: Email
                              value: michael.miller@demo.com
                              type: standard
                              universal_id: email
                        certificate:
                          status: not-required
                        created_at: '2017-01-17T10:32:18+0100'
                        updated_at: '2017-01-17T10:32:18+0100'

        "404":
          description: Not found response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorAbsenceResponse"
              examples:
                response:
                  value:
                    success: false
                    error:
                      code: 404
                      message: 'The absence period was not found.'
  /company/absence-periods:
    parameters:
      - $ref: "#/components/parameters/XPersonioPartnerID"
      - $ref: "#/components/parameters/XPersonioAppID"
    get:
      security:
        - BearerAuth: [ ]
      tags:
        - Absences
      description: Fetches absence periods for absences with **time unit** set to **hours**. The result can be `paginated` and `filtered` by period and/or specific employee/employees. The result contains a list of hourly absence periods.
      summary: List Absence Periods
      parameters:
        - name: start_date
          in: query
          required: false
          description: When both start_date and end_date values are provided, the list of absences returned is a set that has all absences that intersects the window expressed as [start_date, end_date]. When either value is unspecified, the list of absences returned are unbounded in the direction of the unspecified value.
          schema:
            type: string
            format: date
        - name: end_date
          in: query
          required: false
          description: When both start_date and end_date values are provided, the list of absences returned is a set that has all absences that intersects the window expressed as [start_date, end_date]. When either value is unspecified, the list of absences returned are unbounded in the direction of the unspecified value.
          schema:
            type: string
            format: date
        - name: updated_from
          in: query
          required: false
          description: Filter by periods that were created or modified from the date updated_from. It is inclusive, so all the periods created or modified from the beginning of the updated_from will be included in the results.
          schema:
            type: string
            format: date-time
        - name: updated_to
          in: query
          required: false
          description: Filter by periods that were created or modified until the date updated_to. It is inclusive, so all the periods created or modified until the end of the updated_to will be included in the results.
          schema:
            type: string
            format: date-time
        - name: employees[]
          in: query
          required: false
          description: A list of Personio employee ID's to filter the results. The result filters including only absences of provided employees
          explode: true
          schema:
            type: array
            items:
              type: integer
          allowReserved: true
        - name: absence_types[]
          in: query
          required: false
          description: A list of Personio absence type IDs to filter the results. The result filters including only absences of provided absence types.
          explode: true
          schema:
            type: array
            items:
              type: string
          allowReserved: true
        - name: absence_periods[]
          in: query
          required: false
          description: A list of Personio absence period IDs to filter the results. The result filters including only absences containing the provided ids.
          explode: true
          schema:
            type: array
            items:
              type: string
          allowReserved: true
        - name: limit
          in: query
          required: false
          description: Pagination attribute to limit how many absence periods are returned per page.
          schema:
            type: integer
            minimum: 1
            default: 200
        - name: offset
          in: query
          required: false
          description: Pagination attribute to identify which page you are requesting, by the form of telling an offset from the first record that would be returned.
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HourlyAbsencePeriodsResponse"
              examples:
                response:
                  value:
                    success: true
                    metadata:
                      total_elements: 1
                      current_page: 1
                      total_pages: 1
                    data:
                      - type: AbsencePeriod
                        attributes:
                          id: 9bba303f-0fbc-4514-9958-0befa21923fb
                          measurement_unit: "hour"
                          effective_duration: 960
                          employee:
                            type: Employee
                            attributes:
                              id:
                                label: id
                                value: 2367
                                type: integer
                                universal_id: id
                              first_name:
                                label: First name
                                value: Michael
                                type: standard
                                universal_id: first_name
                              last_name:
                                label: Last name
                                value: Miller
                                type: standard
                                universal_id: last_name
                              email:
                                label: Email
                                value: michael.miller@demo.com
                                type: standard
                                universal_id: email
                          absence_type:
                            type: AbsenceType
                            attributes:
                              id: "9bba303f-0fbc-4514-9958-0befa21923fb"
                              name: "Absence Type Name"
                              time_off_type_id: 45678
                          certificate:
                            status: not-required
                          start: "2022-05-31T22:00:00.0Z"
                          end: "2022-06-02T22:00:00.0Z"
                          half_day_start: true
                          half_day_end: false
                          comment: "this is a comment"
                          origin: "web"
                          status: "approved"
                          created_by: 1
                          created_at: "2022-06-20T14:29:56.510Z"
                          updated_at: "2022-06-20T14:29:56.510Z"
                          approved_at: "2022-06-20T14:29:56.510Z"
                          breakdowns:
                            - date: "2022-06-01"
                              effective_duration: 480
                            - date: "2022-06-02"
                              effective_duration: 480
                    offset: 0,
                    limit: 200,
        "400":
          description: Bad request
          content:
            problem+json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: AbsenceType Not Found
          content:
            problem+json:
              schema:
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: object
                    properties:
                      code:
                        type: integer
                        example: 404
                      message:
                        type: string
                        example: 'models.absence-types.not-found'
        "500":
          description: Internal server error
          content:
            problem+json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    post:
      security:
        - BearerAuth: [ ]
      tags:
        - Absences
      description: Adds absence data for absence types with **time unit** set to **hours**. Note that creating periods for absence types with certificate requirement enabled is not supported!
      summary: Create an Absence Period
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/CreateAbsencePeriodRequest"
        description: Absence data
        required: true
      x-readme:
        code-samples:
          - language: "powershell"
            code: "Auto-generated code snippets for this language may not be supported"
          - language: "php"
            code: "Auto-generated code snippets for this language may not be supported"
      responses:
        "201":
          description: The absence period was successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/HourlyAbsencePeriodResponse"
              examples:
                response:
                  value:
                    success: true
                    data:
                      - type: AbsencePeriod
                        attributes:
                          id: 9bba303f-0fbc-4514-9958-0befa21923fb
                          measurement_unit: "hour"
                          effective_duration: 960
                          employee:
                            type: Employee
                            attributes:
                              id:
                                label: id
                                value: 2367
                                type: integer
                                universal_id: id
                              first_name:
                                label: First name
                                value: Michael
                                type: standard
                                universal_id: first_name
                              last_name:
                                label: Last name
                                value: Miller
                                type: standard
                                universal_id: last_name
                              email:
                                label: Email
                                value: michael.miller@demo.com
                                type: standard
                                universal_id: email
                          absence_type:
                            type: AbsenceType
                            attributes:
                              id: "9bba303f-0fbc-4514-9958-0befa21923fb"
                              name: "Absence Type Name"
                              time_off_type_id: 45678
                          certificate:
                            status: not-required
                          start: "2022-05-31T22:00:00.0Z"
                          end: "2022-06-02T22:00:00.0Z"
                          half_day_start: true
                          half_day_end: false
                          comment: "this is a comment"
                          origin: "web"
                          status: "approved"
                          timezone: "Europe/Berlin"
                          created_by: 1
                          created_at: "2022-06-20T14:29:56.510Z"
                          updated_at: "2022-06-20T14:29:56.510Z"
                          approved_at: "2022-06-20T14:29:56.510Z"
                          breakdowns:
                            - date: "2022-06-01"
                              effective_duration: 480
                            - date: "2022-06-02"
                              effective_duration: 480
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInsertingAbsenceResponse"
              examples:
                response:
                  value:
                    success: false
                    error:
                      code: 400
                      message: 'Error when trying to insert absence period'

        "404":
          description: Employee or Absence type not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    success: false
                    error:
                      code: 0
                      message: 'Absence type not found.'

        "422":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorCreateAbsenceResponse"
              examples:
                response:
                  value:
                    success: false
                    error:
                      code: 0
                      message: 'The given data failed to pass validation.'
                      error_data: '{...}'
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                response:
                  value:
                    success: false
                    error:
                      code: 0
                      message: 'Something went wrong'

  /company/absence-periods/{id}:
    parameters:
      - $ref: "#/components/parameters/XPersonioPartnerID"
      - $ref: "#/components/parameters/XPersonioAppID"
    delete:
      security:
        - BearerAuth: []
      tags:
        - Absences
      description: Deletes absence period data for absence types with **time unit** set to **hours**.
      summary: Delete Absence Period by ID
      parameters:
        - name: id
          in: path
          description: ID of the absence period to delete
          required: true
          schema:
            type: string
            format: uuid
            example: 61fe126b-a7b3-449a-b5ee-3865a6fcc546
      responses:
        "200":
          description: Success response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeletedAbsenceResponse"
              examples:
                response:
                  value:
                    success: true
                    data:
                      message: The absence period was deleted.
        "404":
          description: Not found response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorAbsenceResponse"
              examples:
                response:
                  value:
                    success: false
                    error:
                      code: 404
                      message: 'The absence period was not found.'
        "400":
          description: Bad request response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorAbsenceResponse"
              examples:
                response:
                  value:
                    success: false
                    error:
                      code: 400
                      message: 'The absence period id is invalid.'

  /company/document-categories:
    parameters:
      - $ref: "#/components/parameters/XPersonioPartnerID"
      - $ref: "#/components/parameters/XPersonioAppID"
    get:
      security:
        - BearerAuth: []
      tags:
        - Documents
      description: This endpoint is responsible for fetching all document categories of the company. The result contains a list of document categories.
      summary: List Document Categories
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DocumentCategoriesResponse"
              examples:
                response:
                  value:
                    success: true
                    data:
                      - id: 1
                        type: "DocumentCategory"
                        attributes:
                          name: "Certificates of employment"
                      - id: 2
                        type: "DocumentCategory"
                        attributes:
                          name: "Other documents"
  /company/documents:
    parameters:
      - $ref: "#/components/parameters/XPersonioPartnerID"
      - $ref: "#/components/parameters/XPersonioAppID"
    post:
      security:
        - BearerAuth: []
      tags:
        - Documents
      description: | 
        This endpoint is responsible for uploading documents for the company employees.
        The Documents endpoint has a rate limit of 60 requests per minute.
      summary: Upload Document
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/DocumentUploadRequest"
        description: Data necessary for document upload.
      x-readme:
        code-samples:
          - language: "powershell"
            code: "Auto-generated code snippets for this language may not be supported"
          - language: "php"
            code: "Auto-generated code snippets for this language may not be supported"
          - language: "ruby"
            code: "Auto-generated code snippets for this language may not be supported"
          - language: "java"
            code: "Auto-generated code snippets for this language may not be supported"
      responses:
        "201":
          description: "The document was successfully uploaded to the employees profile"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DocumentUploadSuccessResponse"
              examples:
                response:
                  value:
                    success: true
                    data:
                      id: 1
                      type: "Document"
                      attributes:
                        title: "Personio"
                        date: "2022-02-02"
                        comment: "Enable better organisations"
                        employee:
                          type: "Employee"
                          attributes:
                            id:
                              label: "ID"
                              value: 1
                              type: integer
                              universal_id: "id"
                            first_name:
                              label: "First name"
                              value: "Demo"
                              type: standard
                              universal_id: "first_name"
                            last_name:
                              label: "Last name"
                              value: "Account"
                              type: standard
                              universal_id: "last_name"
                            email:
                              label: "Email"
                              value: "demo.account@demo.de"
                              type: standard
                              universal_id: "email"
                        category:
                          id: 1
                          type: "DocumentCategory"
                          attributes:
                            name: "Other documents"
        "404":
          description: "This status code is returned if the provided employee_id or category_id are not found within the company."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DocumentUploadFailedWithBadDocumentCategoryResponse"
              examples:
                response:
                  value:
                    success: false
                    error:
                      message: "No query results for model [DocumentCategory] 1"
                      code: 0
        "422":
          description: "This status code is returned if the provided request parameters cannot be processed or if the parameters are invalid."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DocumentUploadFailedWithUnsupportedFileTypeResponse"
              examples:
                response:
                  value:
                    success: false
                    error:
                      message: "The given data was invalid."
                      code: 0
                      error_data:
                        file: [
                          "The file must be a file of type: pdf, docx, doc, jpg, zip, png, txt, jpeg, odt, xlsx, rtf, htm, xls, p7s, pptx, pages, rar, ppt, gif, tif, html, msg, asc, tiff, wps, bmp, 7z, csv, ics, vcf, dotx, numbers, eps, gz, ods, otf, odp, odg, rtfd, txz, webarchive, xml, xps, md, fax."
                        ]

  /company/custom-reports/reports:
    get:
      tags:
        - Custom Reports
      parameters:
        - $ref: "#/components/parameters/XPersonioPartnerID"
        - $ref: "#/components/parameters/XPersonioAppID"
        - name: report_ids
          in: query
          schema:
            type: array
            items:
              type: string
          example: eea50309-d1b1-47d6-bc7e-27de7a3ab491, baa50309-d1b1-47d6-bc76-27de7a3ab491
          required: false
          description: A list of report ID's to filter the results.
        - name: status
          in: query
          schema:
            type: string
          example: "up_to_date"
          required: false
          description: The status of the report to filter the results.
      description: This endpoint provides you with metadata about existing custom reports in your Personio account, such as report name, report type, report date / timeframe.
      summary: List Custom Reports
      operationId: listReports
      responses:
        200:
          description: Ok
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/PublicListReportsResponse"
        500:
          description: Internal Server Error
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/PublicAPIException"

  /company/custom-reports/reports/{report_id}:
    get:
      tags:
        - Custom Reports
      parameters:
        - $ref: "#/components/parameters/XPersonioPartnerID"
        - $ref: "#/components/parameters/XPersonioAppID"
        - name: report_id
          in: path
          schema:
            type: string
          example: "eea50309-d1b1-47d6-bc7e-27de7a3ab491"
          description: The ID of the report to filter the result.
          required: true
        - name: locale
          in: query
          description: locale used to translate localized fields.
          schema:
            type: string
          example: "de"
          required: false
        - name: page
          in: query
          description: Pagination parameter to identify the page to return.
          schema:
            type: integer
          example: 1
          required: false
        - name: limit
          in: query
          description: Pagination parameter to limit the number of employees returned per page.
          schema:
            type: integer
          example: 10
          required: false
      description: This endpoint provides you with the data of an existing Custom Report.
      summary: Get Custom Report by ID
      operationId: listReportItems
      responses:
        200:
          description: Ok
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/PublicReportResponse"
        400:
          description: Bad request
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/PublicAPIException"
        404:
          description: Report not found
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/PublicAPIException"
        500:
          description: Internal Server Error
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/PublicAPIException"

  /company/custom-reports/columns:
    get:
      tags:
        - Custom Reports
      parameters:
        - $ref: "#/components/parameters/XPersonioPartnerID"
        - $ref: "#/components/parameters/XPersonioAppID"
        - name: columns
          in: query
          schema:
            type: array
            items:
              type: string
          example: first_name,last_name
          description: The columns to filter the results.
          required: false
        - name: locale
          in: query
          schema:
            type: string
          example: "en"
          description: locale used to translate localized fields.
          required: false
        - name: report_id
          in: query
          schema:
            type: string
          example: "eea50309-d1b1-47d6-bc7e-27de7a3ab491"
          description: The ID of the report to filter the result of the columns. If no ID is passed, all columns for the company are returned.
          required: false
      description: This endpoint provides human-readable labels for report table columns. It is particularly important if you get a report with custom attributes or absence data to match the column IDs to the translation.
      summary: List Custom Report Column Labels
      operationId: listColumns
      responses:
        200:
          description: Ok
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/PublicListColumnsResponse"
        500:
          description: Internal Server Error
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/PublicAPIException"

servers:
  - url: https://api.personio.de/v1
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
  parameters:
    XPersonioPartnerID:
      name: X-Personio-Partner-ID
      in: header
      required: false
      description: The partner identifier
      schema:
        type: string
    XPersonioAppID:
      name: X-Personio-App-ID
      in: header
      required: false
      description: The application identifier
      schema:
        type: string
  schemas:
    Response:
      title: Default response object
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
      required:
        - success
        - data

    DocumentUploadRequest:
      type: object
      properties:
        title:
          type: string
          description: Title of the document. Maximum length is 255 characters.
        comment:
          type: string
          description: Optional comment that can be added to the uploaded document.
        employee_id:
          type: integer
          description: Employee identifier
        category_id:
          type: integer
          description: Document Category identifier
        date:
          type: string
          format: date
          description: "Optional date can be added to the uploaded document. Must follow the format: Y-m-d"
        file:
          type: string
          format: binary
          description: The document that shall be uploaded to an employees profile. Maximum file size is 30MB.
      required:
        - title
        - employee_id
        - category_id
        - file

    DocumentUploadFailedWithBadDocumentCategoryResponse:
      type: object
      allOf:
        - type: object
          properties:
            success:
              type: boolean
              example: false
            error:
              type: object
              properties:
                message:
                  type: string
                  example: "No query results for model [DocumentCategory] 1"
                code:
                  type: integer
                  example: 0

    DocumentUploadFailedWithUnsupportedFileTypeResponse:
      type: object
      allOf:
        - type: object
          properties:
            success:
              type: boolean
              example: false
            error:
              type: object
              properties:
                message:
                  type: string
                  example: "The given data was invalid."
                code:
                  type: integer
                  example: 0
                error_data:
                  type: object
                  properties:
                    file:
                      type: array
                      items:
                        type: string
                        example: "The file must be a file of type: pdf, docx, doc, jpg, zip, png, txt, jpeg, odt, xlsx, rtf, htm, xls, p7s, pptx, pages, rar, ppt, gif, tif, html, msg, asc, tiff, wps, bmp, 7z, csv, ics, vcf, dotx, numbers, eps, gz, ods, otf, odp, odg, rtfd, txz, webarchive, xml, xps, md, fax."

    DocumentUploadSuccessResponse:
      type: object
      allOf:
        - type: object
          properties:
            success:
              type: boolean
              example: true
            data:
              type: object
              properties:
                id:
                  type: integer
                  example: 1
                type:
                  type: string
                  example: "Document"
                attributes:
                  type: object
                  properties:
                    title:
                      type: string
                      example: "Document Title"
                    date:
                      type: string
                      example: "2022-01-01"
                    comment:
                      type: string
                      example: "Optional Test Comment"
                    employee:
                      $ref: "#/components/schemas/DocumentEmployeeResponseObject"
                    category_id:
                      $ref: "#/components/schemas/DocumentCategory"

    DocumentEmployeeResponseObject:
      type: object
      properties:
        id:
          type: object
          properties:
            label:
              type: string
              example: "ID"
            value:
              type: integer
              example: 1
            type:
              type: string
              example: "standard"
            universal_id:
              type: string
              example: "id"
        first_name:
          type: object
          properties:
            label:
              type: string
              example: "First name"
            value:
              type: string
              example: "Michael"
            type:
              type: string
              example: "standard"
            universal_id:
              type: string
              example: "first_name"
        last_name:
          type: object
          properties:
            label:
              type: string
              example: "Last name"
            value:
              type: string
              example: "Dou"
            type:
              type: string
              example: "standard"
            universal_id:
              type: string
              example: "last_name"
        email:
          type: object
          properties:
            label:
              type: string
              example: "Email"
            value:
              type: string
              example: "michaeldou@demo.de"
            type:
              type: string
              example: "standard"
            universal_id:
              type: string
              example: "email"

    DocumentCategoriesResponse:
      type: object
      allOf:
        - type: object
          properties:
            success:
              type: boolean
              example: true
            data:
              type: array
              items:
                $ref: "#/components/schemas/DocumentCategory"

    DocumentCategory:
      type: object
      properties:
        id:
          type: integer
          example: 1
        type:
          type: string
          example: "DocumentCategory"
        attributes:
          type: object
          properties:
            name:
              type: string
              example: "Certificates of employment"

    DeletedAbsenceResponse:
      title: Default response object
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            message:
              example: The absence period was deleted.

    DeletedAttendanceResponse:
      title: Default response object
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            message:
              example: The attendance period was deleted

    UpdatedAttendanceResponse:
      title: Default response object
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            message:
              example: The attendance period was updated.

    ErrorResponse:
      title: Default error response
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: integer
              example: 0
            message:
              example: Something went wrong

    ErrorCreateAbsenceResponse:
      title: Default error response
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: integer
              example: 0
            message:
              example: The given data failed to pass validation.

    ErrorAbsenceResponse:
      title: 404 absence error
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: integer
              example: 404
            message:
              example: The absence period was not found.

    ErrorInsertingAbsenceResponse:
      title: 400 absence error
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: integer
              example: 400
            message:
              example: Error when trying to insert absence period

    AttendanceCreateUpdate400ErrorResponse:
      title: 400 [Bad Request] Attendances Creation Error
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: integer
              example: 400
            message:
              type: string
              example: Error when trying to insert Attendances periods rows
            detailed_message:
              type: array
              items:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error_msg:
                    type: string
                    example: Existing overlapping attendances periods
                  'id':
                    type: integer
                    nullable: true
                    example: null
                  employee:
                    type: integer
                    example: 1234
                  date:
                    type: string
                    example: 2017-01-01
                  start_time:
                    type: string
                    example: 09:00
                  end_time:
                    type: string
                    example: 18:00
                  break:
                    type: integer
                    example: 60
                  comment:
                    type: string
                    example: "Optional Test Comment"
                  project_id:
                    type: integer
                    nullable: true
                    example: null

    AttendanceDelete400ErrorResponse:
      title: 400 [Bad Request] Attendance Error
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: integer
              example: 400
            message:
              example: Bad Request

    Attendance404ErrorResponse:
      title: 404 [Not Found] Attendance Error
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: integer
              example: 404
            message:
              example: The attendance period was not found.

    Employee404ErrorResponse:
      title: 404 [Not Found] Employee Error
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: integer
              example: 0
            message:
              example: Es ist ein Problem aufgetreten

    EmployeeCreatedResponse:
      title: Successfully created employee response
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            id:
              type: number
              example: 1
            message:
              type: string
              example: success

    EmployeeCreationErrorResponse:
      title: Employee creation failed due to invalid payload
      type: object
      properties:
        success:
          type: boolean
        error:
          type: object
          properties:
            code:
              type: number
              example: 422
            message:
              type: string
              example: "Supervisor with ID 1 not found"

    EmployeeUpdatedResponse:
      title: Successfully updated employee response
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            id:
              type: number
              example: 12345
        meta:
          type: array
          items:
            type: string
          default: []

    EmployeeUpdateErrorResponse:
      title: Employee update failed due to invalid payload
      type: object
      properties:
        success:
          type: boolean
        error:
          type: object
          properties:
            code:
              type: number
              example: 422
            message:
              type: string
              example: "Supervisor with ID 1 not found"

    Office:
      type: object
      properties:
        label:
          example: Workplace
        value:
          type: object
          properties:
            type:
              type: string
              example: Office
            attributes:
              type: object
              properties:
                name:
                  example: Munich
        type:
          $ref: '#/components/schemas/TypeEnum'
        universal_id:
          example: office

    Department:
      type: object
      properties:
        label:
          example: Department
        value:
          type: object
          properties:
            type:
              type: string
              example: Department
            attributes:
              type: object
              required:
                - id
                - name
              properties:
                id:
                  type: integer
                  example: 1
                name:
                  type: string
                  example: Marketing
        type:
          $ref: '#/components/schemas/TypeEnum'
        universal_id:
          example: department
    CostCenters:
      type: object
      properties:
        label:
          example: Cost center
        value:
          type: array
          items:
            type: object
            properties:
              type:
                example: CostCenter
              attributes:
                type: object
                properties:
                  name:
                    example: Cost Center One
                  id:
                    type: number
                    example: 1
                  percentage:
                    type: number
                    example: 50
        type:
          $ref: '#/components/schemas/TypeEnum'
        universal_id:
          example: cost_center
    HolidayCalendar:
      type: object
      properties:
        label:
          example: Holiday Calendar
        value:
          type: object
          properties:
            type:
              example: HolidayCalendar
            attributes:
              type: object
              properties:
                id:
                  type: number
                  example: 1
                name:
                  example: DE (Hamburg) Feiertage
                country:
                  example: DE
                state:
                  example: Hamburg
        type:
          $ref: '#/components/schemas/TypeEnum'
        universal_id:
          example: holiday_calendar
    WorkSchedule:
      type: object
      properties:
        label:
          example: WorkSchedule
        value:
          type: object
          properties:
            type:
              example: WorkSchedule
            attributes:
              type: object
              properties:
                id:
                  type: number
                  example: 1
                name:
                  example: Standard Hours
                monday:
                  example: 08:30
                  pattern: ^\d\d:\d\d$
                tuesday:
                  example: 08:30
                  pattern: ^\d\d:\d\d$
                wednesday:
                  example: 08:30
                  pattern: ^\d\d:\d\d$
                thursday:
                  example: 08:30
                  pattern: ^\d\d:\d\d$
                friday:
                  example: 08:30
                  pattern: ^\d\d:\d\d$
                saturday:
                  example: 00:00
                  pattern: ^\d\d:\d\d$
                sunday:
                  example: 00:00
                  pattern: ^\d\d:\d\d$
        type:
          $ref: '#/components/schemas/TypeEnum'
        universal_id:
          example: work_schedule
    Team:
      type: object
      properties:
        label:
          example: Team
        value:
          type: object
          properties:
            type:
              type: string
              example: Team
            attributes:
              type: object
              properties:
                name:
                  example: Management
        type:
          $ref: '#/components/schemas/TypeEnum'
        universal_id:
          example: team

    AbsenceEntitlement:
      type: object
      properties:
        label:
          example: Absence entitlement
        value:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                  - TimeOffType
              attributes:
                type: object
                properties:
                  id:
                    type: integer
                    example: 1
                  name:
                    example: Paid Vacation
                  entitlement:
                    example: 30
      required:
        - label
        - value
    Supervisor:
      type: object
      properties:
        label:
          type: string
          example: Supervisor
        value:
          $ref: "#/components/schemas/ShortEmployee"

    Employee:
      type: object
      properties:
        id:
          type: object
          properties:
            label:
              example: ID
            value:
              example: 1
            type:
              $ref: '#/components/schemas/TypeEnum'
            universal_id:
              example: id
        first_name:
          type: object
          properties:
            label:
              example: First name
            value:
              example: Michael
            type:
              $ref: '#/components/schemas/TypeEnum'
            universal_id:
              example: first_name
        last_name:
          type: object
          properties:
            label:
              example: Last name
            value:
              example: Dou
            type:
              $ref: '#/components/schemas/TypeEnum'
            universal_id:
              example: last_name
        preferred_name:
          type: object
          properties:
            label:
              example: Name (preferred)
            value:
              example: Michael Dou
            type:
              $ref: '#/components/schemas/TypeEnum'
            universal_id:
              example: preferred_name
        email:
          type: object
          properties:
            label:
              example: Email
            value:
              example: michael.dou@personio.de
            type:
              $ref: '#/components/schemas/TypeEnum'
            universal_id:
              example: email
        gender:
          type: object
          properties:
            label:
              example: Gender
            value:
              example: male
            type:
              $ref: '#/components/schemas/TypeEnum'
            universal_id:
              example: gender
        status:
          type: object
          properties:
            label:
              example: Status
            value:
              example: active
            type:
              $ref: '#/components/schemas/TypeEnum'
            universal_id:
              example: status
        position:
          type: object
          properties:
            label:
              example: Position
            value:
              example: Online Marketing Specialist
            type:
              $ref: '#/components/schemas/TypeEnum'
            universal_id:
              example: position
        supervisor:
          $ref: "#/components/schemas/Supervisor"
        employment_type:
          type: object
          properties:
            label:
              example: Employment type
            value:
              example: internal
            type:
              $ref: '#/components/schemas/TypeEnum'
            universal_id:
              example: employment_type
        weekly_working_hours:
          type: object
          properties:
            label:
              example: Weekly hours
            value:
              example: 40
            type:
              $ref: '#/components/schemas/TypeEnum'
            universal_id:
              example: weekly_working_hours
        hire_date:
          type: object
          properties:
            label:
              example: Hire date
            value:
              example: 2012-02-01T00:00:00+0100
            type:
              $ref: '#/components/schemas/TypeEnum'
            universal_id:
              example: hire_date
        contract_end_date:
          type: object
          properties:
            label:
              example: Contact end date
            value:
              example: 2020-02-01T00:00:00+0100
            type:
              $ref: '#/components/schemas/TypeEnum'
            universal_id:
              example: contract_end_date
        termination_date:
          type: object
          properties:
            label:
              example: Termonation date
            value:
              example: 2020-02-01T00:00:00+0100
            type:
              $ref: '#/components/schemas/TypeEnum'
            universal_id:
              example: termination_date
        termination_type:
          type: object
          properties:
            label:
              example: Termonation type
            value:
              example:
            type:
              $ref: '#/components/schemas/TypeEnum'
            universal_id:
              example: termination_type
        termination_reason:
          type: object
          properties:
            label:
              example: Termonation reason
            value:
              example:
            type:
              $ref: '#/components/schemas/TypeEnum'
            universal_id:
              example: termination_reason
        probation_period_end:
          type: object
          properties:
            label:
              example: Probation period end
            value:
              example: 2020-02-01T00:00:00+0100
            type:
              $ref: '#/components/schemas/TypeEnum'
            universal_id:
              example: probation_period_end
        created_at:
          type: object
          properties:
            label:
              example: Created at
            value:
              example: 2018-02-01T00:00:00+0100
            type:
              $ref: '#/components/schemas/TypeEnum'
            universal_id:
              example: created_at
        last_modified_at:
          type: object
          properties:
            label:
              example: Last modified
            value:
              example: '2020-11-18T17:33:55+01:00'
            type:
              $ref: '#/components/schemas/TypeEnum'
            universal_id:
              example: last_modified_at
        subcompany:
          $ref: "#/components/schemas/Office"
        office:
          $ref: "#/components/schemas/Office"
        department:
          $ref: "#/components/schemas/Department"
        cost_centers:
          $ref: "#/components/schemas/CostCenters"
        holiday_calendar:
          $ref: "#/components/schemas/HolidayCalendar"
        work_schedule:
          $ref: "#/components/schemas/WorkSchedule"
        absence_entitlement:
          $ref: "#/components/schemas/AbsenceEntitlement"
        team:
          $ref: "#/components/schemas/Team"
        fix_salary:
          type: object
          properties:
            label:
              example: Fix salary
            value:
              example: 4000
            type:
              $ref: '#/components/schemas/TypeEnum'
            universal_id:
              example: fix_salary
            currency:
              example: EUR
              type: string
        fix_salary_interval:
          type: object
          properties:
            label:
              example: Salary interval
            value:
              example: monthly
            type:
              $ref: '#/components/schemas/TypeEnum'
            universal_id:
              example: fix_salary_interval
        hourly_salary:
          type: object
          properties:
            label:
              example: Hourly salary
            value:
              example: 0
            type:
              $ref: '#/components/schemas/TypeEnum'
            universal_id:
              example: hourly_salary
            currency:
              example: EUR
              type: string
        last_working_day:
          type: object
          properties:
            label:
              example: Last day of work
            value:
              example:
            type:
              $ref: '#/components/schemas/TypeEnum'
            universal_id:
              example: last_working_day
        profile_picture:
          type: object
          properties:
            label:
              example: Profile Picture
            value:
              example: http://api.dev.personio.de/v1/company/employees/1/profile-picture
            type:
              $ref: '#/components/schemas/TypeEnum'
            universal_id:
              example: profile_picture
        dynamic_21827:
          type: object
          properties:
            label:
              example: IBAN
            value:
              example: DE98 8989 9898 0000 8989 00
            type:
              description: The type of the field.
              $ref: '#/components/schemas/TypeEnum'
            universal_id:
              example: iban

    EmployeesResponse:
      title: List of Employees
      allOf:
        - $ref: "#/components/schemas/Response"
        - type: object
          properties:
            metadata:
              type: object
              required:
                - total_elements
                - current_page
                - total_pages
              properties:
                total_elements:
                  type: integer
                  description: The total number of items matching the query filters.
                total_pages:
                  type: integer
                  description: The total number of pages distributing sets of items matching the query filters.
                current_page:
                  type: integer
                  description: Current page number containing the returned set of items matching with the query filters. The page number range is from 0 to total_pages - 1
            offset:
              type: integer
            limit:
              type: integer
            data:
              type: array
              items:
                type: object
                properties:
                  type:
                    example: Employee
                  attributes:
                    $ref: "#/components/schemas/Employee"

    EmployeeResponse:
      title: Employee Response
      allOf:
        - $ref: "#/components/schemas/Response"
        - type: object
          properties:
            data:
              type: object
              properties:
                type:
                  example: Employee
                attributes:
                  $ref: "#/components/schemas/Employee"

    EmployeeAbsenceBalance:
      title: Employee Absence Balance
      type: object
      properties:
        success:
          type: boolean
        data:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
                example: 1234
              name:
                type: string
                example: Paid Vacation
              category:
                type: string
                example: custom_absence
              balance:
                type: number
                description: >
                  Effective balance, as of request date; not deducting any upcoming absence periods,
                  but only what has been taken. If the absence period is currently ongoing,
                  the effective balance only considers the part of the period until today.
                example: 10.5
              available_balance:
                type: number
                description: Available balance is what actually left to be planned (where upcoming absence periods are already deducted).
                example: 8.5

    Project:
      type: object
      properties:
        id:
          type: integer
          example: 1
        type:
          type: string
          example: "Project"
        attributes:
          type: object
          properties:
            name:
              type: string
              example: "Project name"
            active:
              example: true
              description: "Marks the availability of the project. The default value is false."
              type: boolean
            created_at:
              example: "2022-02-01T12:00:00+0100"
              type: string
              format: datetime
            updated_at:
              example: "2022-02-01T12:00:00+0100"
              type: string
              format: datetime

    AttendanceProject:
      type: object
      properties:
        id:
          type: integer
          example: 1
        type:
          type: string
          example: "Project"
        attributes:
          type: object
          properties:
            name:
              type: string
              example: "Project name"
            active:
              example: true
              description: "Marks the availability of the project. When a new project is created, it's set by default to false."
              type: boolean

    Attendance:
      type: object
      properties:
        employee:
          example: 1
          type: integer
        date:
          type: string
          format: date
        start_time:
          type: string
          pattern: ^\d\d:\d\d$
          example: "08:00"
        end_time:
          type: string
          nullable: true
          pattern: ^\d\d:\d\d$
          example: "17:00"
        break:
          type: integer
          example: 60
        comment:
          type: string
          example: "I was productive as hell"
        is_holiday:
          type: boolean
          example: false
        is_on_time_off:
          type: boolean
          example: false
        status:
          type: string
          enum:
            - confirmed
            - pending
            - rejected
        project:
          type: object
          nullable: true
          properties:
            id:
              type: integer
              example: 5
            type:
              type: string
              example: "Project"
            attributes:
              type: object
              properties:
                name:
                  type: string
                  example: "A project name"
                active:
                  type: boolean
                  example: true

    AttendanceCreateRequest:
      type: object
      properties:
        attendances:
          type: array
          items:
            type: object
            required: [employee, date, start_time, break]
            properties:
              employee:
                type: integer
                minimum: 1
                example: 1
              date:
                type: string
                format: date
              start_time:
                type: string
                pattern: ^\d\d:\d\d$
                example: "08:00"
                description: "Format: hh:mm"
              end_time:
                type: string
                nullable: true
                pattern: ^\d\d:\d\d$
                example: "17:00"
                description: "Format: hh:mm"
              break:
                type: integer
                minimum: 0
                example: 60
              comment:
                type: string
                nullable: true
                example: "I was productive as hell"
              project_id:
                type: integer
                nullable: true
                example: 5
          minItems: 1
        skip_approval:
          type: boolean
          description: "Optional, default value is true. If set to false, the approval status of the attendance period will be \"pending\" if an approval rule is set for the attendances type. The respective approval flow will be triggered."

    AttendanceUpdateRequest:
      type: object
      properties:
        date:
          type: string
          format: date
        start_time:
          type: string
          pattern: ^\d\d:\d\d$
          example: "08:00"
          description: "Format: hh:mm"
        end_time:
          type: string
          nullable: true
          pattern: ^\d\d:\d\d$
          example: "17:00"
          description: "Format: hh:mm"
        break:
          type: integer
          minimum: 0
          example: 60
        comment:
          type: string
          nullable: true
          example: "I was productive as hell"
        project_id:
          type: integer
          nullable: true
          example: 5
        skip_approval:
          type: boolean
          description: "Optional, default value is true. If set to false, the approval status of the attendance period will be \"pending\" if an approval rule is set for the attendances type. The respective approval flow will be triggered."

    AttendancePeriodsResponse:
      title: List All Attendance Periods response
      type: object
      allOf:
        - $ref: "#/components/schemas/Response"
        - type: object
          properties:
            metadata:
              type: object
              required:
                - total_elements
                - current_page
                - total_pages
              properties:
                total_elements:
                  type: integer
                  description: The total number of items matching the query filters.
                total_pages:
                  type: integer
                  description: The total number of pages distributing sets of items matching the query filters.
                current_page:
                  type: integer
                  description: Current page number containing the returned set of items matching with the query filters. The page number range is from 0 to total_pages - 1
            offset:
              type: integer
            limit:
              type: integer
            data:
              type: array
              items:
                type: object
                required:
                  - id
                  - type
                  - attributes
                properties:
                  id:
                    type: integer
                    example: 1
                  type:
                    example: AttendancePeriod
                  attributes:
                    $ref: "#/components/schemas/Attendance"

    NewAttendancePeriodParametersRequest:
      title: Create a New Attendance Period request
      type: object
      properties:
        attendances[][employee]:
          type: integer
          description: Employee identifier
        attendances[][date]:
          type: string
          format: date
          description: "Attendance date. Format: yyyy-mm-dd"
          example: '2020-01-31'
        attendances[][start_time]:
          type: string
          pattern: ^\d\d:\d\d$
          description: "Start time. Format: hh:mm"
          example: '08:00'
        attendances[][end_time]:
          type: string
          nullable: true
          pattern: ^\d\d:\d\d$
          description: "End time. Format: hh:mm"
          example: '12:00'
        attendances[]break:
          type: integer
          minimum: 0
          format: int32
          description: Break in minutes
        attendances[][comment]:
          type: string
          nullable: true
          description: Optional comment
        skip_approval:
          type: boolean
          description: "Optional, default value is true. If set to false, the approval status of the attendance period will be \"pending\" if an approval rule is set for the attendances type. The respective approval flow will be triggered."
        project_id:
          type: integer
          nullable: true
          format: int32
          description: The ID of the project
          example: 5
      required:
        - attendances[][employee]
        - attendances[][date]
        - attendances[][start_time]
        - attendances[]break

    NewAttendancePeriodResponse:
      type: object
      allOf:
        - $ref: "#/components/schemas/Response"
        - type: object
          properties:
            data:
              type: object
              properties:
                id:
                  type: array
                  items:
                    type: integer
                    example: 1
                message:
                  example: Success

    TimeOffTypeResource:
      title: Type of time-off resource
      type: object
      properties:
        type:
          type: string
          enum:
            - TimeOffType
          description: Time-off type resource name
        attributes:
          type: object
          properties:
            id:
              type: integer
              description: identifier
              example: 1
            name:
              type: string
              example: Paid vacation
            category:
              type: string
              nullable: true
              enum:
                - family_care
                - maternity_parental_leave
                - child_care
                - short_time_allowance
                - quarantine
                - irrevocable_exemption
                - sick_leave
                - strike_and_lockout
                - public_duty
                - unpaid_suspension
                - paid_vacation
                - unpaid_vacation
                - unexcused_absence
                - offsite_work
                - other
                - undefined
              example: offsite_work
            unit:
              type: string
              enum:
                - day
                - hour
              example: day
            approval_required:
              type: boolean
              example: true

    CreateTimeOffPeriodRequest:
      title: Create time-off periods
      type: object
      properties:
        employee_id:
          type: integer
          description: Employee identifier
        time_off_type_id:
          type: integer
          description: Time-off type identifier
        start_date:
          type: string
          format: date
          description: "Absence start date. Format: yyyy-mm-dd"
          example: '2020-01-31'
        end_date:
          type: string
          format: date
          description: "Absence end date. Format: yyyy-mm-dd"
          example: '2020-01-31'
        half_day_start:
          type: boolean
          example: false
          description: Whether the start date is a half-day off.
        half_day_end:
          type: boolean
          example: false
          description: Whether the end date is a half-day off.
        comment:
          type: string
          example: Some Comment
          description: Optional comment
        skip_approval:
          type: boolean
          example: false
          description: Optional, default value is true. If set to false, the approval status of the absence request will be "pending" if an approval rule is set for the absence type in Personio. The respective approval flow will be triggered.
      required:
        - employee_id
        - time_off_type_id
        - start_date
        - end_date
        - half_day_start
        - half_day_end
    CreateAbsencePeriodRequest:
      title: Create Absence periods with **time unit** set to **hours**
      type: object
      properties:
        employee_id:
          type: integer
          description: Employee identifier
          example: 10735
        time_off_type_id:
          type: integer
          description: Time-off type identifier
          example: 10735
        start_date:
          type: string
          format: date
          description: "Absence start date. Format: yyyy-mm-dd"
          example: '2020-01-31'
        end_date:
          type: string
          format: date
          description: "Absence end date. Format: yyyy-mm-dd"
          example: '2020-01-31'
        start_time:
          type: string
          format: date
          description: "Absence start time. Format: HH:mm (hours and minutes) and only required if the start_date and end_date are the same (partial-day absence)"
          example: '03:00'
        end_time:
          type: string
          format: date
          description: "Absence end time. Format: HH:mm (hours and minutes) and only required if the start_date and end_date are the same (partial-day absence)"
          example: '15:00'
        half_day_start:
          type: boolean
          example: false
          description: Whether the start date is a half-day off, only considered if the start_date and end_date are not the same (more than one day absence)
        half_day_end:
          type: boolean
          example: false
          description: Whether the end date is a half-day off, only considered if the start_date and end_date are not the same (more than one day absence)
        comment:
          type: string
          example: Some Comment
          description: Optional comment
        skip_approval:
          type: boolean
          example: false
          description: Optional, default value is true. If set to false, the approval status of the absence request will be "pending" if an approval rule is set for the absence type in Personio. The respective approval flow will be triggered.
      required:
        - employee_id
        - time_off_type_id
        - start_date
        - end_date
    AbsencePeriodsResponse:
      title: List All Absence Periods response
      type: object
      allOf:
        - $ref: "#/components/schemas/Response"
        - type: object
          properties:
            metadata:
              type: object
              required:
                - total_elements
                - current_page
                - total_pages
              properties:
                total_elements:
                  type: integer
                  description: The total number of items matching the query filters.
                total_pages:
                  type: integer
                  description: The total number of pages distributing sets of items matching the query filters.
                current_page:
                  type: integer
                  description: Current page number containing the returned set of items matching with the query filters. The page number range is from 0 to total_pages - 1
            offset:
              type: integer
            limit:
              type: integer
            data:
              type: array
              items:
                type: object
                required:
                  - type
                  - attributes
                properties:
                  type:
                    example: TimeOffPeriod
                  attributes:
                    $ref: "#/components/schemas/Absence"
    HourlyAbsencePeriodsResponse:
      title: List All Hourly Absence Periods response
      type: object
      allOf:
        - $ref: "#/components/schemas/Response"
        - type: object
          properties:
            metadata:
              type: object
              required:
                - total_elements
                - current_page
                - total_pages
              properties:
                total_elements:
                  type: integer
                  description: The total number of items matching the query filters.
                total_pages:
                  type: integer
                  description: The total number of pages distributing sets of items matching the query filters.
                current_page:
                  type: integer
                  description: Current page number containing the returned set of items matching with the query filters. The page number range is from 0 to total_pages - 1
            offset:
              type: integer
            limit:
              type: integer
            data:
              type: array
              items:
                type: object
                required:
                  - type
                  - attributes
                properties:
                  type:
                    example: AbsencePeriod
                  attributes:
                    $ref: "#/components/schemas/HourlyAbsence"
    HourlyAbsencePeriodResponseAttributes:
      type: object
      required:
        - id
        - employee
        - absence_type_id
        - start
        - half_day_start
        - half_day_end
        - origin
        - status
        - certificate
        - created_by
        - effective_duration
        - created_at
        - updated_at
        - breakdowns
      properties:
        id:
          type: string
          example: 9bba303f-0fbc-4514-9958-0befa21923fb
        measurement_unit:
          type: string
          enum: [minutes]
          example: "minutes"
        effective_duration:
          type: integer
          example: 60
          description: Period effective duration in minutes
        employee:
          $ref: "#/components/schemas/ShortEmployee"
        absence_type_id:
          $ref: "#/components/schemas/AbsenceType"
        certificate:
          type: object
          properties:
            status:
              example: not-required
              type: string
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
          nullable: true
        half_day_start:
          type: boolean
        half_day_end:
          type: boolean
        comment:
          type: string
        origin:
          type: string
          nullable: true
          enum: [web,api,mobile,slack,msteams]
          example: web
        status:
          type: string
          example: approved
        created_by:
          type: integer
          example: 1
          description: "ID of the employee who created the absence period."
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        approved_at:
          type: string
          format: date-time
          nullable: true
        breakdowns:
          type: array
          description: "Breakdowns of effective duration by day of absence."
          items:
            $ref: "#/components/schemas/AbsencePeriodBreakdown"

    AbsencePeriodResponse:
      title: Absence Periods response
      type: object
      allOf:
        - $ref: "#/components/schemas/Response"
        - type: object
          properties:
            data:
              type: object
              required:
                - type
                - attributes
              properties:
                type:
                  example: TimeOffPeriod
                attributes:
                  $ref: "#/components/schemas/Absence"

    HourlyAbsencePeriodResponse:
      title: Absence Periods response
      type: object
      allOf:
        - $ref: "#/components/schemas/Response"
        - type: object
          properties:
            data:
              type: object
              required:
                - type
                - attributes
              properties:
                type:
                  example: AbsencePeriod
                attributes:
                  $ref: "#/components/schemas/HourlyAbsence"

    Absence:
      type: object
      properties:
        id:
          type: integer
          example: 1
        status:
          type: string
          example: approved
        start_date:
          type: string
          example: 2017-12-27T00:00:00+0100
        end_date:
          type: string
          example: 2017-12-79T00:00:00+0100
        days_count:
          type: number
          example: 3
        half_day_start:
          type: boolean
          example: false
        half_day_end:
          type: boolean
          example: false
        time_off_type:
          type: object
          properties:
            type:
              type: string
              example: TimeOffType
            attributes:
              type: object
              properties:
                id:
                  type: integer
                  example: 1
                name:
                  type: string
                  example: Vacation
                category:
                  type: string
                  example: offsite_work
        employee:
          $ref: "#/components/schemas/ShortEmployee"
        certificate:
          type: object
          properties:
            status:
              example: not-required
              type: string
        created_at:
          type: string
          example: 2017-01-17T10:32:18+0100
        created_by:
          type: string
          example: 'API'
          description: "API if the origin is api, otherwise returns an admin employee's name who's account is used to create the absence"
        updated_at:
          type: string
          example: 2017-01-17T10:32:18+0100
    HourlyAbsence:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 61fe126b-a7b3-449a-b5ee-3865a6fcc546
        measurement_unit:
          type: string
          example: "hours"
        effective_duration:
          type: integer
          example: 16
          description: Period effective duration in minutes
        employee:
          $ref: "#/components/schemas/ShortEmployee"
        absence_type:
          $ref: "#/components/schemas/AbsenceType"
        certificate:
          type: object
          properties:
            status:
              example: not-required
              type: string
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
          nullable: true
        half_day_start:
          type: boolean
        half_day_end:
          type: boolean
        comment:
          type: string
        origin:
          type: string
          example: web
        status:
          type: string
          example: approved
        timezone:
          type: string
          example: "Europe/Berlin"
        created_by:
          type: integer
          example: 1
          description: "ID of the employee who created the absence period."
        created_at:
          type: string
          example: 2017-01-17T10:32:18+0100
        updated_at:
          type: string
          example: 2017-01-17T10:32:18+0100
        approved_at:
          type: string
          format: date-time
          nullable: true
        breakdowns:
          type: array
          description: "Breakdowns of effective duration by day of absence."
          items:
            $ref: "#/components/schemas/AbsencePeriodBreakdown"
    AbsenceType:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          format: uuid
          example: 61fe126b-a7b3-449a-b5ee-3865a6fcc546
        name:
          type: string
          example: Absence Type Name
        time_off_type_id:
          type: integer
          example: 1
    AbsencePeriodBreakdown:
      type: object
      required:
        - date
        - effective_duration
      properties:
        date:
          type: string
          format: date
        effective_duration:
          description: Number representing the value of duration in minutes.
          type: integer
          example: 60
    ShortEmployee:
      type: object
      properties:
        type:
          type: string
          example: Employee
        attributes:
          type: object
          properties:
            id:
              type: object
              properties:
                label:
                  example: 1
                value:
                  example: id
                type:
                  $ref: '#/components/schemas/TypeEnum'
                universal_id:
                  example: id
            first_name:
              type: object
              properties:
                label:
                  example: First Name
                value:
                  example: Michael
                type:
                  $ref: '#/components/schemas/TypeEnum'
                universal_id:
                  example: first_name
            last_name:
              type: object
              properties:
                label:
                  example: Last Name
                value:
                  example: Dou
                type:
                  $ref: '#/components/schemas/TypeEnum'
                universal_id:
                  example: last_name
            email:
              type: object
              properties:
                label:
                  example: Email
                value:
                  example: michael.dou@personio.de
                type:
                  $ref: '#/components/schemas/TypeEnum'
                universal_id:
                  example: email

    TypeEnum:
      type: string
      example: standard
      enum:
        - standard
        - date
        - integer
        - decimal
        - list
        - link
        - tags
        - multiline

    PublicListReportsResponse:
      type: object
      properties:
        success:
          type: boolean
        metadata:
          $ref: "#/components/schemas/PublicReportMetaData"
        offset:
          type: integer
        limit:
          type: integer
        data:
          type: array
          items:
            $ref: "#/components/schemas/PublicReportData"

    PublicReportResponse:
      type: object
      properties:
        success:
          type: boolean
        metadata:
          $ref: "#/components/schemas/PublicReportMetaData"
        offset:
          type: integer
          deprecated: true
        limit:
          type: integer
        data:
          type: array
          items:
            $ref: "#/components/schemas/PublicReportItemsData"

    PublicListColumnsResponse:
      type: object
      properties:
        success:
          type: boolean
        metadata:
          $ref: "#/components/schemas/PublicReportMetaData"
        offset:
          type: integer
        limit:
          type: integer
        data:
          $ref: "#/components/schemas/PublicColumnData"

    PublicReportMetaData:
      type: object
      properties:
        total_elements:
          type: integer
        current_page:
          type: integer
        total_pages:
          type: integer

    PublicReportData:
      type: object
      properties:
        type:
          type: string
          example: "Report"
        attributes:
          $ref: "#/components/schemas/PublicReportAttributes"

    PublicReportItemsData:
      type: object
      properties:
        type:
          type: string
          example: "Report"
        attributes:
          oneOf:
            - $ref: "#/components/schemas/PublicReportItemsAttributes"
            - $ref: "#/components/schemas/PublicTimeframeReportItemsAttributes"
            - $ref: "#/components/schemas/PublicHistoricalReportItemsAttributes"

    PublicColumnData:
      type: object
      properties:
        type:
          type: string
          example: "Column"
        attributes:
          type: array
          items:
            $ref: "#/components/schemas/PublicColumnAttributes"

    PublicColumnAttributes:
      type: object
      properties:
        attribute_id:
          type: string
          example: first_name
        human_readable:
          type: string
          example: First Name
        data_type:
          type: string
          example: "TEXT"

    PublicReportAttributes:
      type: object
      properties:
        id:
          type: string
          example: "eb7482f3-2323-43e2-87ed-99d2399e8e22"
        name:
          type: string
          example: Employee vacations past month
        description:
          type: string
          example: Shows vacations of all employees that were taken past month
        author_first_name:
          type: string
          description: Report author
          example: Robert
        author_last_name:
          type: string
          description: Report author
          example: Sirano
        type:
          type: string
          example: point_in_time
          enum:
            - point_in_time
            - historical_data
            - timeframe
        status:
          type: string
          example: up_to_date
          enum:
            - up_to_date
            - updating
            - update_failed
        start_date:
          type: string
          format: date
          example: "2022-09-01"
        end_date:
          type: string
          format: date
          example: "2022-09-30"
        created_at:
          type: string
          format: date-time
          example: "2022-04-10T17:32:28Z"
        updated_at:
          type: string
          format: date-time
          example: "2022-04-10T17:32:28Z"
        data_refreshed_at:
          type: string
          format: date-time
          example: "2022-04-10T17:32:28Z"
        columns:
          type: array
          items:
            type: string
        filters:
          type: array
          items:
            type: object
            properties:
              column:
                type: string
                example: office_id
              comparison:
                type: string
                example: eq
              value:
                type: string
                example: 1
        period_type:
          type: string
          example: fixed
          enum:
            - fixed
            - today
            - last_day_of_this_month
            - this_year
            - last_month
            - last_thirty_days
            - this_month
            - year_to_date

    PublicReportItemsAttributes:
      type: object
      properties:
        id:
          type: string
          example: "eb7482f3-2323-43e2-87ed-99d2399e8e22"
        name:
          type: string
          example: Employee vacations at a specific point in time
        description:
          type: string
          example: Shows vacations of all employees on a specific date
        author_first_name:
          type: string
          description: Report author
          example: Robert
        author_last_name:
          type: string
          description: Report author
          example: Sirano
        type:
          type: string
          example: point_in_time
          enum:
            - point_in_time
        status:
          type: string
          example: created
          enum:
            - up_to_date
            - updating
            - update_failed
        start_date:
          type: string
          format: date-time
          example: "2022-04-10"
        end_date:
          type: string
          format: date-time
          example: "2022-04-10"
        created_at:
          type: string
          format: date-time
          example: "2022-04-10T17:32:28Z"
        updated_at:
          type: string
          format: date-time
          example: "2022-04-10T17:32:28Z"
        data_refreshed_at:
          type: string
          format: date-time
          example: "2022-04-10T17:32:28Z"
        columns:
          type: array
          items:
            type: string
        filters:
          type: array
          items:
            type: object
            properties:
              column:
                type: string
                example: office_id
              comparison:
                type: string
                example: eq
              value:
                type: string
                example: 1
        period_type:
          type: string
          example: fixed
          enum:
            - fixed
            - today
            - yesterday
            - last_day_of_this_week
            - last_day_of_last_week
            - last_day_of_this_month
            - last_day_of_last_month
            - last_day_of_this_quarter
            - last_day_of_last_quarter
            - last_day_of_this_year
            - last_day_of_last_year
        items:
          type: array
          items:
            type: object
            properties:
              employee_id:
                type: integer
                example: 17
              attributes:
                type: array
                items:
                  anyOf:
                    - $ref: "#/components/schemas/DefaultAttribute"
                    - $ref: "#/components/schemas/EntityAttribute"
                    - $ref: "#/components/schemas/DurationAttribute"
                    - $ref: "#/components/schemas/CostCenterAttribute"
                    - $ref: "#/components/schemas/AbsenceOverviewAttribute"
                    - $ref: "#/components/schemas/AbsencePeriodAttribute"
                    - $ref: "#/components/schemas/PerformanceTargetAttribute"
                    - $ref: "#/components/schemas/PerformanceKpiAttribute"
                    - $ref: "#/components/schemas/SalaryAttribute"
                    - $ref: "#/components/schemas/CompensationAttribute"

    PublicTimeframeReportItemsAttributes:
      type: object
      properties:
        id:
          type: string
          example: "eb7482f3-2323-43e2-87ed-99d2399e8e22"
        name:
          type: string
          example: Employee vacations past month
        description:
          type: string
          example: Shows vacations of all employees that were taken past month
        author_first_name:
          type: string
          description: Report author
          example: Robert
        author_last_name:
          type: string
          description: Report author
          example: Sirano
        type:
          type: string
          example: timeframe
          enum:
            - timeframe
        status:
          type: string
          example: created
          enum:
            - up_to_date
            - updating
            - update_failed
        start_date:
          type: string
          format: date-time
          example: "2022-04-01"
        end_date:
          type: string
          format: date-time
          example: "2022-04-10"
        created_at:
          type: string
          format: date-time
          example: "2022-04-10T17:32:28Z"
        updated_at:
          type: string
          format: date-time
          example: "2022-04-10T17:32:28Z"
        data_refreshed_at:
          type: string
          format: date-time
          example: "2022-04-10T17:32:28Z"
        columns:
          type: array
          items:
            type: string
        filters:
          type: array
          items:
            type: object
            properties:
              column:
                type: string
                example: office_id
              comparison:
                type: string
                example: eq
              value:
                type: string
                example: 1
        period_type:
          type: string
          example: fixed
          enum:
            - fixed
            - today
            - yesterday
            - this_week
            - last_week
            - this_month
            - last_month
            - last_thirty_days
            - next_month
            - this_quarter
            - last_quarter
            - this_year
            - year_to_date
            - last_year
            - next_year
        items:
          type: array
          items:
            type: object
            properties:
              employee_id:
                type: integer
                example: 17
              attributes:
                type: array
                items:
                  anyOf:
                    - $ref: "#/components/schemas/DefaultAttribute"
                    - $ref: "#/components/schemas/EntityAttribute"
                    - $ref: "#/components/schemas/DurationAttribute"
                    - $ref: "#/components/schemas/CostCenterAttribute"
                    - $ref: "#/components/schemas/AbsenceOverviewAttribute"
                    - $ref: "#/components/schemas/AbsencePeriodAttribute"
                    - $ref: "#/components/schemas/PerformanceTargetAttribute"
                    - $ref: "#/components/schemas/PerformanceKpiAttribute"
                    - $ref: "#/components/schemas/SalaryAttribute"
                    - $ref: "#/components/schemas/CompensationAttribute"

    PublicHistoricalReportItemsAttributes:
      type: object
      properties:
        id:
          type: string
          example: "eb7482f3-2323-43e2-87ed-99d2399e8e22"
        name:
          type: string
          example: Department changes in the past year
        description:
          type: string
          example: Shows department changes of all employees over the past year
        author_first_name:
          type: string
          description: Report author
          example: Robert
        author_last_name:
          type: string
          description: Report author
          example: Sirano
        type:
          type: string
          example: historical_data
          enum:
            - historical_data
        status:
          type: string
          example: created
          enum:
            - up_to_date
            - updating
            - update_failed
        start_date:
          type: string
          format: date-time
          example: "2022-01-01"
        end_date:
          type: string
          format: date-time
          example: "2022-09-30"
        created_at:
          type: string
          format: date-time
          example: "2022-04-10T17:32:28Z"
        updated_at:
          type: string
          format: date-time
          example: "2022-04-10T17:32:28Z"
        data_refreshed_at:
          type: string
          format: date-time
          example: "2022-04-10T17:32:28Z"
        columns:
          type: array
          items:
            type: string
        filters:
          type: array
          items:
            type: object
            properties:
              column:
                type: string
                example: office_id
              comparison:
                type: string
                example: eq
              value:
                type: string
                example: 1
        period_type:
          type: string
          example: fixed
          enum:
            - fixed
            - today
            - yesterday
            - this_week
            - last_week
            - this_month
            - last_month
            - last_thirty_days
            - next_month
            - this_quarter
            - last_quarter
            - this_year
            - year_to_date
            - last_year
            - next_year
        items:
          type: array
          items:
            type: object
            properties:
              employee_id:
                type: integer
                example: 17
              historical_attributes:
                type: array
                items:
                  anyOf:
                    - $ref: "#/components/schemas/DefaultHistoricalAttribute"
                    - $ref: "#/components/schemas/EntityHistoricalAttribute"
                    - $ref: "#/components/schemas/DurationHistoricalAttribute"
                    - $ref: "#/components/schemas/CostCenterHistoricalAttribute"
                    - $ref: "#/components/schemas/SalaryHistoricalAttribute"

    DefaultAttribute:
      type: object
      properties:
        attribute_id:
          type: string
          example: first_name
        data_type:
          type: string
          enum:
            - TEXT
        value:
          type: string
          example: Robert
        employee_id:
          type: integer
          example: 17

    EntityAttribute:
      type: object
      properties:
        attribute_id:
          type: string
          example: department
        entity_id:
          type: string
          example: 1
        data_type:
          type: string
          enum:
            - ENTITY
        value:
          type: string
          example: IT
        employee_id:
          type: integer
          example: 17

    CostCenterAttribute:
      type: object
      properties:
        attribute_id:
          type: string
          example: cost_center
        data_type:
          type: string
          enum:
            - COST_CENTER
        employee_id:
          type: integer
          example: 17
        cost_centers:
          type: array
          items:
            $ref: "#/components/schemas/CostCenter"

    CostCenter:
      type: object
      properties:
        cost_center_id:
          type: string
          example: 1
        value:
          type: string
          example: Test Center
        weight:
          type: string
          example: 100%

    AbsenceOverviewAttribute:
      type: object
      properties:
        attribute_id:
          type: string
          example: absence_123
        data_type:
          type: string
          enum:
            - ABSENCE_OVERVIEW
        start_date:
          type: string
          format: date
          example: "2022-03-01"
        end_date:
          type: string
          format: date
          example: "2022-03-03"
        duration_days:
          type: string
          example: 2
        duration_hours:
          type: string
          example: 5
        employee_id:
          type: integer
          example: 17

    AbsencePeriodAttribute:
      type: object
      properties:
        attribute_id:
          type: string
          example: "absence_123:periods"
        data_type:
          type: string
          enum:
            - ABSENCE_PERIOD
        start_date:
          type: string
          format: date
          example: "2022-03-01"
        end_date:
          type: string
          format: date
          example: "2022-03-03"
        half_day_at_start:
          type: boolean
        half_day_at_end:
          type: boolean
        employee_id:
          type: integer
          example: 17

    DurationAttribute:
      type: object
      properties:
        attribute_id:
          type: string
          example: attendance_contractual_target_hours
        data_type:
          type: string
          enum:
            - DURATION
        duration:
          type: integer
          example: 10
        employee_id:
          type: integer
          example: 17

    PerformanceTargetAttribute:
      type: object
      properties:
        attribute_id:
          type: string
          example: performance_target_name
        data_type:
          type: string
          enum:
            - PERFORMANCE_TARGET
        employee_id:
          type: integer
          example: 17
        performance_targets:
          type: array
          items:
            $ref: "#/components/schemas/PerformanceTarget"

    PerformanceTarget:
      type: object
      properties:
        performance_target_id:
          type: string
          example: 1
        performance_target_value:
          type: string
          example: 20

    PerformanceKpiAttribute:
      type: object
      properties:
        attribute_id:
          type: string
        data_type:
          type: string
          enum:
            - PERFORMANCE_KPI
        employee_id:
          type: integer
          example: 17
        performance_target_kpis:
          type: array
          items:
            $ref: "#/components/schemas/PerformanceTarget"

    PerformanceTargetKpi:
      type: object
      properties:
        performance_target_id:
          type: string
          example: id_123
        performance_kpis:
          type: array
          items:
            $ref: "#/components/schemas/PerformanceKpi"

    PerformanceKpi:
      type: object
      properties:
        performance_kpi_id:
          type: string
          example: kpi_123
        performance_kpi_value:
          type: string
          example: 14

    SalaryAttribute:
      type: object
      properties:
        attribute_id:
          type: string
          example: salary_123
        data_type:
          type: string
          enum:
            - SALARY
        amount:
          type: string
          example: 12.20
        currency_symbol:
          type: string
          example: $
        employee_id:
          type: integer
          example: 17

    CompensationAttribute:
      type: object
      properties:
        attribute_id:
          type: string
          example: ABCXXX
        data_type:
          type: string
          enum:
            - COMPENSATION
        amount:
          type: string
          example: 12.20
        currency_code:
          type: string
          example: USD
        currency_symbol:
          type: string
          example: $
        overtime_hours:
          type: string
          example: 12
        bonus_type:
          type: string
          example: MAX
        employee_id:
          type: integer
          example: 17

    DefaultHistoricalAttribute:
      type: object
      properties:
        attribute_id:
          type: string
          example: first_name
        data_type:
          type: string
          enum:
            - TEXT
        value:
          type: string
          example: Robert
        employee_id:
          type: integer
          example: 17
        effective_date:
          type: string
          example: 2021-01-01

    DurationHistoricalAttribute:
      type: object
      properties:
        attribute_id:
          type: string
          example: attendance_contractual_target_hours
        data_type:
          type: string
          enum:
            - DURATION
        duration:
          type: integer
          example: 10
        employee_id:
          type: integer
          example: 17
        effective_date:
          type: string
          example: 2021-01-01

    EntityHistoricalAttribute:
      type: object
      properties:
        attribute_id:
          type: string
          example: department
        entity_id:
          type: string
          example: 1
        data_type:
          type: string
          enum:
            - ENTITY
        value:
          type: string
          example: IT
        employee_id:
          type: integer
          example: 17
        effective_date:
          type: string
          example: 2021-01-01

    CostCenterHistoricalAttribute:
      type: object
      properties:
        attribute_id:
          type: string
          example: cost_center
        data_type:
          type: string
          enum:
            - COST_CENTER
        employee_id:
          type: integer
          example: 17
        cost_centers:
          type: array
          items:
            $ref: "#/components/schemas/CostCenter"
        effective_date:
          type: string
          example: 2021-01-01

    SalaryHistoricalAttribute:
      type: object
      properties:
        attribute_id:
          type: string
          example: salary_123
        data_type:
          type: string
          enum:
            - SALARY
        amount:
          type: string
          example: 12.20
        currency_symbol:
          type: string
          example: $
        employee_id:
          type: integer
          example: 17
        effective_date:
          type: string
          example: 2021-01-01

    PublicAPIException:
      type: array
      items:
        $ref: "#/components/schemas/CustomReportsErrorResponse"

    CustomReportsErrorResponse:
      type: object
      properties:
        status:
          type: integer
          example: 500
        trace_id:
          type: string
          example: ABCXXX
        timestamp:
          type: string
          format: date-time
          example: "2020-01-01T00:00:00Z"
        errors:
          type: array
          items:
            $ref: "#/components/schemas/ErrorDetails"

    ErrorDetails:
      type: object
      properties:
        title:
          type: string
          example: Not Found
        details:
          type: string
          example: Report not found
        type:
          type: string
          example: search
        _meta:
          type: array
          items:
            $ref: "#/components/schemas/ErrorMeta"

    ErrorMeta:
      type: object
      properties:
        field:
          type: string
          example: ID
        description:
          type: string
          example: Report ID not found
  examples:
    401UnauthorizedErrorExample:
      value:
        {
          "success": false,
          "error": {
            "message": "Authorization is not provided",
            "code": 401
          }
        }
    403ForbiddenErrorExample:
      value:
        {
          "success": false,
          "error": {
            "message": "Provided authorization is not valid",
            "code": 403
          }
        }
  responses:
    401UnauthorizedResponse:
      description: "Unauthorized Access"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            response:
              $ref: "#/components/examples/401UnauthorizedErrorExample"
    403ForbiddenResponse:
      description: "Forbidden Access"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            response:
              $ref: "#/components/examples/403ForbiddenErrorExample"