openapi: 3.1.0
info:
  title: Absence.io Absences Locations 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: Locations
  description: Operations for retrieving office location information.
paths:
  /locations:
    post:
      operationId: listLocations
      summary: Absence.io List Locations
      description: Retrieve a list of office locations in the organization.
      tags:
      - Locations
      security:
      - HawkAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListRequest'
            examples:
              ListLocationsRequestExample:
                summary: Default listLocations request
                x-microcks-default: true
                value:
                  skip: 0
                  limit: 50
      responses:
        '200':
          description: Successful response with list of locations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocationListResponse'
              examples:
                ListLocations200Example:
                  summary: Default listLocations 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - _id: '500888'
                      name: HQ-SanFrancisco
                      timezone: America/Los_Angeles
                    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
    Location:
      title: Location
      description: An office or work location.
      type: object
      properties:
        _id:
          type: string
          description: Unique identifier of the location.
          example: '500888'
        name:
          type: string
          description: Name of the location.
          example: HQ-SanFrancisco
        timezone:
          type: string
          description: Timezone identifier for this location.
          example: America/Los_Angeles
        country:
          type: string
          description: Country code for the location.
          example: US
    LocationListResponse:
      title: LocationListResponse
      description: Paginated list response containing location records.
      type: object
      properties:
        data:
          type: array
          description: Array of location records.
          items:
            $ref: '#/components/schemas/Location'
        skip:
          type: integer
          example: 0
        limit:
          type: integer
          example: 50
        count:
          type: integer
          example: 5
    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.