Absence.io Reason Types API

openapi: 3.2.0
info:
  title: Absence.io Absences Reason Types 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: Reason Types
  description: Operations for retrieving absence reason type definitions.
paths:
  /reasontypes:
    post:
      operationId: listReasonTypes
      summary: Absence.io List Reason Types
      description: Retrieve a list of absence reason types defined in the organization (e.g., vacation, sick leave, parental leave).
      tags:
      - Reason Types
      security:
      - HawkAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListRequest'
            examples:
              ListReasonTypesRequestExample:
                summary: Default listReasonTypes request
                x-microcks-default: true
                value:
                  skip: 0
                  limit: 50
      responses:
        '200':
          description: Successful response with list of reason types
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReasonTypeListResponse'
              examples:
                ListReasonTypes200Example:
                  summary: Default listReasonTypes 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - _id: '500789'
                      name: Vacation
                      color: '#4CAF50'
                      requiresApproval: true
                    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
    ReasonTypeListResponse:
      title: ReasonTypeListResponse
      description: Paginated list response containing reason type records.
      type: object
      properties:
        data:
          type: array
          description: Array of reason type records.
          items:
            $ref: '#/components/schemas/ReasonType'
        skip:
          type: integer
          example: 0
        limit:
          type: integer
          example: 50
        count:
          type: integer
          example: 8
    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
    ReasonType:
      title: ReasonType
      description: An absence reason type (e.g., vacation, sick leave, parental leave).
      type: object
      properties:
        _id:
          type: string
          description: Unique identifier of the reason type.
          example: '500789'
        name:
          type: string
          description: Display name of the absence reason.
          example: Vacation
        color:
          type: string
          description: Color code for displaying this absence type in the calendar.
          example: '#4CAF50'
        requiresApproval:
          type: boolean
          description: Whether absences of this type require manager approval.
          example: true
        affectsAllowance:
          type: boolean
          description: Whether absences of this type count against the employee's allowance.
          example: true
  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.