openapi: 3.1.0
info:
  title: Absence.io Absences 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: Absences
  description: Operations for managing employee absence records.
paths:
  /absences:
    post:
      operationId: listAbsences
      summary: Absence.io List Absences
      description: Retrieve a paginated list of employee absences with optional filters and related data resolution.
      tags:
      - Absences
      security:
      - HawkAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListRequest'
            examples:
              ListAbsencesRequestExample:
                summary: Default listAbsences request
                x-microcks-default: true
                value:
                  skip: 0
                  limit: 50
                  filter:
                    start:
                      $gte: '2025-01-01T00:00:00.000Z'
                      $lte: '2025-12-31T23:59:59.999Z'
                  relations:
                  - assignedToId
                  - reasonId
                  - approverId
      responses:
        '200':
          description: Successful response with list of absences
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AbsenceListResponse'
              examples:
                ListAbsences200Example:
                  summary: Default listAbsences 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - _id: '500123'
                      start: '2025-06-01T00:00:00.000Z'
                      end: '2025-06-05T23:59:59.999Z'
                      assignedToId: '500456'
                      reasonId: '500789'
                      status: 1
                      days: 5
                    skip: 0
                    limit: 50
                    count: 1
        '401':
          description: Unauthorized - invalid or missing Hawk credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /absences/{id}:
    get:
      operationId: getAbsence
      summary: Absence.io Get Absence
      description: Retrieve a specific absence record by its unique identifier.
      tags:
      - Absences
      security:
      - HawkAuth: []
      parameters:
      - name: id
        in: path
        required: true
        description: The unique identifier of the absence record.
        schema:
          type: string
          example: '500123'
      responses:
        '200':
          description: Successful response with absence details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Absence'
              examples:
                GetAbsence200Example:
                  summary: Default getAbsence 200 response
                  x-microcks-default: true
                  value:
                    _id: '500123'
                    start: '2025-06-01T00:00:00.000Z'
                    end: '2025-06-05T23:59:59.999Z'
                    assignedToId: '500456'
                    reasonId: '500789'
                    status: 1
                    days: 5
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Absence not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateAbsence
      summary: Absence.io Update Absence
      description: Update an existing absence record by its unique identifier.
      tags:
      - Absences
      security:
      - HawkAuth: []
      parameters:
      - name: id
        in: path
        required: true
        description: The unique identifier of the absence record.
        schema:
          type: string
          example: '500123'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AbsenceInput'
            examples:
              UpdateAbsenceRequestExample:
                summary: Default updateAbsence request
                x-microcks-default: true
                value:
                  start: '2025-06-02T00:00:00.000Z'
                  end: '2025-06-06T23:59:59.999Z'
                  reasonId: '500789'
      responses:
        '200':
          description: Absence updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Absence'
              examples:
                UpdateAbsence200Example:
                  summary: Default updateAbsence 200 response
                  x-microcks-default: true
                  value:
                    _id: '500123'
                    start: '2025-06-02T00:00:00.000Z'
                    end: '2025-06-06T23:59:59.999Z'
                    assignedToId: '500456'
                    reasonId: '500789'
                    status: 1
                    days: 5
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Absence not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteAbsence
      summary: Absence.io Delete Absence
      description: Delete an absence record by its unique identifier.
      tags:
      - Absences
      security:
      - HawkAuth: []
      parameters:
      - name: id
        in: path
        required: true
        description: The unique identifier of the absence record.
        schema:
          type: string
          example: '500123'
      responses:
        '200':
          description: Absence deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              examples:
                DeleteAbsence200Example:
                  summary: Default deleteAbsence 200 response
                  x-microcks-default: true
                  value:
                    success: true
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Absence not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /absences/create:
    post:
      operationId: createAbsence
      summary: Absence.io Create Absence
      description: Create a new absence record for an employee.
      tags:
      - Absences
      security:
      - HawkAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AbsenceInput'
            examples:
              CreateAbsenceRequestExample:
                summary: Default createAbsence request
                x-microcks-default: true
                value:
                  assignedToId: '500456'
                  start: '2025-06-01T00:00:00.000Z'
                  end: '2025-06-05T23:59:59.999Z'
                  reasonId: '500789'
                  comment: Annual leave
      responses:
        '200':
          description: Absence created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Absence'
              examples:
                CreateAbsence200Example:
                  summary: Default createAbsence 200 response
                  x-microcks-default: true
                  value:
                    _id: '500123'
                    start: '2025-06-01T00:00:00.000Z'
                    end: '2025-06-05T23:59:59.999Z'
                    assignedToId: '500456'
                    reasonId: '500789'
                    status: 0
                    days: 5
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    AbsenceInput:
      title: AbsenceInput
      description: Request body for creating or updating an absence record.
      type: object
      properties:
        assignedToId:
          type: string
          description: ID of the user this absence is for.
          example: '500456'
        reasonId:
          type: string
          description: ID of the absence reason type.
          example: '500789'
        start:
          type: string
          format: date-time
          description: Start date and time of the absence.
          example: '2025-06-01T00:00:00.000Z'
        end:
          type: string
          format: date-time
          description: End date and time of the absence.
          example: '2025-06-05T23:59:59.999Z'
        comment:
          type: string
          description: Optional comment or note on the absence.
          example: Annual leave
    AbsenceListResponse:
      title: AbsenceListResponse
      description: Paginated list response containing absence records.
      type: object
      properties:
        data:
          type: array
          description: Array of absence records.
          items:
            $ref: '#/components/schemas/Absence'
        skip:
          type: integer
          description: Number of records skipped.
          example: 0
        limit:
          type: integer
          description: Maximum records per page.
          example: 50
        count:
          type: integer
          description: Total count of matching records.
          example: 25
    SuccessResponse:
      title: SuccessResponse
      description: Generic success response.
      type: object
      properties:
        success:
          type: boolean
          description: Indicates if the operation was successful.
          example: true
    Absence:
      title: Absence
      description: An employee absence record.
      type: object
      properties:
        _id:
          type: string
          description: Unique identifier of the absence.
          example: '500123'
        assignedToId:
          type: string
          description: ID of the user this absence is assigned to.
          example: '500456'
        reasonId:
          type: string
          description: ID of the absence reason type.
          example: '500789'
        approverId:
          type: string
          description: ID of the user who approved this absence.
          example: '500654'
        start:
          type: string
          format: date-time
          description: Start date and time of the absence.
          example: '2025-06-01T00:00:00.000Z'
        end:
          type: string
          format: date-time
          description: End date and time of the absence.
          example: '2025-06-05T23:59:59.999Z'
        days:
          type: number
          description: Number of working days covered by the absence.
          example: 5
        status:
          type: integer
          description: 'Absence approval status: 0=pending, 1=approved, 2=declined.'
          example: 1
        comment:
          type: string
          description: Optional comment or note on the absence.
          example: Annual leave
    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
    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.