> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maxcare.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List appointment statuses

> Returns the complete normalized appointment-status vocabulary and, for each EHR, the native status strings that map onto it. Static reference data — identical for every organization, safe to cache. Use it instead of pattern-matching on `integrationStatus`: a regex cannot tell 'no cancellations this month' apart from 'we do not recognise this EHR's word for cancelled'. Requires read:appointments scope.



## OpenAPI

````yaml /openapi-v4.json get /appointments/statuses
openapi: 3.0.0
info:
  title: Max AI Public API
  description: API for third-party marketplace apps
  version: '4.0'
  contact: {}
servers:
  - url: https://api.maxcare.ai/v4
security: []
tags: []
paths:
  /appointments/statuses:
    get:
      tags:
        - Appointments
      summary: List appointment statuses
      description: >-
        Returns the complete normalized appointment-status vocabulary and, for
        each EHR, the native status strings that map onto it. Static reference
        data — identical for every organization, safe to cache. Use it instead
        of pattern-matching on `integrationStatus`: a regex cannot tell 'no
        cancellations this month' apart from 'we do not recognise this EHR's
        word for cancelled'. Requires read:appointments scope.
      operationId: AppointmentsPublicController_listAppointmentStatuses
      parameters:
        - name: X-Organization-Id
          in: header
          required: true
          schema:
            type: string
          description: Target clinic organization ID
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAppointmentStatusesSuccessResponse'
        '401':
          description: Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiUnauthorizedResponse'
        '403':
          description: Insufficient scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiForbiddenResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiRateLimitResponse'
      security:
        - api-key: []
components:
  schemas:
    ListAppointmentStatusesSuccessResponse:
      type: object
      properties:
        code:
          type: string
          description: Response code
          example: success
        data:
          $ref: '#/components/schemas/ListAppointmentStatusesResponseData'
      required:
        - code
        - data
    PublicApiUnauthorizedResponse:
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: unauthorized
        message:
          type: string
          description: Human-readable error message
          example: Invalid or missing API key
        trace_id:
          type: string
          description: Trace ID for debugging
          example: 550e8400-e29b-41d4-a716-446655440000
      required:
        - code
        - message
        - trace_id
    PublicApiForbiddenResponse:
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: forbidden
        message:
          type: string
          description: Human-readable error message
          example: Insufficient scope
        trace_id:
          type: string
          description: Trace ID for debugging
          example: 550e8400-e29b-41d4-a716-446655440000
      required:
        - code
        - message
        - trace_id
    PublicApiRateLimitResponse:
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: rate_limit_exceeded
        message:
          type: string
          description: Human-readable error message
          example: Rate limit exceeded. Maximum 1000 requests per 60 seconds.
        trace_id:
          type: string
          description: Trace ID for debugging
          example: 550e8400-e29b-41d4-a716-446655440000
      required:
        - code
        - message
        - trace_id
    ListAppointmentStatusesResponseData:
      type: object
      properties:
        statuses:
          type: array
          items:
            $ref: '#/components/schemas/AppointmentStatusDefinitionResponse'
        mappings:
          description: >-
            Every native EHR status Max AI maps, and what it normalizes to. A
            vendor status absent from this list arrives as `unknown`.
          type: array
          items:
            $ref: '#/components/schemas/AppointmentStatusMappingResponse'
      required:
        - statuses
        - mappings
    AppointmentStatusDefinitionResponse:
      type: object
      properties:
        status:
          type: string
          description: The normalized status value
          enum:
            - scheduled
            - confirmed
            - arrived
            - in_progress
            - completed
            - cancelled
            - no_show
            - rescheduled
            - other
            - unknown
          example: no_show
        description:
          type: string
          description: >-
            What the value means. Read this before writing logic that branches
            on `status`.
          example: Patient did not attend and did not cancel.
        missed:
          type: boolean
          description: >-
            True for statuses that mean the visit did not happen — the
            reactivation/recall set. Equivalent to `status in (cancelled,
            no_show)` today, but read this flag instead of hardcoding the list
            so a future status joins your campaign automatically.
          example: true
      required:
        - status
        - description
        - missed
    AppointmentStatusMappingResponse:
      type: object
      properties:
        integrationStatus:
          type: string
          description: The exact, unmodified EHR status string
          example: CHECKED_IN
        status:
          type: string
          description: The normalized status it maps to
          enum:
            - scheduled
            - confirmed
            - arrived
            - in_progress
            - completed
            - cancelled
            - no_show
            - rescheduled
            - other
            - unknown
          example: arrived
        ehrType:
          type: string
          description: Which EHR emits this status string
          enum:
            - modmed
            - ezderm
          example: modmed
      required:
        - integrationStatus
        - status
        - ehrType
  securitySchemes:
    api-key:
      scheme: bearer
      bearerFormat: JWT
      type: http
      description: Marketplace API key

````