openapi: 3.1.0
info:
  title: Absence.io Absences Departments API
  description: The Absence.io REST API allows integration with absence management features. With this API, users can retrieve, create, update, and delete information related to employee absences, allowances, users, departments, locations, and reason types. All requests and responses use JSON format. Authentication uses the Hawk authentication scheme with an API key generated from the Absence.io account settings under Integrations.
  version: 2.0.0
  contact:
    url: https://www.absence.io/contact
  license:
    name: Proprietary
    url: https://www.absence.io/terms-and-conditions/
  x-generated-from: documentation
servers:
- url: https://app.absence.io/api/v2
  description: Production server
tags:
- name: Departments
  description: Operations for retrieving organizational department information.
paths:
  /departments:
    post:
      operationId: listDepartments
      summary: Absence.io List Departments
      description: Retrieve a list of departments in the organization.
      tags:
      - Departments
      security:
      - HawkAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListRequest'
            examples:
              ListDepartmentsRequestExample:
                summary: Default listDepartments request
                x-microcks-default: true
                value:
                  skip: 0
                  limit: 50
      responses:
        '200':
          description: Successful response with list of departments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DepartmentListResponse'
              examples:
                ListDepartments200Example:
                  summary: Default listDepartments 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - _id: '500999'
                      name: Engineering
                      managerId: '500456'
                    skip: 0
                    limit: 50
                    count: 1
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    ListRequest:
      title: ListRequest
      description: Common request body for list operations with pagination and filtering.
      type: object
      properties:
        skip:
          type: integer
          description: Number of records to skip for pagination.
          example: 0
        limit:
          type: integer
          description: Maximum number of records to return per page.
          example: 50
        filter:
          type: object
          description: MongoDB-style filter object. Supports operators like $gte, $lte, $eq.
          example:
            start:
              $gte: '2025-01-01T00:00:00.000Z'
        relations:
          type: array
          description: List of related fields to resolve (dereference IDs to full objects).
          items:
            type: string
          example:
          - assignedToId
          - reasonId
    Department:
      title: Department
      description: An organizational department.
      type: object
      properties:
        _id:
          type: string
          description: Unique identifier of the department.
          example: '500999'
        name:
          type: string
          description: Name of the department.
          example: Engineering
        managerId:
          type: string
          description: ID of the department manager.
          example: '500456'
        parentId:
          type: string
          description: ID of the parent department if hierarchical.
          example: '500000'
    DepartmentListResponse:
      title: DepartmentListResponse
      description: Paginated list response containing department records.
      type: object
      properties:
        data:
          type: array
          description: Array of department records.
          items:
            $ref: '#/components/schemas/Department'
        skip:
          type: integer
          example: 0
        limit:
          type: integer
          example: 50
        count:
          type: integer
          example: 10
    Error:
      title: Error
      description: Error response returned when a request fails.
      type: object
      properties:
        error:
          type: string
          description: Error message describing what went wrong.
          example: Unauthorized
        statusCode:
          type: integer
          description: HTTP status code.
          example: 401
  securitySchemes:
    HawkAuth:
      type: http
      scheme: hawk
      description: Hawk authentication using an API key ID and API key. Generate your API key from your absence.io account profile under the Integrations tab. Use the @hapi/hawk library to generate the Authorization header with SHA256 algorithm.