> ## 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.

# Read the tracking board

> Whole-day tracking rows for the selected facilities, with counts, freshness and completeness. Poll at the source's `recommendedPollIntervalSeconds`. A snapshot that cannot be read completely is served `stale` while a recent complete one exists, otherwise 503 `snapshot_unavailable` with `Retry-After`. Expansions need extra scopes (see `include`); a denied expansion is a 403, never an omission.



## OpenAPI

````yaml /openapi-v4.json get /patient-tracking/snapshot
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:
  /patient-tracking/snapshot:
    get:
      tags:
        - Patient Tracking
      summary: Read the tracking board
      description: >-
        Whole-day tracking rows for the selected facilities, with counts,
        freshness and completeness. Poll at the source's
        `recommendedPollIntervalSeconds`. A snapshot that cannot be read
        completely is served `stale` while a recent complete one exists,
        otherwise 503 `snapshot_unavailable` with `Retry-After`. Expansions need
        extra scopes (see `include`); a denied expansion is a 403, never an
        omission.
      operationId: PatientTrackingPublicController_getSnapshot
      parameters:
        - name: sourceId
          required: true
          in: query
          description: Tracking source from `GET /v4/patient-tracking/sources`.
          schema:
            type: string
            example: pts_00000000000040008000000000000001
        - name: facilityExternalIds
          required: false
          in: query
          description: >-
            Comma-separated native facility ids. ModMed requires exactly one;
            EZDerm providers are practice-wide and ignore it, but any id sent
            must belong to the source.
          schema:
            type: string
            example: '101'
        - name: providerExternalIds
          required: false
          in: query
          description: >-
            Comma-separated native provider ids, at most 100. Matches the
            primary provider on ModMed and any encounter role on EZDerm (see the
            source's `capabilities.providerFilter`). An id the source does not
            know is a 400.
          schema:
            example: 2001,2002
            type: string
        - name: date
          required: false
          in: query
          description: >-
            Calendar day `YYYY-MM-DD` in the source's timezone. Defaults to
            today there. Future days are refused; EZDerm reads today only
            (`capability_unsupported`).
          schema:
            example: '2026-10-16'
            type: string
        - name: include
          required: false
          in: query
          description: >-
            Comma-separated row expansions: `patient` (read:patients), `contact`
            (read:patients and read:patient_pii), `visitDetails`
            (read:appointments), `insurance` (read:patients and
            read:insurance_policies). A requested expansion without every listed
            scope is a 403 `include_not_permitted`.
          schema:
            example: patient,visitDetails
            type: string
        - 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/PatientTrackingSnapshotSuccessResponse'
        '400':
          description: Missing or invalid request parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiBadRequestResponse'
        '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'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiNotFoundResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiRateLimitResponse'
        '503':
          description: EHR integration unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiServiceUnavailableResponse'
      security:
        - api-key: []
components:
  schemas:
    PatientTrackingSnapshotSuccessResponse:
      type: object
      properties:
        code:
          type: string
          description: Response code
          example: success
        data:
          $ref: '#/components/schemas/PatientTrackingSnapshotDto'
      required:
        - code
        - data
    PublicApiBadRequestResponse:
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: bad_request
        message:
          type: string
          description: Human-readable error message
          example: '''id'' must be a valid UUID'
        trace_id:
          type: string
          description: Trace ID for debugging
          example: 550e8400-e29b-41d4-a716-446655440000
      required:
        - code
        - message
        - trace_id
    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
    PublicApiNotFoundResponse:
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: not_found
        message:
          type: string
          description: Human-readable error message
          example: Resource not found
        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
    PublicApiServiceUnavailableResponse:
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: server_unresponsive
        message:
          type: string
          description: Human-readable error message
          example: EHR integration is not available for this note
        trace_id:
          type: string
          description: Trace ID for debugging
          example: 550e8400-e29b-41d4-a716-446655440000
      required:
        - code
        - message
        - trace_id
    PatientTrackingSnapshotDto:
      type: object
      properties:
        sourceId:
          type: string
          example: pts_00000000000040008000000000000001
        instanceId:
          type: string
          example: ins_00000000000040008000000000000002
        ehr:
          type: string
          enum:
            - ezderm
            - modmed
          example: modmed
        date:
          type: string
          description: Effective `YYYY-MM-DD` in `timezone`
          example: '2026-10-16'
        timezone:
          type: string
          description: IANA zone resolved by the server
          example: America/New_York
        rows:
          type: array
          items:
            $ref: '#/components/schemas/PatientTrackingRowDto'
        counts:
          $ref: '#/components/schemas/PatientTrackingCountsDto'
        freshness:
          $ref: '#/components/schemas/PatientTrackingFreshnessDto'
        completeness:
          $ref: '#/components/schemas/PatientTrackingCompletenessDto'
        access:
          $ref: '#/components/schemas/PatientTrackingAccessDto'
      required:
        - sourceId
        - instanceId
        - ehr
        - date
        - timezone
        - rows
        - counts
        - freshness
        - completeness
        - access
    PatientTrackingRowDto:
      type: object
      properties:
        trackingKey:
          type: string
          description: Stable 64-char hex row identity
          example: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
        recordKind:
          type: string
          enum:
            - ezderm_encounter
            - modmed_appointment
          example: modmed_appointment
        nativeId:
          type: string
          example: '90001'
        patientDisplay:
          $ref: '#/components/schemas/PatientTrackingPatientDisplayDto'
        patient:
          description: Only with `include=patient`
          allOf:
            - $ref: '#/components/schemas/PatientTrackingPatientExpansionDto'
        contact:
          description: Only with `include=contact`
          allOf:
            - $ref: '#/components/schemas/PatientTrackingContactExpansionDto'
        visitDetails:
          description: Only with `include=visitDetails`
          allOf:
            - $ref: '#/components/schemas/PatientTrackingVisitDetailsExpansionDto'
        insurance:
          description: Only with `include=insurance`
          allOf:
            - $ref: '#/components/schemas/PatientTrackingInsuranceExpansionDto'
        facility:
          $ref: '#/components/schemas/PatientTrackingFacilityRefDto'
        providers:
          $ref: '#/components/schemas/PatientTrackingProvidersRefDto'
        appointment:
          $ref: '#/components/schemas/PatientTrackingAppointmentDto'
        officeFlow:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/PatientTrackingOfficeFlowDto'
        effectiveStatus:
          $ref: '#/components/schemas/PatientTrackingSourcedValueDto'
        room:
          $ref: '#/components/schemas/PatientTrackingSourcedValueDto'
        checkInTime:
          type: string
          nullable: true
          example: '2026-10-16T12:55:00.000Z'
        arrivalTime:
          type: string
          nullable: true
          example: null
        timeInStatus:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/PatientTrackingTimeInStatusDto'
      required:
        - trackingKey
        - recordKind
        - nativeId
        - patientDisplay
        - facility
        - providers
        - appointment
        - officeFlow
        - effectiveStatus
        - room
        - checkInTime
        - arrivalTime
        - timeInStatus
    PatientTrackingCountsDto:
      type: object
      properties:
        returned:
          type: number
          example: 12
        seenAppointments:
          type: number
          nullable: true
          description: Null when the EHR cannot supply it
          example: 12
        scheduledAppointments:
          type: number
          nullable: true
          description: Null when the EHR cannot supply it
          example: 40
        scope:
          $ref: '#/components/schemas/PatientTrackingCountScopeDto'
      required:
        - returned
        - seenAppointments
        - scheduledAppointments
        - scope
    PatientTrackingFreshnessDto:
      type: object
      properties:
        readStartedAt:
          type: string
          example: '2026-10-16T14:00:00.000Z'
        readCompletedAt:
          type: string
          example: '2026-10-16T14:00:01.000Z'
        snapshotId:
          type: string
          example: 0123456789abcdef.7
        state:
          type: string
          enum:
            - fresh
            - stale
          example: fresh
        maxUsableAgeSeconds:
          type: number
          example: 60
      required:
        - readStartedAt
        - readCompletedAt
        - snapshotId
        - state
        - maxUsableAgeSeconds
    PatientTrackingCompletenessDto:
      type: object
      properties:
        primary:
          type: string
          enum:
            - complete
            - incomplete
            - unavailable
            - unsupported
          example: complete
        officeFlow:
          type: string
          enum:
            - complete
            - incomplete
            - unavailable
            - unsupported
          example: complete
        colors:
          type: string
          enum:
            - complete
            - incomplete
            - unavailable
            - unsupported
          example: complete
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/PatientTrackingWarningDto'
      required:
        - primary
        - officeFlow
        - colors
        - warnings
    PatientTrackingAccessDto:
      type: object
      properties:
        granted:
          type: array
          example:
            - patient
          items:
            type: string
            enum:
              - patient
              - contact
              - visitDetails
              - insurance
        requested:
          type: array
          example:
            - patient
          items:
            type: string
            enum:
              - patient
              - contact
              - visitDetails
              - insurance
      required:
        - granted
        - requested
    PatientTrackingPatientDisplayDto:
      type: object
      properties:
        initials:
          type: string
          nullable: true
          example: JD
        gender:
          type: string
          nullable: true
          example: F
      required:
        - initials
        - gender
    PatientTrackingPatientExpansionDto:
      type: object
      properties:
        nativePatientId:
          type: string
          nullable: true
          example: '50001'
        firstName:
          type: string
          nullable: true
          example: Jane
        lastName:
          type: string
          nullable: true
          example: Doe
        dateOfBirth:
          type: string
          nullable: true
          description: '`YYYY-MM-DD`'
          example: '1980-01-01'
        mrn:
          type: string
          nullable: true
          example: MRN-1
        sex:
          type: string
          nullable: true
          example: null
        gender:
          type: string
          nullable: true
          example: F
      required:
        - nativePatientId
        - firstName
        - lastName
        - dateOfBirth
        - mrn
        - sex
        - gender
    PatientTrackingContactExpansionDto:
      type: object
      properties:
        phone:
          type: string
          nullable: true
          example: '5555550100'
        email:
          type: string
          nullable: true
          example: jane@example.com
      required:
        - phone
        - email
    PatientTrackingVisitDetailsExpansionDto:
      type: object
      properties:
        chiefComplaint:
          type: string
          nullable: true
          example: Rash
        paymentMethod:
          type: string
          nullable: true
          example: null
      required:
        - chiefComplaint
        - paymentMethod
    PatientTrackingInsuranceExpansionDto:
      type: object
      properties:
        primaryInsuranceName:
          type: string
          nullable: true
          example: Example Health
        copayAmount:
          type: number
          nullable: true
          example: 25
      required:
        - primaryInsuranceName
        - copayAmount
    PatientTrackingFacilityRefDto:
      type: object
      properties:
        externalId:
          type: string
          example: '101'
        name:
          type: string
          nullable: true
          example: Main Street Clinic
      required:
        - externalId
        - name
    PatientTrackingProvidersRefDto:
      type: object
      properties:
        primary:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/PatientTrackingPrimaryProviderDto'
        attendees:
          type: array
          items:
            $ref: '#/components/schemas/PatientTrackingAttendeeDto'
      required:
        - primary
        - attendees
    PatientTrackingAppointmentDto:
      type: object
      properties:
        scheduledStart:
          type: string
          nullable: true
          description: ISO-8601 instant
          example: '2026-10-16T13:00:00.000Z'
        durationMinutes:
          type: number
          nullable: true
          example: 15
        type:
          type: string
          nullable: true
          example: Follow-up
        color:
          type: string
          nullable: true
          description: '`#rrggbb`'
          example: '#33aa55'
        nativeStatus:
          type: string
          nullable: true
          description: Status exactly as the EHR reports it
          example: ARRIVED
        normalizedStatus:
          type: string
          enum:
            - scheduled
            - confirmed
            - arrived
            - in_progress
            - completed
            - cancelled
            - no_show
            - rescheduled
            - other
            - unknown
          nullable: true
          example: arrived
      required:
        - scheduledStart
        - durationMinutes
        - type
        - color
        - nativeStatus
        - normalizedStatus
    PatientTrackingOfficeFlowDto:
      type: object
      properties:
        status:
          type: string
          example: WITH_STAFF
        label:
          type: string
          nullable: true
          example: With Staff
        color:
          type: string
          nullable: true
          example: '#ffaa00'
      required:
        - status
        - label
        - color
    PatientTrackingSourcedValueDto:
      type: object
      properties:
        value:
          type: string
          nullable: true
          example: WITH_STAFF
        source:
          type: string
          enum:
            - office_flow
            - appointment
            - encounter
          nullable: true
          example: office_flow
      required:
        - value
        - source
    PatientTrackingTimeInStatusDto:
      type: object
      properties:
        value:
          type: number
          example: 12
        unit:
          type: string
          enum:
            - unknown
          description: ModMed's unit is unverified; not seconds
          example: unknown
      required:
        - value
        - unit
    PatientTrackingCountScopeDto:
      type: object
      properties:
        returned:
          type: string
          enum:
            - filtered_rows
          example: filtered_rows
        seenAppointments:
          type: string
          enum:
            - selected_facilities_and_providers
          example: selected_facilities_and_providers
        scheduledAppointments:
          type: string
          enum:
            - selected_facilities
          example: selected_facilities
      required:
        - returned
        - seenAppointments
        - scheduledAppointments
    PatientTrackingWarningDto:
      type: object
      properties:
        code:
          type: string
          enum:
            - rows_without_facility_excluded
            - office_flow_conflicting_entries
            - office_flow_incomplete
            - office_flow_unavailable
            - office_flow_unsupported_for_date
            - colors_unavailable
          example: colors_unavailable
        component:
          type: string
          enum:
            - primary
            - officeFlow
            - colors
          example: colors
      required:
        - code
        - component
    PatientTrackingPrimaryProviderDto:
      type: object
      properties:
        externalId:
          type: string
          example: '2001'
        name:
          type: string
          nullable: true
          example: Dana Example
        source:
          type: string
          enum:
            - visit_physician
            - booked_provider
            - encounter_role
          example: visit_physician
      required:
        - externalId
        - name
        - source
    PatientTrackingAttendeeDto:
      type: object
      properties:
        externalId:
          type: string
          example: '2002'
        name:
          type: string
          nullable: true
          example: Pat Example
        role:
          type: string
          nullable: true
          description: Vendor role verbatim
          example: SECONDARY_PROVIDER
      required:
        - externalId
        - name
        - role
  securitySchemes:
    api-key:
      scheme: bearer
      bearerFormat: JWT
      type: http
      description: Marketplace API key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.