openapi: 3.1.0
info:
  title: Absence.io Absences Allowances 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: Allowances
  description: Operations for managing employee leave allowances and balances.
paths:
  /allowances:
    post:
      operationId: listAllowances
      summary: Absence.io List Allowances
      description: Retrieve a paginated list of employee leave allowances with optional filters.
      tags:
      - Allowances
      security:
      - HawkAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListRequest'
            examples:
              ListAllowancesRequestExample:
                summary: Default listAllowances request
                x-microcks-default: true
                value:
                  skip: 0
                  limit: 50
      responses:
        '200':
          description: Successful response with list of allowances
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AllowanceListResponse'
              examples:
                ListAllowances200Example:
                  summary: Default listAllowances 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - _id: '500234'
                      userId: '500456'
                      reasonId: '500789'
                      year: 2025
                      allowance: 25
                      used: 10
                      remaining: 15
                    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:
    AllowanceListResponse:
      title: AllowanceListResponse
      description: Paginated list response containing allowance records.
      type: object
      properties:
        data:
          type: array
          description: Array of allowance records.
          items:
            $ref: '#/components/schemas/Allowance'
        skip:
          type: integer
          example: 0
        limit:
          type: integer
          example: 50
        count:
          type: integer
          example: 50
    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
    Allowance:
      title: Allowance
      description: An employee leave allowance record for a specific reason type and year.
      type: object
      properties:
        _id:
          type: string
          description: Unique identifier of the allowance.
          example: '500234'
        userId:
          type: string
          description: ID of the user this allowance belongs to.
          example: '500456'
        reasonId:
          type: string
          description: ID of the absence reason type this allowance is for.
          example: '500789'
        year:
          type: integer
          description: Calendar year this allowance applies to.
          example: 2025
        allowance:
          type: number
          description: Total number of days allowed.
          example: 25
        used:
          type: number
          description: Number of days used.
          example: 10
        remaining:
          type: number
          description: Number of days remaining.
          example: 15
        carryover:
          type: number
          description: Number of days carried over from the previous year.
          example: 0
    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.