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

# List Patients



## OpenAPI

````yaml https://api.getsolum.com/openapi.json get /v1/patients
openapi: 3.1.0
info:
  title: Solum Health API
  description: '## Solum Health Backend API '
  version: 1.0.0
servers: []
security: []
paths:
  /v1/patients:
    get:
      tags:
        - Patients
      summary: List Patients
      operationId: list_patients_v1_patients_get
      parameters:
        - name: workflow_stage_ids[]
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  type: string
                  format: uuid
              - type: 'null'
            description: Filter by multiple workflow stage IDs (OR)
            title: Workflow Stage Ids[]
          description: Filter by multiple workflow stage IDs (OR)
        - name: include_unassigned
          in: query
          required: false
          schema:
            type: boolean
            description: >-
              Include patients with no workflow stage (combines with
              workflow_stage_ids via OR)
            default: false
            title: Include Unassigned
          description: >-
            Include patients with no workflow stage (combines with
            workflow_stage_ids via OR)
        - name: tags[]
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: Filter by tag IDs
            title: Tags[]
          description: Filter by tag IDs
        - name: insurance_ids[]
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: Filter by insurance IDs
            title: Insurance Ids[]
          description: Filter by insurance IDs
        - name: states[]
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  $ref: '#/components/schemas/States'
              - type: 'null'
            description: Filter by states
            title: States[]
          description: Filter by states
        - name: location_ids[]
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  type: string
                  format: uuid
              - type: 'null'
            description: Filter by company location IDs
            title: Location Ids[]
          description: Filter by company location IDs
        - name: organization_ids[]
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  type: string
                  format: uuid
              - type: 'null'
            description: Filter by company organization IDs
            title: Organization Ids[]
          description: Filter by company organization IDs
        - name: created_from[]
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  $ref: '#/components/schemas/PatientCreatedFrom'
              - type: 'null'
            description: Filter by created_from sources
            title: Created From[]
          description: Filter by created_from sources
        - name: eligibility_status[]
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  $ref: '#/components/schemas/EligibilityStatus'
              - type: 'null'
            description: Filter by eligibility check status
            title: Eligibility Status[]
          description: Filter by eligibility check status
        - name: eligibility_filter_mode
          in: query
          required: false
          schema:
            anyOf:
              - $ref: '#/components/schemas/EligibilityFilterMode'
              - type: 'null'
            description: Eligibility filter mode
            title: Eligibility Filter Mode
          description: Eligibility filter mode
        - name: sync_status[]
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  $ref: '#/components/schemas/SyncStatus'
              - type: 'null'
            description: Filter by sync status
            title: Sync Status[]
          description: Filter by sync status
        - name: plan_name
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Filter by plan name (partial match)
            title: Plan Name
          description: Filter by plan name (partial match)
        - name: plan_types[]
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  $ref: '#/components/schemas/InsurancePlanType'
              - type: 'null'
            description: Filter by plan types
            title: Plan Types[]
          description: Filter by plan types
        - name: group_description
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Filter by group description (partial match)
            title: Group Description
          description: Filter by group description (partial match)
        - name: group_number
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Filter by group number (partial match)
            title: Group Number
          description: Filter by group number (partial match)
        - name: expand[]
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  $ref: '#/components/schemas/PatientExpand'
              - type: 'null'
            description: Fields to expand in the response
            title: Expand[]
          description: Fields to expand in the response
        - name: page
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
                minimum: 1
              - type: 'null'
            default: 1
            title: Page
        - name: limit
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
                maximum: 100
                minimum: 1
              - type: 'null'
            default: 50
            title: Limit
        - name: q
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Q
        - name: id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: uuid
              - type: 'null'
            title: Id
        - name: workflow_stage_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Workflow Stage Id
        - name: assigned_to
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Assigned To
        - name: status
          in: query
          required: false
          schema:
            anyOf:
              - $ref: '#/components/schemas/PatientStatusFilter'
              - type: 'null'
            default: active
            title: Status
        - name: phone_number
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Phone Number
        - name: email
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Email
        - name: external_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: External Id
        - name: first_name
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: First Name
        - name: last_name
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Last Name
        - name: date_of_birth
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Date Of Birth
        - name: tag_filter_mode
          in: query
          required: false
          schema:
            anyOf:
              - $ref: '#/components/schemas/TagFilterMode'
              - type: 'null'
            default: any
            title: Tag Filter Mode
        - name: created_gte
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: 'null'
            title: Created Gte
        - name: created_lte
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: 'null'
            title: Created Lte
        - name: updated_gte
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: 'null'
            title: Updated Gte
        - name: updated_lte
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: 'null'
            title: Updated Lte
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatientList'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    example: validation_error
                  code:
                    type: string
                    example: invalid_parameter
                  message:
                    type: string
                    example: Field validation failed
                  param:
                    type: string
                    example: phone_number
                required:
                  - type
                  - code
                  - message
      security:
        - APIKeyHeader: []
        - HTTPBearer: []
components:
  schemas:
    States:
      type: string
      enum:
        - alabama
        - alaska
        - arizona
        - arkansas
        - california
        - colorado
        - connecticut
        - delaware
        - florida
        - georgia
        - hawaii
        - idaho
        - illinois
        - indiana
        - iowa
        - kansas
        - kentucky
        - louisiana
        - maine
        - maryland
        - massachusetts
        - michigan
        - minnesota
        - mississippi
        - missouri
        - montana
        - nebraska
        - nevada
        - new_hampshire
        - new_jersey
        - new_mexico
        - new_york
        - north_carolina
        - north_dakota
        - ohio
        - oklahoma
        - oregon
        - pennsylvania
        - rhode_island
        - south_carolina
        - south_dakota
        - tennessee
        - texas
        - utah
        - vermont
        - virginia
        - washington
        - west_virginia
        - wisconsin
        - wyoming
        - district_of_columbia
        - puerto_rico
        - virgin_islands
        - guam
        - northern_mariana_islands
        - american_samoa
      title: States
      description: US States enum matching Prisma @map values
    PatientCreatedFrom:
      type: string
      enum:
        - form
        - call
        - api
        - file
        - sms
        - fax
        - chat_agent
        - manual
        - bulk_import
        - eligibility
        - prior_auth
      title: PatientCreatedFrom
      description: Patient creation source enum matching Prisma
    EligibilityStatus:
      type: string
      enum:
        - active
        - inactive
        - pending
        - failed
      title: EligibilityStatus
      description: >-
        Eligibility check status enum matching Prisma EligibilityStatus.


        Note: this Python enum has `FAILED` but the Postgres
        `eligibility_check_status`

        type does not — pre-existing drift between Prisma and the DB. Don't use

        `pg_enum(EligibilityStatus)` for the DB column; declare the column with
        the

        DB's actual values via a literal `ENUM(...)`.
    EligibilityFilterMode:
      type: string
      enum:
        - any
        - primary
        - secondary
        - tertiary
        - quaternary
      title: EligibilityFilterMode
      description: Eligibility filter mode — which payor tier to check, or any
    SyncStatus:
      type: string
      enum:
        - pending
        - completed
      title: SyncStatus
      description: Sync status filter for patient list queries
    InsurancePlanType:
      type: string
      enum:
        - '01'
        - '02'
        - '03'
        - '12'
        - '13'
        - '14'
        - '15'
        - '16'
        - '17'
        - '18'
        - '19'
        - '41'
        - '42'
        - '43'
        - '47'
        - '48'
        - '49'
        - AP
        - C1
        - CO
        - CP
        - D
        - DB
        - EP
        - FF
        - GP
        - HB
        - HD
        - HG
        - HM
        - HN
        - HP
        - HS
        - IN
        - IP
        - LC
        - LD
        - LI
        - LT
        - M
        - MA
        - MB
        - MC
        - MD
        - ME
        - MH
        - MI
        - MJ
        - MK
        - ML
        - MM
        - MN
        - MO
        - MP
        - MR
        - MT
        - OA
        - OT
        - PE
        - PL
        - PP
        - PR
        - PS
        - QM
        - RP
        - SA
        - SP
        - TF
        - WC
        - WU
      title: InsurancePlanType
      description: Insurance plan type enum matching Prisma - X12 standard codes
    PatientExpand:
      type: string
      enum:
        - tags
        - workflow_stage
        - assigned_user
        - referrals
        - payors
        - external_id_values
      title: PatientExpand
      description: Allowed expand values for patient endpoints
    PatientStatusFilter:
      type: string
      enum:
        - active
        - inactive
        - all
      title: PatientStatusFilter
      description: Filter options for patient status (active/inactive/all)
    TagFilterMode:
      type: string
      enum:
        - any
        - all
        - exclude_any
        - exclude_all
      title: TagFilterMode
      description: Tag filter mode for patient queries
    PatientList:
      properties:
        data:
          items:
            $ref: '#/components/schemas/Patient'
          type: array
          title: Data
        pagination:
          $ref: '#/components/schemas/Pagination'
      additionalProperties: false
      type: object
      required:
        - data
        - pagination
      title: PatientList
      description: List response for patients
      example:
        data:
          - active: true
            created_at: '2024-01-15T10:30:00Z'
            date_of_birth: '1990-01-15'
            email: john.doe@example.com
            first_name: John
            id: 550e8400-e29b-41d4-a716-446655440009
            last_name: Doe
            phone_number: '+1234567890'
            updated_at: '2024-01-15T10:30:00Z'
        pagination:
          has_more: false
          limit: 50
          page: 1
          total: 1
    Patient:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        first_name:
          anyOf:
            - type: string
            - type: 'null'
          title: First Name
        last_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Last Name
        middle_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Middle Name
        phone_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Phone Number
        additional_phone_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Additional Phone Number
        email:
          anyOf:
            - type: string
            - type: 'null'
          title: Email
        date_of_birth:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Date Of Birth
        gender:
          anyOf:
            - $ref: '#/components/schemas/Gender'
            - type: 'null'
        address:
          anyOf:
            - type: string
            - type: 'null'
          title: Address
        address2:
          anyOf:
            - type: string
            - type: 'null'
          title: Address2
        city:
          anyOf:
            - type: string
            - type: 'null'
          title: City
        state:
          anyOf:
            - $ref: '#/components/schemas/States'
            - type: 'null'
        zip:
          anyOf:
            - type: string
            - type: 'null'
          title: Zip
        workflow_stage_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Workflow Stage Id
        assigned_user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Assigned User Id
        location_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Location Id
        organization_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Organization Id
        created_from:
          anyOf:
            - $ref: '#/components/schemas/PatientCreatedFrom'
            - type: 'null'
        active:
          type: boolean
          title: Active
          default: true
        version:
          type: integer
          title: Version
          default: 1
        first_communication_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: First Communication At
        has_sync_completed:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Has Sync Completed
          description: >-
            Whether a completed external-sync event exists. Populated on
            patient-list items whose expanded current workflow stage runs
            external sync; null on other patient responses.
        custom_fields:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Custom Fields
        comments:
          anyOf:
            - type: string
            - type: 'null'
          title: Comments
        tags:
          anyOf:
            - items:
                $ref: '#/components/schemas/Tag'
              type: array
            - type: 'null'
          title: Tags
        workflow_stage:
          anyOf:
            - $ref: '#/components/schemas/WorkflowStageSummary'
            - type: 'null'
        assigned_user:
          anyOf:
            - $ref: '#/components/schemas/UserSummary'
            - type: 'null'
        referrals:
          anyOf:
            - items:
                $ref: '#/components/schemas/ReferralResponse'
              type: array
            - type: 'null'
          title: Referrals
        payors:
          anyOf:
            - items:
                $ref: '#/components/schemas/Payor'
              type: array
            - type: 'null'
          title: Payors
        external_id_values:
          anyOf:
            - items:
                $ref: '#/components/schemas/ExternalIdValueResponse'
              type: array
            - type: 'null'
          title: External Id Values
      type: object
      required:
        - id
        - created_at
        - updated_at
      title: Patient
      description: Patient resource response model.
    Pagination:
      properties:
        has_more:
          type: boolean
          title: Has More
        total:
          type: integer
          title: Total
        page:
          type: integer
          title: Page
        limit:
          type: integer
          title: Limit
      additionalProperties: false
      type: object
      required:
        - has_more
        - total
        - page
        - limit
      title: Pagination
      description: |-
        Pagination information for list responses.

        Fields:
        - has_more: Whether more items exist beyond this page
        - total: Total number of items across all pages
        - page: Current page number (1-based)
        - limit: Number of items per page
    Gender:
      type: string
      enum:
        - male
        - female
        - other
      title: Gender
      description: Gender enum matching Prisma
    Tag:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
      type: object
      required:
        - id
        - name
      title: Tag
    WorkflowStageSummary:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
        actions:
          anyOf:
            - items:
                $ref: '#/components/schemas/WorkflowStageAction'
              type: array
            - type: 'null'
          title: Actions
        order:
          anyOf:
            - type: integer
            - type: 'null'
          title: Order
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
      type: object
      required:
        - id
      title: WorkflowStageSummary
      description: Lightweight workflow stage for patient expansion responses.
    UserSummary:
      properties:
        id:
          type: string
          title: Id
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        email:
          anyOf:
            - type: string
            - type: 'null'
          title: Email
      type: object
      required:
        - id
      title: UserSummary
    ReferralResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        physician_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Physician Name
          description: Referring physician's name
        physician_email:
          anyOf:
            - type: string
            - type: 'null'
          title: Physician Email
          description: Referring physician's email
        physician_phone:
          anyOf:
            - type: string
            - type: 'null'
          title: Physician Phone
          description: Referring physician's phone
        physician_fax:
          anyOf:
            - type: string
            - type: 'null'
          title: Physician Fax
          description: Referring physician's fax
        physician_group:
          anyOf:
            - type: string
            - type: 'null'
          title: Physician Group
          description: Referring physician's group/practice
        physician_npi:
          anyOf:
            - type: string
            - type: 'null'
          title: Physician Npi
          description: Referring physician's National Provider Identifier
        physician_address:
          anyOf:
            - type: string
            - type: 'null'
          title: Physician Address
          description: Referring physician's street address
        physician_address_2:
          anyOf:
            - type: string
            - type: 'null'
          title: Physician Address 2
          description: Referring physician's address line 2
        physician_city:
          anyOf:
            - type: string
            - type: 'null'
          title: Physician City
          description: Referring physician's city
        physician_state:
          anyOf:
            - $ref: '#/components/schemas/States'
            - type: 'null'
          description: Referring physician's state
        physician_zip:
          anyOf:
            - type: string
            - type: 'null'
          title: Physician Zip
          description: Referring physician's ZIP code
        start_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Start Date
          description: Referral start date (YYYY-MM-DD)
        end_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: End Date
          description: Referral end date (YYYY-MM-DD)
        location_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Location Id
          description: Company location ID
        icd_codes:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Icd Codes
        service_types:
          anyOf:
            - items:
                $ref: '#/components/schemas/ServiceType'
              type: array
            - type: 'null'
          title: Service Types
        created_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Created At
        updated_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Updated At
      type: object
      required:
        - id
      title: ReferralResponse
    Payor:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        patient_id:
          type: string
          title: Patient Id
        insurance_id:
          type: string
          title: Insurance Id
        coverage_chain_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Coverage Chain Id
          description: >-
            Coverage chain this row belongs to. Rows sharing it are one coverage
            (the tier-bearing row is current; the others are its previous
            versions). A patient may hold two chains on the same insurance (two
            distinct policies).
        insurance_display_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Insurance Display Name
        subscriber_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Subscriber Id
        external_id:
          anyOf:
            - type: string
            - type: 'null'
          title: External Id
          description: Identifier for this coverage in an external system.
        relationship_to_subscriber:
          anyOf:
            - $ref: '#/components/schemas/RelationshipToSubscriber'
            - type: 'null'
        insured_member_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Insured Member Id
        group_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Group Number
        group_description:
          anyOf:
            - type: string
            - type: 'null'
          title: Group Description
        medicaid_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Medicaid Id
        payor_responsibility:
          anyOf:
            - $ref: '#/components/schemas/InsuranceTier'
            - type: 'null'
        coverage_from:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Coverage From
        coverage_to:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Coverage To
        provider_network_status:
          anyOf:
            - $ref: '#/components/schemas/ProviderNetworkStatus'
            - type: 'null'
        cbh_status:
          anyOf:
            - $ref: '#/components/schemas/CbhStatus'
            - type: 'null'
        plan_funding_type:
          anyOf:
            - $ref: '#/components/schemas/PlanFundingType'
            - type: 'null'
        plan_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Plan Name
        plan_type:
          anyOf:
            - $ref: '#/components/schemas/InsurancePlanType'
            - type: 'null'
        plan_renewal_date_type:
          anyOf:
            - $ref: '#/components/schemas/PlanRenewalDateType'
            - type: 'null'
        benefit_period_end_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Benefit Period End Date
        cob_on_file:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Cob On File
        cob_last_verified_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Cob Last Verified At
        has_other_active_coverage:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Has Other Active Coverage
        cob_other_coverages:
          anyOf:
            - items:
                $ref: '#/components/schemas/OtherCoverage'
              type: array
            - type: 'null'
          title: Cob Other Coverages
        out_of_state_benefits:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Out Of State Benefits
        out_of_state_benefits_comments:
          anyOf:
            - type: string
            - type: 'null'
          title: Out Of State Benefits Comments
        in_grace_period:
          anyOf:
            - type: boolean
            - type: 'null'
          title: In Grace Period
        last_payment_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Last Payment Date
        is_cobra_coverage:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Cobra Coverage
        deductible_apply_to_oop:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Deductible Apply To Oop
        eligibility_check_status:
          $ref: '#/components/schemas/EligibilityStatus'
          default: pending
        eligibility_check_comment:
          anyOf:
            - type: string
            - type: 'null'
          title: Eligibility Check Comment
        eligibility_check_date:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Eligibility Check Date
        eligibility_version:
          type: integer
          title: Eligibility Version
          default: 0
        individual_deductible_policy_in_network:
          anyOf:
            - type: number
            - type: 'null'
          title: Individual Deductible Policy In Network
        individual_deductible_policy_out_network:
          anyOf:
            - type: number
            - type: 'null'
          title: Individual Deductible Policy Out Network
        individual_deductible_remaining_in_network:
          anyOf:
            - type: number
            - type: 'null'
          title: Individual Deductible Remaining In Network
        individual_deductible_remaining_out_network:
          anyOf:
            - type: number
            - type: 'null'
          title: Individual Deductible Remaining Out Network
        family_deductible_policy_in_network:
          anyOf:
            - type: number
            - type: 'null'
          title: Family Deductible Policy In Network
        family_deductible_policy_out_network:
          anyOf:
            - type: number
            - type: 'null'
          title: Family Deductible Policy Out Network
        family_deductible_remaining_in_network:
          anyOf:
            - type: number
            - type: 'null'
          title: Family Deductible Remaining In Network
        family_deductible_remaining_out_network:
          anyOf:
            - type: number
            - type: 'null'
          title: Family Deductible Remaining Out Network
        individual_oop_max_policy_in_network:
          anyOf:
            - type: number
            - type: 'null'
          title: Individual Oop Max Policy In Network
        individual_oop_max_policy_out_network:
          anyOf:
            - type: number
            - type: 'null'
          title: Individual Oop Max Policy Out Network
        individual_oop_max_remaining_in_network:
          anyOf:
            - type: number
            - type: 'null'
          title: Individual Oop Max Remaining In Network
        individual_oop_max_remaining_out_network:
          anyOf:
            - type: number
            - type: 'null'
          title: Individual Oop Max Remaining Out Network
        family_oop_max_policy_in_network:
          anyOf:
            - type: number
            - type: 'null'
          title: Family Oop Max Policy In Network
        family_oop_max_policy_out_network:
          anyOf:
            - type: number
            - type: 'null'
          title: Family Oop Max Policy Out Network
        family_oop_max_remaining_in_network:
          anyOf:
            - type: number
            - type: 'null'
          title: Family Oop Max Remaining In Network
        family_oop_max_remaining_out_network:
          anyOf:
            - type: number
            - type: 'null'
          title: Family Oop Max Remaining Out Network
        benefits_related_entities:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Benefits Related Entities
        ai_summary:
          anyOf:
            - type: string
            - type: 'null'
          title: Ai Summary
        ai_summary_generated_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Ai Summary Generated At
        patient:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Patient
        insurance:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Insurance
        subscriber:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Subscriber
        services:
          anyOf:
            - items:
                $ref: '#/components/schemas/PayorService'
              type: array
            - type: 'null'
          title: Services
        active:
          type: boolean
          title: Active
          default: true
        version:
          type: integer
          title: Version
          default: 1
      type: object
      required:
        - id
        - created_at
        - updated_at
        - patient_id
        - insurance_id
      title: Payor
      description: >-
        Payor resource.


        Represents the relationship between a patient and their insurance
        coverage.

        Includes related insurance, subscriber, and service information.
    ExternalIdValueResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        patient_id:
          type: string
          format: uuid
          title: Patient Id
        value:
          type: string
          title: Value
        external_id_type:
          $ref: '#/components/schemas/ExternalIdTypeSummary'
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      additionalProperties: false
      type: object
      required:
        - id
        - patient_id
        - value
        - external_id_type
        - created_at
        - updated_at
      title: ExternalIdValueResponse
      description: >-
        Response shape for the patient external-ids endpoints AND for the
        embedded

        `external_id_values` field on PatientResponse.
    WorkflowStageAction:
      type: string
      enum:
        - verify_insurance
        - sync_external
        - complete_verification
      title: WorkflowStageAction
      description: Actions that can be triggered when a patient enters a stage.
    ServiceType:
      type: string
      enum:
        - medical_care
        - surgical
        - consultation
        - diagnostic_x_ray
        - diagnostic_lab
        - radiation_therapy
        - anesthesia
        - surgical_assistance
        - other_medical
        - blood_charges
        - used_durable_medical_equipment
        - durable_medical_equipment_purchase
        - ambulatory_service_center_facility
        - renal_supplies_in_home
        - alternate_method_dialysis
        - chronic_renal_disease_equipment
        - pre_admission_testing
        - durable_medical_equipment_rental
        - pneumonia_vaccine
        - second_surgical_opinion
        - third_surgical_opinion
        - social_work
        - diagnostic_dental
        - periodontics
        - restorative
        - endodontics
        - maxillofacial_prosthetics
        - adjunctive_dental_services
        - health_benefit_plan_coverage
        - plan_waiting_period
        - chiropractic
        - chiropractic_office_visits
        - dental_care
        - dental_crowns
        - dental_accident
        - orthodontics
        - prosthodontics
        - oral_surgery
        - routine_preventive_dental
        - home_health_care
        - home_health_prescriptions
        - home_health_visits
        - hospice
        - respite_care
        - hospital
        - hospital_inpatient
        - hospital_room_and_board
        - hospital_outpatient
        - hospital_emergency_accident
        - hospital_emergency_medical
        - hospital_ambulatory_surgical
        - long_term_care
        - major_medical
        - medically_related_transportation
        - air_transportation
        - cabulance
        - licensed_ambulance
        - general_benefits
        - in_vitro_fertilization
        - mri_cat_scan
        - donor_procedures
        - acupuncture
        - newborn_care
        - pathology
        - smoking_cessation
        - well_baby_care
        - maternity
        - transplants
        - audiology_exam
        - inhalation_therapy
        - diagnostic_medical
        - private_duty_nursing
        - prosthetic_device
        - dialysis
        - otological_exam
        - chemotherapy
        - allergy_testing
        - immunizations
        - routine_physical
        - family_planning
        - infertility
        - abortion
        - aids
        - emergency_services
        - cancer
        - pharmacy
        - free_standing_prescription_drug
        - mail_order_prescription_drug
        - brand_name_prescription_drug
        - generic_prescription_drug
        - podiatry
        - podiatry_office_visits
        - podiatry_nursing_home_visits
        - professional_physician
        - anesthesiologist
        - professional_visit_office
        - professional_visit_inpatient
        - professional_visit_outpatient
        - professional_visit_nursing_home
        - professional_visit_skilled_nursing_facility
        - professional_visit_home
        - psychiatric
        - psychiatric_room_and_board
        - psychotherapy
        - psychiatric_inpatient
        - psychiatric_outpatient
        - rehabilitation
        - rehabilitation_room_and_board
        - rehabilitation_inpatient
        - rehabilitation_outpatient
        - occupational_therapy
        - physical_medicine
        - speech_therapy
        - skilled_nursing_care
        - skilled_nursing_care_room_and_board
        - substance_abuse
        - alcoholism
        - drug_addiction
        - vision_optometry
        - frames
        - routine_exam
        - lenses
        - nonmedically_necessary_physical
        - experimental_drug_therapy
        - burn_care
        - brand_name_prescription_drug_formulary
        - brand_name_prescription_drug_non_formulary
        - independent_medical_evaluation
        - partial_hospitalization_psychiatric
        - day_care_psychiatric
        - cognitive_therapy
        - massage_therapy
        - pulmonary_rehabilitation
        - cardiac_rehabilitation
        - pediatric
        - nursery
        - skin
        - orthopedic
        - cardiac
        - lymphatic
        - gastrointestinal
        - endocrine
        - neurology
        - eye
        - invasive_procedures
        - gynecological
        - obstetrical
        - obstetrical_gynecological
        - mail_order_prescription_drug_brand_name
        - mail_order_prescription_drug_generic
        - physician_visit_office_sick
        - physician_visit_office_well
        - coronary_care
        - private_duty_nursing_inpatient
        - private_duty_nursing_home
        - surgical_benefits_professional
        - surgical_benefits_facility
        - mental_health_provider_inpatient
        - mental_health_provider_outpatient
        - mental_health_facility_inpatient
        - mental_health_facility_outpatient
        - substance_abuse_facility_inpatient
        - substance_abuse_facility_outpatient
        - screening_x_ray
        - screening_laboratory
        - mammogram_high_risk_patient
        - mammogram_low_risk_patient
        - flu_vaccination
        - eyewear_and_accessories
        - case_management
        - dermatology
        - durable_medical_equipment
        - diabetic_supplies
        - generic_prescription_drug_formulary
        - generic_prescription_drug_non_formulary
        - allergy
        - intensive_care
        - mental_health
        - neonatal_intensive_care
        - oncology
        - physical_therapy
        - pulmonary
        - renal
        - residential_psychiatric_treatment
        - transitional_care
        - transitional_nursery_care
        - urgent_care
      title: ServiceType
      description: |-
        X12 Service Type — human-readable enum values stored in the database.
        See app/utils/service_type_mapping.py for code-to-type mappings.
    RelationshipToSubscriber:
      type: string
      enum:
        - spouse
        - self
        - child
        - employee
        - unknown
        - organ_donor
        - cadaver_donor
        - life_partner
        - other_relationship
      title: RelationshipToSubscriber
      description: Relationship to subscriber enum matching Prisma @map values
    InsuranceTier:
      type: string
      enum:
        - primary
        - secondary
        - tertiary
        - quaternary
      title: InsuranceTier
      description: Insurance tier enum matching Prisma
    ProviderNetworkStatus:
      type: string
      enum:
        - unknown
        - in_network
        - out_of_network
      title: ProviderNetworkStatus
      description: Provider network status enum matching Prisma @map values
    CbhStatus:
      type: string
      enum:
        - active
        - inactive
      title: CbhStatus
      description: >-
        CBH (Community Behavioral Health) coverage status matching Prisma @map
        values.


        Captured per-payor; the checklist counterpart is

        VerificationRequirement.ASK_FOR_CBH.
    PlanFundingType:
      type: string
      enum:
        - fully_funded
        - self_funded
        - unknown
      title: PlanFundingType
      description: Plan funding type enum matching Prisma @map values
    PlanRenewalDateType:
      type: string
      enum:
        - calendar_year
        - service_year
        - contract
      title: PlanRenewalDateType
      description: Plan renewal date type enum matching Prisma @map values
    OtherCoverage:
      properties:
        name:
          type: string
          minLength: 1
          title: Name
          description: Carrier name as the payer states it
        position:
          anyOf:
            - $ref: '#/components/schemas/InsuranceTier'
            - type: 'null'
          description: >-
            Where this coverage sits in the member's coordination order. Left
            empty when the payer names a carrier without stating its position.
      additionalProperties: false
      type: object
      required:
        - name
      title: OtherCoverage
      description: >-
        One other insurance the payer holds on file for a member.


        Stored as JSON on `payors.cob_other_coverages`. `name` is free text on

        purpose — the carriers a payer names are frequently ones we do not
        contract

        with, so a catalog reference would block recording them.
    PayorService:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        payor_id:
          type: string
          title: Payor Id
        service_type:
          $ref: '#/components/schemas/ServiceType'
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        verification_benefits_status:
          $ref: '#/components/schemas/VerificationBenefitsStatus'
          default: pending
        verification_dates:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Verification Dates
        verification_user_ids:
          anyOf:
            - items:
                anyOf:
                  - type: string
                  - type: 'null'
              type: array
            - type: 'null'
          title: Verification User Ids
        verification_benefits_comment:
          anyOf:
            - type: string
            - type: 'null'
          title: Verification Benefits Comment
        pre_cert_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Pre Cert Name
        pre_cert_phone_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Pre Cert Phone Number
        pre_cert_fax:
          anyOf:
            - type: string
            - type: 'null'
          title: Pre Cert Fax
        pre_cert_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Pre Cert Url
        pre_cert_penalty:
          anyOf:
            - type: string
            - type: 'null'
          title: Pre Cert Penalty
        pre_cert_email:
          anyOf:
            - type: string
            - type: 'null'
          title: Pre Cert Email
        sca_instructions:
          anyOf:
            - type: string
            - type: 'null'
          title: Sca Instructions
        claim_address:
          anyOf:
            - type: string
            - type: 'null'
          title: Claim Address
        oon_reimbursement_rate:
          anyOf:
            - type: number
            - type: 'null'
          title: Oon Reimbursement Rate
        oon_reimbursement_rate_type:
          anyOf:
            - $ref: '#/components/schemas/OonReimbursementRateType'
            - type: 'null'
        eligibility_check_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Eligibility Check Id
        carve_out_insurer_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Carve Out Insurer Id
        location_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Location Id
        rep_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Rep Name
        call_reference_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Call Reference Number
        called_phone_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Called Phone Number
        covered_cpt_codes:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Covered Cpt Codes
        not_covered_cpt_codes:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Not Covered Cpt Codes
        covered_icd_codes:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Covered Icd Codes
        not_covered_icd_codes:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Not Covered Icd Codes
        version:
          type: integer
          title: Version
          default: 1
        location_rates:
          anyOf:
            - items:
                $ref: '#/components/schemas/PayorServiceLocation'
              type: array
            - type: 'null'
          title: Location Rates
        payor:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Payor
      type: object
      required:
        - id
        - payor_id
        - service_type
        - created_at
        - updated_at
      title: PayorService
      description: >-
        Payor service resource.


        Represents insurance verification and benefit details for a specific
        service.
      example:
        copay_in_network: 25
        created_at: '2024-01-15T10:30:00Z'
        eligibility_check_status: ELIGIBLE
        id: 550e8400-e29b-41d4-a716-446655440014
        payor_id: 550e8400-e29b-41d4-a716-446655440012
        service_type: PT
        updated_at: '2024-01-15T10:30:00Z'
        verification_benefits_status: VERIFIED
    ExternalIdTypeSummary:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        name:
          type: string
          title: Name
        created_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Created At
      additionalProperties: false
      type: object
      required:
        - id
        - name
      title: ExternalIdTypeSummary
      description: >-
        Read-only summary of an external_id_types row.


        Used embedded in `ExternalIdValueResponse` (where `created_at` stays
        None)

        and as the body of `GET /v1/external-id-types` (where it's populated).
    VerificationBenefitsStatus:
      type: string
      enum:
        - completed
        - pending
        - in_progress
      title: VerificationBenefitsStatus
      description: Verification benefits status enum matching Prisma @map values
    OonReimbursementRateType:
      type: string
      enum:
        - ucr
        - medicare
        - mnrp
        - maa
        - billed_charges
        - fee_schedule
        - mrc1
        - mrc2
        - local_allowable_rates
        - not_confirmed
      title: OonReimbursementRateType
      description: OON Reimbursement rate type enum matching Prisma @map values
    PayorServiceLocation:
      properties:
        service_location:
          $ref: '#/components/schemas/ServiceLocation'
          description: Service location
        covered_in_network:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Covered In Network
          description: Whether service is covered in network
        covered_out_network:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Covered Out Network
          description: Whether service is covered out of network
        copay_in_network:
          anyOf:
            - type: number
            - type: 'null'
          title: Copay In Network
          description: Copay in network
        copay_out_network:
          anyOf:
            - type: number
            - type: 'null'
          title: Copay Out Network
          description: Copay out of network
        co_insurance_in_network:
          anyOf:
            - type: number
            - type: 'null'
          title: Co Insurance In Network
          description: Co-insurance in network (percentage)
        co_insurance_out_network:
          anyOf:
            - type: number
            - type: 'null'
          title: Co Insurance Out Network
          description: Co-insurance out of network (percentage)
        auth_required_in_network:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Auth Required In Network
          description: Whether authorization is required in network
        auth_required_out_network:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Auth Required Out Network
          description: Whether authorization is required out of network
        auth_required_at_visit_in_network:
          anyOf:
            - type: integer
            - type: 'null'
          title: Auth Required At Visit In Network
          description: Visit number from which authorization is required in network
        auth_required_at_visit_out_network:
          anyOf:
            - type: integer
            - type: 'null'
          title: Auth Required At Visit Out Network
          description: Visit number from which authorization is required out of network
        mnr_required_in_network:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Mnr Required In Network
          description: Whether a medical necessity review is required in network
        mnr_required_out_network:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Mnr Required Out Network
          description: Whether a medical necessity review is required out of network
        mnr_required_at_visit_in_network:
          anyOf:
            - type: integer
            - type: 'null'
          title: Mnr Required At Visit In Network
          description: >-
            Visit number from which a medical necessity review is required in
            network
        mnr_required_at_visit_out_network:
          anyOf:
            - type: integer
            - type: 'null'
          title: Mnr Required At Visit Out Network
          description: >-
            Visit number from which a medical necessity review is required out
            of network
        deductible_apply_in_network:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Deductible Apply In Network
          description: Whether deductible applies in network
        deductible_apply_out_network:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Deductible Apply Out Network
          description: Whether deductible applies out of network
        oop_apply_in_network:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Oop Apply In Network
          description: Whether OOP applies in network
        oop_apply_out_network:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Oop Apply Out Network
          description: Whether OOP applies out of network
        copay_applies_to_oop_max_in_network:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Copay Applies To Oop Max In Network
          description: Whether the copay counts toward the out-of-pocket maximum in network
        copay_applies_to_oop_max_out_network:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Copay Applies To Oop Max Out Network
          description: >-
            Whether the copay counts toward the out-of-pocket maximum out of
            network
        dollar_limit_in_network:
          anyOf:
            - type: number
            - type: 'null'
          title: Dollar Limit In Network
          description: Dollar limit in network
        dollar_limit_out_network:
          anyOf:
            - type: number
            - type: 'null'
          title: Dollar Limit Out Network
          description: Dollar limit out of network
        dollar_limit_remaining_in_network:
          anyOf:
            - type: number
            - type: 'null'
          title: Dollar Limit Remaining In Network
          description: Dollar limit remaining in network
        dollar_limit_remaining_out_network:
          anyOf:
            - type: number
            - type: 'null'
          title: Dollar Limit Remaining Out Network
          description: Dollar limit remaining out of network
        dollar_limit_time_period_in_network:
          anyOf:
            - $ref: '#/components/schemas/PeriodicMaximumTimePeriod'
            - type: 'null'
          description: Dollar limit time period in network
        dollar_limit_time_period_out_network:
          anyOf:
            - $ref: '#/components/schemas/PeriodicMaximumTimePeriod'
            - type: 'null'
          description: Dollar limit time period out of network
        dollar_limit_type_in_network:
          anyOf:
            - $ref: '#/components/schemas/LimitType'
            - type: 'null'
          description: Dollar limit type in network (soft or hard)
        dollar_limit_type_out_network:
          anyOf:
            - $ref: '#/components/schemas/LimitType'
            - type: 'null'
          description: Dollar limit type out of network (soft or hard)
        visit_limit_in_network:
          anyOf:
            - type: number
            - type: 'null'
          title: Visit Limit In Network
          description: Visit limit in network
        visit_limit_out_network:
          anyOf:
            - type: number
            - type: 'null'
          title: Visit Limit Out Network
          description: Visit limit out of network
        visit_limit_remaining_in_network:
          anyOf:
            - type: number
            - type: 'null'
          title: Visit Limit Remaining In Network
          description: Visit limit remaining in network
        visit_limit_remaining_out_network:
          anyOf:
            - type: number
            - type: 'null'
          title: Visit Limit Remaining Out Network
          description: Visit limit remaining out of network
        visit_limit_time_period_in_network:
          anyOf:
            - $ref: '#/components/schemas/PeriodicMaximumTimePeriod'
            - type: 'null'
          description: Visit limit time period in network
        visit_limit_time_period_out_network:
          anyOf:
            - $ref: '#/components/schemas/PeriodicMaximumTimePeriod'
            - type: 'null'
          description: Visit limit time period out of network
        visit_limit_type_in_network:
          anyOf:
            - $ref: '#/components/schemas/LimitType'
            - type: 'null'
          description: Visit limit type in network (soft or hard)
        visit_limit_type_out_network:
          anyOf:
            - $ref: '#/components/schemas/LimitType'
            - type: 'null'
          description: Visit limit type out of network (soft or hard)
        id:
          type: string
          title: Id
        payor_service_id:
          type: string
          title: Payor Service Id
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        version:
          type: integer
          title: Version
          default: 1
      type: object
      required:
        - service_location
        - id
        - payor_service_id
        - created_at
        - updated_at
      title: PayorServiceLocation
      description: Response model for location-specific rates
    ServiceLocation:
      type: string
      enum:
        - home
        - office
        - school
        - daycare
        - community
        - telehealth
      title: ServiceLocation
      description: Service location enum matching Prisma @@map("service_location").
    PeriodicMaximumTimePeriod:
      type: string
      enum:
        - daily
        - monthly
        - annually
      title: PeriodicMaximumTimePeriod
      description: Periodic maximum time period enum matching Prisma
    LimitType:
      type: string
      enum:
        - soft
        - hard
      title: LimitType
      description: Limit type enum matching Prisma @map values
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
    HTTPBearer:
      type: http
      scheme: bearer

````