personio-swagger2.yaml

info: {version: '1.0', title: Personnel Data, description: API for reading and writing
    personnel data including data about attendances and absences}
paths:
  /auth:
    post:
      tags: [Auth]
      description: Request Authentication Token
      parameters:
      - {name: client_id, in: query, required: true, description: Client id of the
          downloaded credentials file, type: string}
      - {name: client_secret, in: query, required: true, description: Client secret
          of the downloaded credentials file, type: string}
      responses:
        '200':
          description: Bearer token
          schema:
            allOf:
            - {$ref: '#/definitions/AuthenticationTokenResponse'}
      produces: [application/json]
      summary: Request Authentication Token
      operationId: Request-Authentication-Token
  /company/employees:
    get:
      tags: [Employees]
      parameters:
      - {name: limit, in: query, required: false, description: Pagination attribute
          to limit the number of employees returned per page., minimum: 1, default: 200,
        type: integer}
      - {name: offset, in: query, required: false, description: Pagination attribute
          to identify the first item in the collection to return., minimum: 0, default: 0,
        type: integer}
      - {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.', type: string}
      description: List Company Employees
      responses:
        '200':
          description: ''
          schema: {$ref: '#/definitions/EmployeesResponse'}
        '404':
          description: ''
          examples:
            application/json:
              response:
                value:
                  success: false
                  error: {message: 'Employee [unknown@personio.de] not found'}
      produces: [application/json]
      summary: List Company Employees
      operationId: List-Employees
    post:
      tags: [Employees]
      summary: Create an employee
      description: 'Creates new employee. Status of the employee will be set to `active`
        if `hire_date` provided is in the past. Otherwise status will be set to `onboarding`.
        This endpoint responds with `id` of created employee in case of success.

        '
      responses:
        '200':
          description: Successful creation of a employee
          schema:
            allOf:
            - {$ref: '#/definitions/EmployeeCreatedResponse'}
      parameters:
      - name: body
        in: body
        schema:
          type: object
          properties:
            employee:
              type: object
              properties:
                email: {type: string, example: john.dou@demo.com, description: The
                    email field is required for the employee creation. Updating of
                    this field is not currently supported.}
                first_name: {type: string, example: John}
                last_name: {type: string, example: Dou}
                gender: {type: string, example: male}
                position: {type: string, example: developer}
                subcompany: {type: string, description: The subcompany employee belongs
                    to. Should be predefined in Personio. Otherwise will be ignored
                    with showing meta error in the response., example: ACME}
                department: {type: string, description: The department employee belongs
                    to. Should be predefined in Personio. Otherwise will be ignored
                    with showing meta error in the response., example: IT}
                office: {type: string, description: The office employee belongs to.
                    Should be predefined in Personio. Otherwise will be ignored with
                    showing meta error in the response., example: Madrid}
                hire_date: {type: string, example: '2020-01-31', format: date, description: 'Employee
                    hire date. Format: yyyy-mm-dd', pattern: '^\d{4}-\d{2}-\d{2}$'}
                weekly_hours: {type: number, example: 40}
                custom_attributes:
                  type: object
                  properties:
                    dynamic_{{ field uid }}: {type: string, description: 'Dynamic
                        field, represented by unique id.', example: German}
              required: [email, first_name, last_name]
      consumes: [application/json, application/x-www-form-urlencoded]
      produces: [application/json]
      operationId: Create-Employee
  /company/employees/{employee_id}:
    get:
      tags: [Employees]
      description: Show employee by ID
      parameters:
      - {name: employee_id, in: path, required: true, description: Numeric `id` of
          the employee, format: int32, type: integer}
      responses:
        '200':
          description: ''
          schema: {$ref: '#/definitions/EmployeeResponse'}
        '404':
          description: ''
          schema: {$ref: '#/definitions/Employee404ErrorResponse'}
      produces: [application/json]
      operationId: Get-Employee
      summary: Get Employee
    patch:
      tags: [Employees]
      summary: Update an employee
      description: 'Update existing employee. Note: Updating of Email field is not
        currently supported.

        '
      parameters:
      - {name: employee_id, in: path, required: true, description: Numeric `id` of
          the employee, format: int32, type: integer}
      - name: body
        in: body
        schema:
          type: object
          properties:
            employee:
              type: object
              properties:
                first_name: {type: string, example: John}
                email: {type: string, example: john@example.org}
                last_name: {type: string, example: Dou}
                gender: {type: string, example: male}
                position: {type: string, example: developer}
                subcompany: {type: string, description: The subcompany employee belongs
                    to. Should be predefined in Personio. Otherwise will be ignored
                    with showing meta error in the response., example: ACME}
                department: {type: string, description: The department employee belongs
                    to. Should be predefined in Personio. Otherwise will be ignored
                    with showing meta error in the response., example: IT}
                office: {type: string, description: The office employee belongs to.
                    Should be predefined in Personio. Otherwise will be ignored with
                    showing meta error in the response., example: Madrid}
                hire_date: {type: string, example: '2020-01-31', format: date, description: 'Employee
                    hire date. Format: yyyy-mm-dd', pattern: '^\d{4}-\d{2}-\d{2}$'}
                weekly_hours: {type: number, example: 40}
                custom_attributes:
                  type: object
                  properties:
                    dynamic_{{ field uid }}: {type: string, description: 'Dynamic
                        field, represented by unique id.', example: German}
              required: [email, first_name, last_name]
      responses:
        '200':
          description: Employee is updated
          schema:
            allOf:
            - {$ref: '#/definitions/EmployeeCreatedResponse'}
      consumes: [application/json, application/x-www-form-urlencoded]
      produces: [application/json]
      operationId: Update-Employee
  /company/employees/{employee_id}/absences/balance:
    get:
      tags: [Employees]
      description: Retrieve the absence balance for a specific employee
      parameters:
      - {name: employee_id, in: path, required: true, description: Numeric `id` of
          the employee, format: int32, type: integer}
      responses:
        '200':
          description: ''
          schema: {$ref: '#/definitions/EmployeeAbsenceBalance'}
        '404':
          description: ''
          schema: {$ref: '#/definitions/Employee404ErrorResponse'}
      produces: [application/json]
      summary: Get Absence Balance
      operationId: Get-Absence-Balance
  /company/employees/custom-attributes:
    get:
      tags: [Employees]
      description: Lists all the custom atrributes.
      responses:
        '200':
          description: ''
          schema: {$ref: '#/definitions/EmployeeResponse'}
      parameters: []
      produces: [application/json]
      summary: Get Custom Attributes
      operationId: Get-Custom-Attributes
  /company/employees/{employee_id}/profile-picture/{width}:
    get:
      tags: [Employees]
      description: Show employee's profile picture. If profile picture is missing,
        the 404 error will be thrown. The `Profile Picture` attribute has to be whitelisted.
      parameters:
      - {name: employee_id, in: path, required: true, description: Numeric `id` of
          the employee, format: int32, type: integer}
      - {name: width, in: path, required: true, description: Width of the image. Default
          is original size, format: int32, type: integer}
      responses:
        '200':
          description: OK
          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.
          schema: {$ref: '#/definitions/Employee404ErrorResponse'}
      produces: [image/png, application/json]
      summary: Get Employee Profile Picture
      operationId: Get-Employee-Profile-Picture
  /company/attendances:
    get:
      tags: [Attendances]
      description: Fetch attendance data for the company employees. The result can
        be `paginated` and `filtered` by period, the date and/or time they were updated,
        and/or specific employee/employees. The result contains a list of attendances.
      parameters:
      - {name: start_date, in: query, required: true, description: 'First day of the
          period to be queried. It is inclusive, so the day specified as start_date
          will also be considered on the results', format: date, type: string}
      - {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.', format: date, type: string}
      - {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.', format: datetime, type: string}
      - {name: updated_to, in: query, required: false, 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.', format: datetime, type: string}
      - {name: includePending, in: query, required: false, description: 'Returns AttendancePeriods
          with a status of pending as well as confirmed. In this case, the end_date
          attribute is nullable. The status of each period is included in the response.',
        type: boolean}
      - name: employees[]
        in: query
        required: false
        description: A list of Personio employee ID's to filter the results. The result
          filters including only absences of provided employees
        type: array
        items: {type: integer}
      - {name: limit, in: query, required: false, description: Pagination attribute
          to limit how many attendances are per page, minimum: 1, default: 200, type: integer}
      - {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.', minimum: 0, default: 0,
        type: integer}
      responses:
        '200':
          description: ''
          schema: {$ref: '#/definitions/AttendancePeriodsResponse'}
      produces: [application/json]
      summary: Get Attendance
      operationId: Get-Attendance
    post:
      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.
      responses:
        '200':
          description: The attendance periods are successfullycreated
          schema: {$ref: '#/definitions/NewAttendancePeriodResponse'}
        '400':
          description: Invalid request
          schema: {$ref: '#/definitions/ErrorCreateAttendanceResponse'}
      parameters:
      - description: List of attendance periods to create
        required: true
        name: body
        in: body
        schema:
          type: array
          items:
            allOf:
            - {$ref: '#/definitions/AttendanceCreateRequest'}
      consumes: [application/json, application/x-www-form-urlencoded]
      produces: [application/json]
      summary: Add Attendance
      operationId: Add-Attendance
  /company/attendances/{id}:
    delete:
      tags: [Attendances]
      description: This endpoint is responsible for deleting attendance data for the
        company employees.
      parameters:
      - {name: id, in: path, description: ID of the attendance period to delete, required: true,
        format: int32, type: integer}
      responses:
        '200':
          description: Success response
          schema: {$ref: '#/definitions/DeletedAtendanceResponse'}
        '404':
          description: Not found response
          schema: {$ref: '#/definitions/ErrorAttendanceResponse'}
      produces: [application/json]
      summary: Delete Attendance
      operationId: Delete-Attendance
    patch:
      tags: [Attendances]
      description: This endpoint is responsible for updating attendance data for the
        company employees. Attributes are not required and if not specified, the current
        value will be used. It is not possible to change the employee id.
      parameters:
      - {name: id, in: path, description: ID of the attendance period to update, required: true,
        format: int32, type: integer}
      - description: attendance period data to update
        required: true
        name: body
        in: body
        schema: {$ref: '#/definitions/AttendanceUpdateRequest'}
      responses:
        '200':
          description: Success response
          schema: {$ref: '#/definitions/UpdatedAtendanceResponse'}
        '404':
          description: Not found response
          schema: {$ref: '#/definitions/ErrorAttendanceResponse'}
      consumes: [application/json]
      produces: [application/json]
      summary: Update Attendance
      operationId: Update-Attendance
  /company/time-off-types:
    get:
      tags: [Absences]
      description: Provides a list of available absences types. For example 'Paid
        vacation', 'Parental leave' or 'Home office'
      parameters:
      - {name: limit, in: query, required: false, description: Pagination attribute
          to limit how many records will be returned per page, minimum: 1, default: 200,
        type: integer}
      - {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.', minimum: 0, default: 0,
        type: integer}
      responses:
        '200':
          description: ''
          schema:
            type: object
            properties:
              success: {type: boolean}
              data:
                type: array
                items: {$ref: '#/definitions/TimeOffTypeResource'}
      produces: [application/json]
      summary: Get Absence Types
      operationId: Get-Absence-Types
  /company/time-offs:
    get:
      tags: [Absences]
      description: This endpoint is responsible for fetching absence data for the
        company employees.The result can be `paginated` and `filtered` by period and/or
        specific employee/employees. The result contains a list of absence periods.
      parameters:
      - {name: start_date, in: query, required: false, description: 'First day of
          the period to be queried. It is inclusive, so the result starts from and
          including the provided `start_date`', format: date, type: string}
      - {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`', format: date, type: string}
      - {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', format: date, type: string}
      - {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', format: date, type: string}
      - 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
        type: array
        items: {type: integer}
      - {name: limit, in: query, required: false, description: Pagination attribute
          to limit how many attendances is returning per page, minimum: 1, default: 200,
        type: integer}
      - {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.', minimum: 0, default: 0,
        type: integer}
      responses:
        '200':
          description: ''
          schema: {$ref: '#/definitions/AbsencePeriodsResponse'}
      produces: [application/json]
      summary: Get Absences
      operationId: Get-Absences
    post:
      tags: [Absences]
      description: This endpoint is responsible for adding absence data for the company
        employees.
      responses:
        '201':
          description: The absence period is successfully created
          schema:
            type: object
            properties:
              data: {$ref: '#/definitions/AbsencePeriodResponse'}
        '400':
          description: Invalid request
          schema: {$ref: '#/definitions/ErrorInsertingAbsenceResponse'}
        '404':
          description: Employee or Absence type not found
          schema: {$ref: '#/definitions/ErrorResponse'}
        '422':
          description: Validation error
          schema: {$ref: '#/definitions/ErrorCreateAbsenceResponse'}
      parameters:
      - {name: employee_id, in: formData, required: true, type: integer, description: Employee
          identifier}
      - {name: time_off_type_id, in: formData, required: true, type: integer, description: Time-off
          type identifier}
      - {name: start_date, in: formData, required: true, format: date, type: string,
        description: 'Absence start date. Format: yyyy-mm-dd'}
      - {name: end_date, in: formData, required: true, format: date, type: string,
        description: 'Absence end date. Format: yyyy-mm-dd'}
      - {name: half_day_start, in: formData, required: true, type: boolean, description: Weather
          the start date is a half-day off}
      - {name: half_day_end, in: formData, required: true, type: boolean, description: Weather
          the end date is a half-day off}
      - {name: comment, in: formData, type: string, description: Optional comment}
      - {name: skip_approval, in: formData, type: boolean, 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.'}
      consumes: [application/x-www-form-urlencoded]
      produces: [application/json]
      summary: Add Absence
      operationId: Add-Absence
  /company/time-offs/{id}:
    get:
      tags: [Absences]
      description: Show Absence Period
      parameters:
      - {name: id, in: path, required: true, description: Numeric `id` of the absence
          period, format: int32, type: integer}
      responses:
        '200':
          description: ''
          schema: {$ref: '#/definitions/AbsencePeriodResponse'}
        '404':
          description: Not found response
          schema: {$ref: '#/definitions/ErrorAbsenceResponse'}
      produces: [application/json]
      summary: Get Absence Periode
      operationId: Get-Absence-Periode
    delete:
      tags: [Absences]
      description: This endpoint is responsible for deleting absence period data for
        the company employees.
      parameters:
      - {name: id, in: path, description: ID of the absence period to delete, required: true,
        format: int32, type: integer}
      responses:
        '200':
          description: Success response
          schema: {$ref: '#/definitions/DeletedAbsenceResponse'}
        '404':
          description: Not found response
          schema: {$ref: '#/definitions/ErrorAbsenceResponse'}
      produces: [application/json]
      summary: Delete Absence Period
      operationId: Delete-Absence-Period
swagger: '2.0'
host: api.personio.de
schemes: [https]
basePath: /v1
definitions:
  Response:
    title: Default response object
    type: object
    properties:
      success: {type: boolean}
      data: {type: object}
    required: [success, data]
  DeletedAbsenceResponse:
    title: Default response object
    type: object
    properties:
      success: {type: boolean}
      data:
        type: object
        properties:
          message: {example: The absence period was deleted.}
  DeletedAtendanceResponse:
    title: Default response object
    type: object
    properties:
      success: {type: boolean}
      data:
        type: object
        properties:
          message: {example: The attendance period was deleted}
  UpdatedAtendanceResponse:
    title: Default response object
    type: object
    properties:
      success: {type: boolean}
      data:
        type: object
        properties:
          message: {example: The attendance period was updated.}
  ErrorResponse:
    title: Default error response
    type: object
    properties:
      success: {type: boolean, example: false}
      error:
        type: object
        properties:
          code: {type: integer, example: 0}
          message: {example: Something went wrong}
  ErrorCreateAbsenceResponse:
    title: Default error response
    type: object
    properties:
      success: {type: boolean, example: false}
      error:
        type: object
        properties:
          code: {type: integer, example: 0}
          message: {example: The given data failed to pass validation.}
  ErrorAbsenceResponse:
    title: 404 absense error
    type: object
    properties:
      success: {type: boolean, example: false}
      error:
        type: object
        properties:
          code: {type: integer, example: 404}
          message: {example: The absence period was not found.}
  ErrorInsertingAbsenceResponse:
    title: 400 absense error
    type: object
    properties:
      success: {type: boolean, example: false}
      error:
        type: object
        properties:
          code: {type: integer, example: 400}
          message: {example: Error when trying to insert absence period}
  ErrorCreateAttendanceResponse:
    title: 400 attendances error
    type: object
    properties:
      success: {type: boolean, example: false}
      error:
        type: object
        properties:
          code: {type: integer, example: 400}
          message: {type: string, example: Error when trying to insert Attendances
              periods rows}
          detailed_message:
            type: array
            items:
              type: object
              properties:
                success: {type: boolean, example: false}
                error_msg: {type: string, example: Existing overlapping attendances
                    periods}
                id: {type: integer, example: null, x-nullable: true}
                employee: {type: integer, example: 1234}
                date: {type: string, example: '2017-01-01T00:00:00.000Z'}
                start_time: {type: string, example: '09:00'}
                end_time: {type: string, example: 1080}
                break: {type: integer, example: 60}
                comment: {type: string, example: null}
  ErrorAttendanceResponse:
    title: 404 absense error
    type: object
    properties:
      success: {type: boolean, example: false}
      error:
        type: object
        properties:
          code: {type: integer, example: 404}
          message: {example: The attendance period was not found.}
  Employee404ErrorResponse:
    title: 404 absense error
    type: object
    properties:
      success: {type: boolean, example: false}
      error:
        type: object
        properties:
          code: {type: integer, example: 0}
          message: {example: Es ist ein Problem aufgetreten}
  EmployeeCreatedResponse:
    title: Sucsefully created employee response
    type: object
    properties:
      success: {type: boolean}
      data:
        type: object
        properties:
          id: {type: number, example: 1}
          message: {example: success}
  Office:
    type: object
    properties:
      label: {example: Office}
      value:
        type: object
        properties:
          type: {type: string, example: Office}
          attributes:
            type: object
            properties:
              name: {example: Munich}
  Department:
    type: object
    properties:
      label: {example: Department}
      value:
        type: object
        properties:
          type: {type: string, example: Department}
          attributes:
            type: object
            properties:
              name: {example: Marketing}
  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}
  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}
  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$'}
  Team:
    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]
  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: '#/definitions/ShortEmployee'}
  Employee:
    type: object
    properties:
      id:
        type: object
        properties:
          label: {example: ID}
          value: {example: 1}
      first_name:
        type: object
        properties:
          label: {example: First name}
          value: {example: Michael}
      last_name:
        type: object
        properties:
          label: {example: Last name}
          value: {example: Dou}
      email:
        type: object
        properties:
          label: {example: Email}
          value: {example: michael.dou@personio.de}
      gender:
        type: object
        properties:
          label: {example: Gender}
          value: {example: male}
      status:
        type: object
        properties:
          label: {example: Status}
          value: {example: active}
      position:
        type: object
        properties:
          label: {example: Position}
          value: {example: Online Marketing Specialist}
      supervisor: {$ref: '#/definitions/Supervisor'}
      employment_type:
        type: object
        properties:
          label: {example: Employment type}
          value: {example: internal}
      weekly_working_hours:
        type: object
        properties:
          label: {example: Weekly hours}
          value: {example: 40}
      hire_date:
        type: object
        properties:
          label: {example: Hire date}
          value: {example: '2012-02-01T00:00:00+0100'}
      contract_end_date:
        type: object
        properties:
          label: {example: Contact end date}
          value: {example: '2020-02-01T00:00:00+0100'}
      termination_date:
        type: object
        properties:
          label: {example: Termonation date}
          value: {example: '2020-02-01T00:00:00+0100'}
      termination_type:
        type: object
        properties:
          label: {example: Termonation type}
          value: {example: null}
      termination_reason:
        type: object
        properties:
          label: {example: Termonation reason}
          value: {example: null}
      probation_period_end:
        type: object
        properties:
          label: {example: Probation period end}
          value: {example: '2020-02-01T00:00:00+0100'}
      created_at:
        type: object
        properties:
          label: {example: Created at}
          value: {example: '2018-02-01T00:00:00+0100'}
      last_modified_at:
        type: object
        properties:
          label: {example: Last modified}
          value: {example: '2020-11-18T17:33:55+01:00'}
      subcompany: {$ref: '#/definitions/Office'}
      office: {$ref: '#/definitions/Office'}
      department: {$ref: '#/definitions/Department'}
      cost_centers: {$ref: '#/definitions/CostCenters'}
      holiday_calendar: {$ref: '#/definitions/HolidayCalendar'}
      work_schedule: {$ref: '#/definitions/WorkSchedule'}
      absence_entitlement: {$ref: '#/definitions/AbsenceEntitlement'}
      team: {$ref: '#/definitions/Team'}
      fix_salary:
        type: object
        properties:
          label: {example: Fix salary}
          value: {example: 4000}
      fix_salary_interval:
        type: object
        properties:
          label: {example: Salary interval}
          value: {example: monthly}
      hourly_salary:
        type: object
        properties:
          label: {example: Hourly salary}
          value: {example: 0}
      vacation_day_balance:
        type: object
        properties:
          label: {example: Vacation day balance}
          value: {example: 20.5}
      last_working_day:
        type: object
        properties:
          label: {example: Last day of work}
          value: {example: null}
      profile_picture:
        type: object
        properties:
          label: {example: Profile Picture}
          value: {example: 'http://api.dev.personio.de/v1/company/employees/1/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. It's only visible on custom attributes
            example: standard
            enum: [standard, date, integer, decimal, list, link, tags, multiline]
  EmployeesResponse:
    title: List of Employees
    allOf:
    - {$ref: '#/definitions/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: '#/definitions/Employee'}
  EmployeeResponse:
    title: Employee
    allOf:
    - {$ref: '#/definitions/Response'}
    - type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              type: {example: Employee}
              attributes: {$ref: '#/definitions/Employee'}
  EmployeeAbsenceBalance:
    title: Employee Absence Balance
    type: object
    properties:
      success: {type: boolean}
      data:
        type: array
        items:
          type: object
          properties:
            id: {type: integer, example: 1234}
            name: {type: string, example: Paid Vacation}
            category: {type: string, example: custom_absence}
            balance: {type: number, example: 10.5}
  Attendance:
    type: object
    properties:
      employee: {example: 1, type: integer}
      date: {type: string, format: date}
      start_time: {type: string, pattern: '^\d\d:\d\d$', example: '08:00'}
      end_time: {type: string, pattern: '^\d\d:\d\d$', example: '17:00'}
      break: {type: integer, example: 60}
      comment: {type: string, example: I was productive as hell}
      is_holiday: {type: boolean, example: false}
      is_on_time_off: {type: boolean, example: false}
  AttendanceCreateRequest:
    type: object
    properties:
      employee: {example: 1}
      date: {type: string, format: date}
      start_time: {type: string, pattern: '^\d\d:\d\d$', example: '08:00', description: 'Format:
          hh:mm'}
      end_time: {type: string, pattern: '^\d\d:\d\d$', example: '17:00', description: 'Format:
          hh:mm'}
      break: {type: integer, example: 60}
      comment: {type: string, example: I was productive as hell}
  AttendanceUpdateRequest:
    type: object
    properties:
      date: {type: string, format: date}
      start_time: {type: string, pattern: '^\d\d:\d\d$', example: '08:00', description: 'Format:
          hh:mm'}
      end_time: {type: string, pattern: '^\d\d:\d\d$', example: '17:00', description: 'Format:
          hh:mm'}
      break: {type: integer, example: 60}
      comment: {type: string, example: I was productive as hell}
  AttendancePeriodsResponse:
    title: List All Attenance Periods response
    type: object
    allOf:
    - {$ref: '#/definitions/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: '#/definitions/Attendance'}
  NewAttendancePeriodParametersRequest:
    title: Create a New Attendance Period request
    type: object
    properties:
      attendances[][employee]: {type: integer, description: Employee identifier}
      attendances[][date]: {type: string, format: date, description: 'Attendance date.
          Format: yyyy-mm-dd', example: '2020-01-31'}
      attendances[][start_time]: {type: string, pattern: '^\d\d:\d\d$', description: 'Start
          time. Format: hh:mm', example: '08:00'}
      attendances[][end_time]: {type: string, pattern: '^\d\d:\d\d$', description: 'End
          time. Format: hh:mm', example: '12:00'}
      attendances[]break: {type: integer, format: int32, description: Break in minutes}
      attendances[][comment]: {type: string, description: Optional comment}
    required: ['attendances[][employee]', 'attendances[][date]', 'attendances[][start_time]',
      'attendances[][end_time]', 'attendances[]break', 'attendances[][comment]']
  NewAttendancePeriodResponse:
    type: object
    allOf:
    - {$ref: '#/definitions/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, example: offsite_work, x-nullable: true}
          unit:
            type: string
            enum: [day, hour]
            example: day
          half_day_requests_enabled: {type: boolean, example: true}
          certification_required: {type: boolean, example: false}
          certification_submission_timeframe: {description: The timeframe in days
              under which the employee needs to submit the certification, type: integer,
            example: 2}
          substitute_option:
            type: string
            enum: [disabled, optional, required]
            example: optional
          approval_required: {type: boolean, example: true}
  CreateTimeOffPeriodRequest:
    title: Create time-off periods
    type: object
    properties:
      employee_id: {type: integer, description: Employee identifier}
      time_off_type_id: {type: integer, description: Time-off type identifier}
      start_date: {type: string, format: date, description: 'Absence start date. Format:
          yyyy-mm-dd', example: '2020-01-31'}
      end_date: {type: string, format: date, description: 'Absence end date. Format:
          yyyy-mm-dd', example: '2020-01-31'}
      half_day_start: {type: boolean, example: 0, description: Weather the start date
          is a half-day off}
      half_day_end: {type: boolean, example: 0, description: Weather the end date
          is a half-day off}
      comment: {type: string, example: Some Comment, description: Optional comment}
      skip_approval: {type: boolean, example: 0, description: 'Optional, default value
          is true. If set to false, the approval status of the absence request will
          be "pending" if an approval rule is set for the absence type in Personio.
          The respective approval flow will be triggered.'}
    required: [employee_id, time_off_type_id, start_date, end_date, half_day_start,
      half_day_end]
  AbsencePeriodsResponse:
    title: List All Absence Periods response
    type: object
    allOf:
    - {$ref: '#/definitions/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: '#/definitions/Absence'}
  AbsencePeriodResponse:
    title: Absence Periods response
    type: object
    allOf:
    - {$ref: '#/definitions/Response'}
    - type: object
      properties:
        data:
          type: object
          required: [type, attributes]
          properties:
            type: {example: TimeOffPeriod}
            attributes: {$ref: '#/definitions/Absence'}
  Absence:
    type: object
    properties:
      id: {type: integer, example: 1}
      status: {type: string, example: approved}
      start_date: {type: string, example: '2017-12-27T00:00:00+0100'}
      end_date: {type: string, example: '2017-12-79T00:00:00+0100'}
      days_count: {type: number, example: 3}
      half_day_start: {type: number, example: 0}
      half_day_end: {type: number, example: 0}
      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: '#/definitions/ShortEmployee'}
      certificate:
        type: object
        properties:
          status: {example: not-required, type: string}
      created_at: {type: string, example: '2017-01-17T10:32:18+0100'}
      updated_at: {type: string, example: '2017-01-17T10:32:18+0100'}
  ShortEmployee:
    type: object
    properties:
      type: {type: string, example: Employee}
      attributes:
        type: object
        properties:
          id:
            type: object
            properties:
              label: {example: 1}
              value: {example: id}
          first_name:
            type: object
            properties:
              label: {example: First Name}
              value: {example: Michael}
          last_name:
            type: object
            properties:
              label: {example: Last Name}
              value: {example: Dou}
          email:
            type: object
            properties:
              label: {example: Email}
              value: {example: michael.dou@personio.de}
  AuthenticationTokenResponse:
    title: Request Authentication Token response
    allOf:
    - {$ref: '#/definitions/Response'}
    - type: object
      properties:
        data:
          type: object
          required: [token]
          properties:
            token: {type: string}
securityDefinitions:
  API-Schlüssel: {type: apiKey, in: header, name: Authorization}
x-components: {}
security:
- API-Schlüssel: []