> ## 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 insurance policies

> Returns a paginated list of patient insurance policies with payer, ranking, termination, and eligibility data. Requires read:insurance_policies scope.



## OpenAPI

````yaml /openapi-v3.json get /insurance-policies
openapi: 3.0.0
info:
  title: Max AI Public API
  description: API for third-party marketplace apps
  version: '3.0'
  contact: {}
servers:
  - url: https://api.maxcare.ai/v3
security: []
tags: []
paths:
  /insurance-policies:
    get:
      tags:
        - Insurance Policies
      summary: List insurance policies
      description: >-
        Returns a paginated list of patient insurance policies with payer,
        ranking, termination, and eligibility data. Requires
        read:insurance_policies scope.
      operationId: InsurancePoliciesPublicController_listInsurancePolicies
      parameters:
        - name: page
          required: false
          in: query
          description: Page number (1-indexed)
          schema:
            default: 1
            example: 1
        - name: pageSize
          required: false
          in: query
          description: Number of items per page (max 500)
          schema:
            default: 100
            example: 100
        - name: patientId
          required: false
          in: query
          description: Filter by patient ID (UUID)
          schema:
            example: pat_8de030393a9e417ab2b3a8b8df183631
            type: string
        - name: includeTerminated
          required: false
          in: query
          description: Include terminated (archived) policies. Defaults to false.
          schema:
            default: false
            example: false
            type: boolean
        - name: eligibilityStatus
          required: false
          in: query
          description: Filter by eligibility status
          schema:
            example: ACTIVE
            enum:
              - ACTIVE
              - INACTIVE
              - PENDING
              - UNKNOWN
              - TERMINATED
              - UNAVAILABLE
            type: string
        - name: updatedSince
          required: false
          in: query
          description: >-
            Only return policies whose record was created or modified at/after
            this timestamp (ISO 8601). When set, results are ordered by
            `updatedAt` ascending with `id` as tiebreaker, overriding
            `sortBy`/`sortOrder`. Must carry an explicit UTC offset (`...Z` or
            `...+02:00`) — a zone-less instant would be resolved against the
            database session timezone on some resources and the API process
            timezone on others, so the same string would mean two different
            moments. Pair with `cursorId` to walk safely — see that parameter;
            page/offset paging of this feed can drop rows. The bound is
            inclusive without `cursorId`, so boundary rows re-deliver — dedupe
            on `id`. A termination is visible as a change (`terminatedAt` is
            set), but pair with `includeTerminated=true` or the terminated row
            is filtered out of the delta entirely. **One fidelity limit remains,
            which is why this feed is not a full substitute for a periodic full
            walk.** `payerName`, `planName`, `policyType` and `payerPhone` are
            joined from the payer/plan tables, so a change to the payer or plan
            itself does not move the policy's `updatedAt` and is invisible here.
            The policy's own columns are covered: the EHR insurance sync
            compares values before writing, so a sync pass that changes nothing
            leaves `updatedAt` alone, and corrections made through the billing
            screens do move it. A hard delete cannot appear in a change feed
            either; a consumer that prunes still needs a full walk.
          schema:
            example: '2026-08-01T00:00:00.000Z'
            type: string
        - name: updatedUntil
          required: false
          in: query
          description: >-
            Only return policies whose record was last modified at/before this
            timestamp (ISO 8601). Pin this to the instant the walk started to
            freeze the window. Must carry an explicit UTC offset.
          schema:
            example: '2026-08-31T23:59:59.999Z'
            type: string
        - name: cursorId
          required: false
          in: query
          description: >-
            Id of the last row you already consumed, for a keyset walk. Pass it
            together with `updatedSince` set to that same row's `updatedAt`,
            always requesting page 1; the next page is everything ordered after
            (`updatedAt`, `id`). **Use this rather than page/offset for any walk
            that must not drop rows.** Paging a delta feed with page/offset is
            unsafe because the sort column is exactly what the sync workers
            rewrite: a row on an earlier page that changes mid-walk moves to the
            tail, every later row shifts one position toward the front, and the
            offset for the next page steps over whichever row moved into that
            slot. That row is never returned and its stamp is below the cursor
            the walk finishes on, so it is missed permanently while the walk
            still looks successful. On a cursor page `pagination.totalCount`
            counts the window starting at your cursor, so it shrinks as you walk
            — stop on a short page rather than on the count.
          schema:
            example: pol_a1b2c3d456784abc9def0123456789ab
            type: string
        - name: sortBy
          required: false
          in: query
          description: >-
            Sort field. Ignored when `updatedSince`/`updatedUntil` is set — see
            `updatedSince`.
          schema:
            example: coverageOrder
            enum:
              - createdAt
              - updatedAt
              - coverageOrder
            type: string
        - name: sortOrder
          required: false
          in: query
          description: Sort direction
          schema:
            example: asc
            enum:
              - asc
              - desc
            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/ListInsurancePoliciesSuccessResponseV3'
        '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'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiRateLimitResponse'
      security:
        - api-key: []
components:
  schemas:
    ListInsurancePoliciesSuccessResponseV3:
      type: object
      properties:
        code:
          type: string
          description: Response code
          example: success
        data:
          $ref: '#/components/schemas/ListInsurancePoliciesResponseDataV3'
      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
    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
    ListInsurancePoliciesResponseDataV3:
      type: object
      properties:
        insurancePolicies:
          type: array
          items:
            $ref: '#/components/schemas/ExternalInsurancePolicyResponseV3'
        pagination:
          $ref: '#/components/schemas/PaginationInfoResponse'
      required:
        - insurancePolicies
        - pagination
    ExternalInsurancePolicyResponseV3:
      type: object
      properties:
        id:
          type: string
          description: Insurance policy unique identifier
          example: pol_a1b2c3d456784abc9def0123456789ab
        patientId:
          type: string
          description: Patient ID this policy belongs to
          nullable: true
          example: pat_8de030393a9e417ab2b3a8b8df183631
        coverageOrder:
          type: number
          description: Coverage ranking (1 = primary, 2 = secondary, ...)
          example: 1
        memberId:
          type: string
          description: Member / policy number
          nullable: true
          example: XYZ123456789
        groupNumber:
          type: string
          description: Group number
          nullable: true
          example: GRP001
        planName:
          type: string
          description: Plan name
          nullable: true
          example: Blue Shield PPO
        policyType:
          type: string
          description: Policy type (e.g. PPO, HMO, MEDICARE)
          nullable: true
          example: PPO
        payerName:
          type: string
          description: Payer name
          nullable: true
          example: Blue Shield of California
        payerCode:
          type: string
          description: Payer ID (clearinghouse payer code)
          nullable: true
          example: BS001
        subscriberFirstName:
          type: string
          description: Subscriber first name
          nullable: true
          example: Jane
        subscriberLastName:
          type: string
          description: Subscriber last name
          nullable: true
          example: Doe
        patientRelationshipToPolicyHolder:
          type: string
          description: Patient relationship to policy holder
          nullable: true
          example: SELF
        copayAmount:
          type: string
          description: Copay amount
          nullable: true
          example: '25.00'
        deductibleRemaining:
          type: string
          description: Remaining deductible, refreshed by the latest eligibility check
          nullable: true
          example: '1250.00'
        referralRequired:
          type: boolean
          description: Whether a referral is required
          example: false
        policyEffectiveDate:
          type: string
          description: Policy effective date
          nullable: true
          example: '2025-01-01T00:00:00.000Z'
        policyEndDate:
          type: string
          description: Policy end/termination date reported by the EHR
          nullable: true
          example: '2026-01-01T00:00:00.000Z'
        terminatedAt:
          type: string
          description: >-
            When the policy was terminated/archived in the EHR (soft delete).
            Terminated policies remain listable with includeTerminated=true.
          nullable: true
          example: null
        eligibilityStatus:
          type: string
          description: Latest eligibility determination
          nullable: true
          enum:
            - ACTIVE
            - INACTIVE
            - PENDING
            - UNKNOWN
            - TERMINATED
            - UNAVAILABLE
          example: ACTIVE
        integrationEligibilityStatus:
          type: string
          description: Raw eligibility status string from the EHR
          nullable: true
          example: Eligible
        eligibilityVerifiedAt:
          type: string
          description: When eligibility was last verified
          nullable: true
          example: '2026-08-01T12:00:00.000Z'
        payerPhone:
          type: string
          description: >-
            The payer's contact phone number, from the payer directory this
            policy's plan resolves to. Null when the payer has no contact on
            file or the plan is unmapped. Not policy-specific — it is the
            payer's number, which is what a manufacturer hub form asks for.
          nullable: true
          example: (800) 555-0123
        source:
          type: string
          description: EHR source
          nullable: true
          enum:
            - modmed
            - ezderm
            - manual
        createdAt:
          type: string
          description: Created timestamp
          example: '2026-03-20T18:35:10.209Z'
        updatedAt:
          type: string
          description: Last updated timestamp
          example: '2026-03-23T03:15:47.285Z'
      required:
        - id
        - patientId
        - coverageOrder
        - memberId
        - groupNumber
        - planName
        - policyType
        - payerName
        - payerCode
        - subscriberFirstName
        - subscriberLastName
        - patientRelationshipToPolicyHolder
        - copayAmount
        - deductibleRemaining
        - referralRequired
        - policyEffectiveDate
        - policyEndDate
        - terminatedAt
        - eligibilityStatus
        - integrationEligibilityStatus
        - eligibilityVerifiedAt
        - payerPhone
        - source
        - createdAt
        - updatedAt
    PaginationInfoResponse:
      type: object
      properties:
        page:
          type: number
          description: Current page number
          example: 1
        pageSize:
          type: number
          description: Items per page
          example: 100
        totalCount:
          type: number
          description: Total number of items
          example: 250
        totalPages:
          type: number
          description: Total number of pages
          example: 3
      required:
        - page
        - pageSize
        - totalCount
        - totalPages
  securitySchemes:
    api-key:
      scheme: bearer
      bearerFormat: JWT
      type: http
      description: Marketplace API key

````