openapi: 3.2.0
info:
  version: 2.0.0
  title: Rest-Service Waitlists API
  x-logo:
    url: https://lumahealth-assets.s3.us-west-2.amazonaws.com/new_luma_logo_black.png
    backgroundColor: '#FFFFFF'
    altText: Luma Health
  description: OpenAPI [Basic Structure](https://swagger.io/docs/specification/basic-structure/)
servers:
- url: https://api.lumahealth.io/api/v2
security:
- Bearer: []
tags:
- name: waitlists
  description: Patients waiting for an appointment
paths:
  /waitlists:
    get:
      summary: Show a list of waitlists
      operationId: listWaitlists
      tags:
      - waitlists
      parameters:
      - name: patient
        in: query
        schema:
          type: string
      - name: provider
        in: query
        schema:
          type: string
      - name: facility
        in: query
        schema:
          type: string
      - name: offer
        in: query
        schema:
          type: string
      - name: status
        in: query
        schema:
          type: string
          enum:
          - waiting
          - in-flight
          - offered
          - confirming
          - accepted
          - pending
          - declined
      - $ref: '#/components/parameters/userParam'
      - $ref: '#/components/parameters/deletedParam'
      - $ref: '#/components/parameters/createdByParam'
      - $ref: '#/components/parameters/updatedByParam'
      - $ref: '#/components/parameters/createdAtParam'
      - $ref: '#/components/parameters/updatedAtParam'
      - $ref: '#/components/parameters/pageParam'
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/populateParam'
      - $ref: '#/components/parameters/selectParam'
      responses:
        '200':
          description: Returns a list of waitlists
          content:
            application/json:
              schema:
                type: object
                required:
                - response
                - page
                - size
                properties:
                  response:
                    type: array
                    minItems: 0
                    items:
                      $ref: '#/components/schemas/Waitlist'
                  page:
                    type: integer
                    format: int32
                    minimum: 1
                  size:
                    type: integer
                    format: int32
                    minimum: 0
                additionalProperties: false
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
        default:
          description: unexpected error - need to finalize the error codes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      summary: Create waitlists
      operationId: createWaitlists
      tags:
      - waitlists
      requestBody:
        description: Waitlist to create
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Waitlist'
      responses:
        '200':
          description: Returns the created waitlists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Waitlist'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
        default:
          description: unexpected error - need to finalize the error codes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /waitlists/{waitlistId}:
    get:
      summary: Show a single waitlist
      operationId: getWaitlistById
      tags:
      - waitlists
      parameters:
      - name: waitlistId
        in: path
        required: true
        schema:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
      responses:
        '200':
          description: Waitlist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Waitlist'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
        default:
          description: unexpected error - need to finalize the error codes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      summary: Update a waitlist
      operationId: waitlistUpdate
      tags:
      - waitlists
      parameters:
      - name: waitlistId
        in: path
        required: true
        schema:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
      requestBody:
        description: Waitlist proprieties to be updated
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Waitlist'
      responses:
        '200':
          description: Waitlist updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Waitlist'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
    delete:
      summary: Delete a waitlist
      operationId: deleteWaitlist
      tags:
      - waitlists
      parameters:
      - name: waitlistId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Deleted waitlist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Waitlist'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
components:
  parameters:
    pageParam:
      in: query
      name: page
      required: false
      type: integer
      format: int32
      default: 1
      minimum: 1
      schema:
        type: integer
        format: int32
        default: 1
        minimum: 1
    createdAtParam:
      in: query
      name: createdAt
      type: string
      format: date-time
      schema:
        type: string
        format: date-time
      required: false
      description: The date/time when this object was created.
    updatedAtParam:
      in: query
      name: updatedAt
      type: string
      format: date-time
      schema:
        type: string
        format: date-time
      required: false
      description: The date/time when this object was updated.
    updatedByParam:
      in: query
      name: updatedBy
      required: false
      type: string
      pattern: '[0-9a-f]'
      minLength: 24
      maxLength: 24
      schema:
        type: string
        pattern: '[0-9a-f]'
        minLength: 24
        maxLength: 24
      description: The ID of the user who updated this object.
    createdByParam:
      in: query
      name: createdBy
      type: string
      pattern: '[0-9a-f]'
      minLength: 24
      maxLength: 24
      schema:
        type: string
        pattern: '[0-9a-f]'
        minLength: 24
        maxLength: 24
      required: false
      description: The ID of the user who created this object.
    populateParam:
      name: _populate
      in: query
      description: Response properties which will be replaced by the referenced objects, separated by commas.
      required: false
      type: string
      schema:
        type: string
    selectParam:
      name: _select
      in: query
      description: Response properties that should be returned, separated by commas.
      required: false
      type: string
      schema:
        type: string
    deletedParam:
      in: query
      name: deleted
      required: false
      type: number
      enum:
      - 0
      - 1
      schema:
        type: number
        enum:
        - 0
        - 1
      description: Flag for logical deletion where 1 means deleted.
    limitParam:
      name: limit
      in: query
      description: How many items to fetch per page
      required: false
      type: integer
      format: int32
      default: 500
      minimum: 1
      maximum: 1000
      schema:
        type: integer
        format: int32
        default: 500
        minimum: 1
        maximum: 1000
    userParam:
      in: query
      name: user
      required: false
      type: string
      pattern: '[0-9a-f]'
      minLength: 24
      maxLength: 24
      schema:
        type: string
        pattern: '[0-9a-f]'
        minLength: 24
        maxLength: 24
      description: The ID of the root account user.
  schemas:
    userParam:
      in: query
      name: user
      required: false
      type: string
      pattern: '[0-9a-f]'
      minLength: 24
      maxLength: 24
      schema:
        type: string
        pattern: '[0-9a-f]'
        minLength: 24
        maxLength: 24
      description: The ID of the root account user.
    Error:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
    Waitlist:
      type: object
      description: Represents a patient's entry on an appointment waitlist, used to offer earlier appointment slots as they become available. It tracks the offer lifecycle from waiting through offered, accepted, or declined, along with who added the patient to the waitlist (patient, staff, or automatically by the system).
      required:
      - _id
      - name
      properties:
        _id:
          $ref: '#/components/schemas/idParam'
        user:
          $ref: '#/components/schemas/userParam'
        deleted:
          $ref: '#/components/schemas/deletedParam'
        createdBy:
          $ref: '#/components/schemas/createdByParam'
        updatedBy:
          $ref: '#/components/schemas/updatedByParam'
        createdAt:
          $ref: '#/components/schemas/createdAtParam'
        updatedAt:
          $ref: '#/components/schemas/updatedAtParam'
        patient:
          type: string
        provider:
          type: string
        facility:
          type: string
        facilities:
          type: array
          items:
            type: string
        appointmentType:
          type: string
        offer:
          type: string
        status:
          type: string
          enum:
          - waiting
          - in-flight
          - offered
          - confirming
          - accepted
          - pending
          - declined
    idParam:
      in: query
      name: _id
      type: string
      pattern: '[0-9a-f]'
      minLength: 24
      maxLength: 24
      required: false
      schema:
        type: string
        pattern: '[0-9a-f]'
        minLength: 24
        maxLength: 24
      description: Luma's internal ID of an object.
    updatedAtParam:
      in: query
      name: updatedAt
      type: string
      format: date-time
      schema:
        type: string
        format: date-time
      required: false
      description: The date/time when this object was updated.
    createdAtParam:
      in: query
      name: createdAt
      type: string
      format: date-time
      schema:
        type: string
        format: date-time
      required: false
      description: The date/time when this object was created.
    updatedByParam:
      in: query
      name: updatedBy
      required: false
      type: string
      pattern: '[0-9a-f]'
      minLength: 24
      maxLength: 24
      schema:
        type: string
        pattern: '[0-9a-f]'
        minLength: 24
        maxLength: 24
      description: The ID of the user who updated this object.
    deletedParam:
      in: query
      name: deleted
      required: false
      type: number
      enum:
      - 0
      - 1
      schema:
        type: number
        enum:
        - 0
        - 1
      description: Flag for logical deletion where 1 means deleted.
    createdByParam:
      in: query
      name: createdBy
      type: string
      pattern: '[0-9a-f]'
      minLength: 24
      maxLength: 24
      schema:
        type: string
        pattern: '[0-9a-f]'
        minLength: 24
        maxLength: 24
      required: false
      description: The ID of the user who created this object.
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT