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

# Real Time Eligibility Check (v4)

> Provides real-time access to patient eligibility benefits information, including out-of-pocket max remaining/YTD, service-level benefits (with in-network/out-of-network and individual/family breakdown), and optional coordination of benefits (COB) check.

> [!WARNING]
>
> The following endpoint requires provider enrollment through our platform. Refer to the platform help guides or contact Cair Support with any questions.

## Mock Requests

To send a mock request without incurring charges, set the `mockRequest` parameter in the body to `true`. There are 4 scenarios you may test with. Refer to
[Mock Eligibility](https://docs.cairhealth.com/api-reference/endpoint/eligibility/mock-eligibility.md) for the scenarios.

## Data Richness

The response you receive will vary by payer. We parse the EDI response to the best of our ability, and the presence of an `N/A` in any field
does not necessarily mean that the benefit is not present in the subscriber's insurance plan.

## Service Benefits & Accumulators

`/api/eligibility/v4` accepts the exact same request body as `v3` (`serviceTypeCodes`, `procedureCodes`, `procedureCodesType`, and `runCobCheck` are all optional, so `v1` request bodies work without modification).

In addition to the per-service-type benefit table under `response`, v4 returns a dynamic `serviceBenefits` map containing copay and coinsurance for any clinical service category reported by the payer. Each entry includes top-level summary fields as well as `inNetwork` and `outNetwork` (`individual` / `family`) breakdowns when reported by the payer:

* `officeVisit.copay` — e.g. `"$15.00"`
* `officeVisit.coinsurance` — e.g. `"20%"`
* `officeVisit.inNetwork.individual` — `{ "copay": "$15.00", "coinsurance": "20%" }`
* `officeVisit.outNetwork.individual` — `{ "coinsurance": "50%" }`

Each benefit cell in `response` includes:

* `deductible.total`, `deductible.remaining`, and `deductible.yearToDate` (when reported)
* `stopLoss` (total out-of-pocket maximum), `stopLossRemaining`, and `stopLossYearToDate` (when reported)

Plan-level `effectiveDateRange` (`{ "start": "YYYY-MM-DD", "end": "YYYY-MM-DD" }`) is automatically resolved from plan, benefit, or service-level date segments when present. Non-2xx error responses return `{ "error": "..." }`.

### Library of Possible `serviceBenefits` Keys

Common X12 Service Type Codes are grouped into canonical `serviceBenefits` keys below. Any additional X12 Service Type Code returned by a payer (across all 191 X12 service type codes) is dynamically converted from its X12 display name into camelCase (e.g. `71` "Audiology Exam" -> `audiologyExam`, `75` "Prosthetic Device" -> `prostheticDevice`).

| `serviceBenefits` Key | Display Label | Mapped X12 Service Type Codes / Detection Rules |
| :- | :- | :- |
| `officeVisit` | Office Visit | `98` (Professional Physician Visit - Office), `BY` (Office: Sick) |
| `specialist` | Specialist Visit | `96` (Professional Physician), `3` (Consultation), or `98` with Specialist notes |
| `preventiveCare` | Preventive Care | `BZ` (Office: Well), `67`, `68`, `80`, `81`, `82`, `CM`, `CN`, `CO` |
| `urgentCare` | Urgent Care | `UC` |
| `emergency` | Emergency | `86` (Emergency Services), `51` (Emergency Accident), `52` (Emergency Medical) |
| `diagnosticLab` | Diagnostic Lab | `5` (Diagnostic Lab), `73` (Diagnostic Medical), `66` (Pathology), `CL` (Screening Lab) |
| `diagnosticXRay` | Diagnostic X-Ray | `4` (Diagnostic X-Ray), `CK` (Screening X-Ray) |
| `advancedImaging` | Advanced Imaging (MRI/CT) | `62` (MRI/CAT Scan) |
| `telehealth` | Telehealth | `GT`, Place of Service `02`/`10`, or notes (`telehealth`, `telemedicine`, `teladoc`, `virtual`) |
| `inpatientHospital` | Inpatient Hospital | `48` (Hospital - Inpatient), `49` (Room and Board), `99` (Physician Visit - Inpatient) |
| `outpatientHospital` | Outpatient Hospital | `50` (Hospital - Outpatient), `53` (Ambulatory Surgical), `13` (ASC Facility) |
| `outpatientVisit` | Outpatient Physician Visit | `A0` (Professional Physician Visit - Outpatient) |
| `hospital` | Hospital | `47` (Hospital) |
| `chiropractic` | Chiropractic | `33` (Chiropractic), `34` (Chiropractic Office Visits) |
| `physicalTherapy` | Physical Therapy | `PT` (Physical Therapy), `AE` (Physical Medicine) |
| `occupationalTherapy` | Occupational Therapy | `AD` (Occupational Therapy) |
| `speechTherapy` | Speech Therapy | `AF` (Speech Therapy) |
| `mentalHealth` | Mental Health | `MH`, `A4`, `A5`, `A6` (Psychotherapy), `A7`, `A8`, `BB`, `BC`, `CE`, `CF`, `CG`, `CH`, `RT` |
| `substanceAbuse` | Substance Abuse | `AI`, `AJ` (Alcoholism), `AK` (Drug Addiction), `CI`, `CJ` |
| `pharmacy` | Pharmacy | `88`, `89`, `90`, `91`, `92`, `B2`, `B3`, `BW`, `BX`, `GF`, `GN` |
| `dental` | Dental Care | `35`, `23`, `24`, `25`, `26`, `27`, `28`, `36`, `37`, `38`, `39`, `40`, `41` |
| `vision` | Vision (Optometry) | `AL`, `AM`, `AN`, `AO`, `BR`, `CP` |
| `podiatry` | Podiatry | `93`, `94`, `95` |
| `homeHealth` | Home Health Care | `42`, `43`, `44`, `A3`, `CB` |
| `hospice` | Hospice | `45`, `46` |
| `skilledNursing` | Skilled Nursing Care | `AG`, `AH`, `A1`, `A2`, `CA` |
| `maternity` | Maternity | `69`, `65` (Newborn Care), `BU`, `BV` |
| `gynecological` | Gynecological | `BT` |
| `durableMedicalEquipment` | Durable Medical Equipment | `DM`, `11`, `12`, `18` |
| `surgery` | Surgical | `2`, `8`, `20`, `21`, `CC`, `CD` |
| `anesthesia` | Anesthesia | `7`, `97` |
| `allergy` | Allergy | `79`, `GY` |
| `chemotherapy` | Chemotherapy / Oncology | `78`, `ON` |
| `radiationTherapy` | Radiation Therapy | `6` |
| `dialysis` | Dialysis / Renal | `76`, `14`, `15`, `16`, `RN` |
| `rehabilitation` | Rehabilitation | `A9`, `AA`, `AB`, `AC`, `BD`, `BF`, `BG` |
| `acupuncture` | Acupuncture | `64` |
| `dermatology` | Dermatology | `DG`, `BJ` |
| `orthopedic` | Orthopedic | `BK` |
| `cardiac` | Cardiac | `BL`, `C1` |
| `neurology` | Neurology | `BQ` |
| `gastrointestinal` | Gastrointestinal | `BN` |
| `endocrine` | Endocrine | `BP`, `DS` |
| `pulmonary` | Pulmonary | `PU`, `72` |
| `pediatric` | Pediatric | `BH`, `BI` |
| `ambulance` | Ambulance / Transportation | `56`, `57`, `58`, `59` |

## Coordination of Benefits

This route allows an optional `runCobCheck` flag to automatically call the [Coordination of Benefits](https://docs.cairhealth.com/api-reference/endpoint/eligibility/mock-eligibility.md) using the information
in the eligibility check request. Using this flag may incur additional costs. Reach out to Cair for pricing.


## OpenAPI

````yaml POST /api/eligibility/v4
openapi: 3.1.0
info:
  title: Cair Health APIs
  description: APIs for the Cair Health platform
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://forecaster.cairhealth.com
security:
  - bearerAuth: []
paths:
  /api/eligibility/v4:
    post:
      description: >-
        Provides real-time access to patient eligibility benefits information,
        including out-of-pocket max remaining/YTD, service-level benefits (with
        in-network/out-of-network and individual/family breakdown), and optional
        coordination of benefits (COB) check.
      requestBody:
        description: Patient and coverage information
        content:
          application/json:
            schema:
              type: object
              properties:
                patientFirstName:
                  type: string
                  description: Patient first name
                patientLastName:
                  type: string
                  description: Patient last name
                patientDOB:
                  type: string
                  description: Patient Date of Birth, formatted as MM-DD-YYYY
                patientMemberId:
                  type: string
                  description: Member ID of patient's insurance policy
                dateOfCoverage:
                  type: string
                  description: >-
                    Date to request coverage information. Formatted as
                    MM-DD-YYYY
                payerId:
                  type: string
                  description: >-
                    Payer ID. Accepts either the Stedi Payer ID (e.g. 'KMQTZ',
                    'HGJLR') or the Primary Payer ID (e.g. '87726') from the
                    platform or the [Fetch
                    Enrollments](../enrollments/fetch-enrollments) API
                providerId:
                  type: string
                  description: >-
                    Billing Provider ID. Accepts either the CAIR logical
                    provider ID (from /admin/provider/<id>) or the clearinghouse
                    provider ID from the [Fetch
                    Enrollments](../enrollments/fetch-enrollments) API
                mockRequest:
                  type: boolean
                  description: Optional flag to only return mock data
                  optional: true
                serviceTypeCodes:
                  type: array
                  description: Service type codes to request coverage information for
                  items:
                    type: string
                  optional: true
                procedureCodes:
                  type: array
                  description: CPT or CDT codes to check coverage for
                  items:
                    type: string
                  optional: true
                procedureCodesType:
                  type: string
                  description: >-
                    Type of procedure codes being provided. Must be either 'CPT'
                    or 'CDT'
                  enum:
                    - CPT
                    - CDT
                  optional: true
                runCobCheck:
                  type: boolean
                  description: Whether to run a coordination of benefits check
                  optional: true
              required:
                - patientFirstName
                - patientLastName
                - patientDOB
                - patientMemberId
                - dateOfCoverage
                - payerId
                - providerId
            example:
              patientFirstName: John
              patientLastName: Major
              patientDOB: 07-24-1974
              patientMemberId: '08398469900'
              dateOfCoverage: 09-14-2026
              payerId: KMQTZ
              providerId: 2b63e721-7fb5-4a4c-9249-620f1c4e9d7e
        required: true
      responses:
        '200':
          description: Eligibility check successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  payerName:
                    type: string
                    description: Name of the insurance payer
                  status:
                    type: string
                    enum:
                      - Active Coverage
                      - Inactive
                    description: Coverage status
                  memberId:
                    type: string
                    description: Member ID of the subscriber
                  groupName:
                    type: string
                    description: Group name from the plan
                  groupNumber:
                    type: string
                    description: Group number from the plan
                  insuranceType:
                    type: string
                    description: Type of insurance (e.g. PPO, HMO, Commercial)
                  planName:
                    type: string
                    description: Name of the plan
                  effectiveDateRange:
                    type: object
                    nullable: true
                    description: Effective date range of the plan
                    properties:
                      start:
                        type: string
                        description: Start date (YYYY-MM-DD)
                      end:
                        type: string
                        description: End date (YYYY-MM-DD)
                  eligibilityBeginDate:
                    type: string
                    description: Eligibility begin date (YYYY-MM-DD)
                  dependents:
                    type: array
                    description: >-
                      Dependent details when the policy is mapped from a family
                      member
                    items:
                      $ref: '#/components/schemas/EligibilityDependent'
                  response:
                    type: object
                    description: Map of service type codes to benefit information
                    additionalProperties:
                      type: object
                      properties:
                        inNetwork:
                          type: object
                          properties:
                            individual:
                              $ref: '#/components/schemas/BenefitDetailsV3'
                            family:
                              $ref: '#/components/schemas/BenefitDetailsV3'
                        outNetwork:
                          type: object
                          properties:
                            individual:
                              $ref: '#/components/schemas/BenefitDetailsV3'
                            family:
                              $ref: '#/components/schemas/BenefitDetailsV3'
                        message:
                          type: string
                          description: Message about the benefits information
                  message:
                    type: string
                    description: Overall message about the eligibility check
                  serviceBenefits:
                    type: object
                    description: >-
                      Dynamic map of common service categories to copay and
                      coinsurance values (with in-network/out-of-network and
                      individual/family breakdown), present per service only
                      when the payer reports values
                    additionalProperties:
                      $ref: '#/components/schemas/ServiceBenefitValues'
                    properties:
                      officeVisit:
                        $ref: '#/components/schemas/ServiceBenefitValues'
                      specialist:
                        $ref: '#/components/schemas/ServiceBenefitValues'
                      preventiveCare:
                        $ref: '#/components/schemas/ServiceBenefitValues'
                      urgentCare:
                        $ref: '#/components/schemas/ServiceBenefitValues'
                      emergency:
                        $ref: '#/components/schemas/ServiceBenefitValues'
                      diagnosticLab:
                        $ref: '#/components/schemas/ServiceBenefitValues'
                      diagnosticXRay:
                        $ref: '#/components/schemas/ServiceBenefitValues'
                      advancedImaging:
                        $ref: '#/components/schemas/ServiceBenefitValues'
                      telehealth:
                        $ref: '#/components/schemas/ServiceBenefitValues'
                      inpatientHospital:
                        $ref: '#/components/schemas/ServiceBenefitValues'
                      outpatientHospital:
                        $ref: '#/components/schemas/ServiceBenefitValues'
                      chiropractic:
                        $ref: '#/components/schemas/ServiceBenefitValues'
                      physicalTherapy:
                        $ref: '#/components/schemas/ServiceBenefitValues'
                      occupationalTherapy:
                        $ref: '#/components/schemas/ServiceBenefitValues'
                      speechTherapy:
                        $ref: '#/components/schemas/ServiceBenefitValues'
                      mentalHealth:
                        $ref: '#/components/schemas/ServiceBenefitValues'
                      pharmacy:
                        $ref: '#/components/schemas/ServiceBenefitValues'
                      dental:
                        $ref: '#/components/schemas/ServiceBenefitValues'
                      vision:
                        $ref: '#/components/schemas/ServiceBenefitValues'
                  cob:
                    type: object
                    description: >-
                      Coordination of benefits information, only present if
                      runCobCheck was true
                    properties:
                      cobCode:
                        type: string
                        description: Code indicating the type of coordination of benefits
                      requestedPlanBenefits:
                        type: array
                        description: Information about the requested plan benefits
                        items:
                          type: object
                          properties:
                            payerName:
                              type: string
                              description: Name of the payer
                            serviceTypeCodes:
                              type: array
                              description: Service type codes and their descriptions
                              items:
                                type: object
                                properties:
                                  code:
                                    type: string
                                    description: Service type code
                                  name:
                                    type: string
                                    description: Description of the service type
                            benefitDate:
                              type: object
                              properties:
                                planStartDate:
                                  type: string
                                  description: Start date of the plan
                      additionalPlanBenefitInfo:
                        type: array
                        description: Additional information about plan benefits
                        items:
                          type: object
                          properties:
                            payerName:
                              type: string
                              description: Name of the payer
                            payerPrimacy:
                              type: string
                              description: >-
                                Indicates if this is the primary or secondary
                                payer
                            serviceTypeCodes:
                              type: array
                              description: Service type codes and their descriptions
                              items:
                                type: object
                                properties:
                                  code:
                                    type: string
                                    description: Service type code
                                  name:
                                    type: string
                                    description: Description of the service type
                            benefitDate:
                              type: object
                              properties:
                                overlapBeginDate:
                                  type: string
                                  description: Start date of benefit overlap
                                overlapEndDate:
                                  type: string
                                  description: End date of benefit overlap
                                planStartDate:
                                  type: string
                                  description: Start date of the plan
                                planEndDate:
                                  type: string
                                  description: End date of the plan
                                coordinationOfBenefits:
                                  type: string
                                  description: Coordination of benefits date
                            subscriber:
                              type: object
                              properties:
                                firstName:
                                  type: string
                                  description: Subscriber's first name
                                lastName:
                                  type: string
                                  description: Subscriber's last name
                                dateOfBirth:
                                  type: string
                                  description: Subscriber's date of birth
                                memberId:
                                  type: string
                                  description: Subscriber's member ID
              example:
                payerName: UNITEDHEALTHCARE
                status: Active Coverage
                memberId: '08398469900'
                groupName: N/A
                groupNumber: '1771499'
                insuranceType: Commercial
                planName: Select Plus
                effectiveDateRange:
                  start: '2026-01-01'
                  end: '2026-12-31'
                eligibilityBeginDate: '2026-01-01'
                dependents: []
                response:
                  '30':
                    inNetwork:
                      individual:
                        copay: $30.00
                        deductible:
                          total: $250.00
                          remaining: $0.00
                          yearToDate: $250.00
                        coinsurance: 20%
                        stopLoss: $4,200.00
                        stopLossRemaining: $0.00
                        stopLossYearToDate: $4,200.00
                      family:
                        copay: N/A
                        deductible:
                          total: N/A
                          remaining: N/A
                        coinsurance: N/A
                        stopLoss: N/A
                        stopLossRemaining: N/A
                    outNetwork:
                      individual:
                        copay: $0.00
                        deductible:
                          total: $1,000.00
                          remaining: $892.37
                        coinsurance: 50%
                        stopLoss: $8,400.00
                        stopLossRemaining: $8,292.37
                      family:
                        copay: N/A
                        deductible:
                          total: N/A
                          remaining: N/A
                        coinsurance: N/A
                        stopLoss: N/A
                        stopLossRemaining: N/A
                    message: N/A
                serviceBenefits:
                  officeVisit:
                    copay: $15.00
                    coinsurance: 20%
                    inNetwork:
                      individual:
                        copay: $15.00
                        coinsurance: 20%
                    outNetwork:
                      individual:
                        coinsurance: 50%
                  urgentCare:
                    copay: $50.00
                    coinsurance: 0%
                    inNetwork:
                      individual:
                        copay: $50.00
                        coinsurance: 0%
                    outNetwork:
                      individual:
                        coinsurance: 50%
                  emergency:
                    copay: $200.00
                    coinsurance: 20%
                    inNetwork:
                      individual:
                        copay: $200.00
                        coinsurance: 20%
                    outNetwork:
                      individual:
                        copay: $200.00
                        coinsurance: 20%
                  telehealth:
                    copay: $15.00
                    coinsurance: 0%
                    inNetwork:
                      individual:
                        copay: $15.00
                        coinsurance: 0%
                message: Eligibility check successful
                cob:
                  error: No COB check run
        '400':
          description: Invalid request body or validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized access or invalid organization ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error or provider/payer enrollment issue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  schemas:
    EligibilityDependent:
      type: object
      description: Dependent information when the policy is mapped from a family member
      properties:
        firstName:
          type: string
          description: Dependent first name
        lastName:
          type: string
          description: Dependent last name
        middleName:
          type: string
          description: Dependent middle name
        dateOfBirth:
          type: string
          description: Dependent date of birth
        relationToSubscriber:
          type: string
          description: Relationship to subscriber (e.g. Spouse, Child)
        relationToSubscriberCode:
          type: string
          description: X12 code for relationship to subscriber
        groupNumber:
          type: string
          description: Group number for the dependent
        address:
          type: object
          properties:
            address1:
              type: string
            city:
              type: string
            state:
              type: string
            postalCode:
              type: string
        gender:
          type: string
          description: Dependent gender
        insuredIndicator:
          type: string
          description: Whether the dependent is the insured
        maintenanceTypeCode:
          type: string
          description: Maintenance type code
        maintenanceReasonCode:
          type: string
          description: Maintenance reason code
    BenefitDetailsV3:
      type: object
      properties:
        copay:
          type: string
          description: String containing money formatted copay information
        deductible:
          type: object
          properties:
            total:
              type: string
              description: Total deductible amount
            remaining:
              type: string
              description: Remaining deductible amount
            yearToDate:
              type: string
              description: Year-to-date deductible amount spent when reported by the payer
        coinsurance:
          type: string
          description: String containing percentage formatted coinsurance information
        stopLoss:
          type: string
          description: >-
            String containing money formatted stop loss (out-of-pocket max)
            information
        stopLossRemaining:
          type: string
          description: >-
            String containing money formatted remaining stop loss (out-of-pocket
            max) amount
        stopLossYearToDate:
          type: string
          description: >-
            String containing money formatted year-to-date stop loss
            (out-of-pocket max) amount spent when reported by the payer
    ServiceBenefitValues:
      type: object
      description: >-
        Copay and coinsurance reported by the payer for a fixed service
        category, with top-level summary values and in-network/out-of-network
        individual/family breakdown.
      properties:
        copay:
          type: string
          description: String containing money formatted copay information
        coinsurance:
          type: string
          description: String containing percentage formatted coinsurance information
        inNetwork:
          type: object
          properties:
            individual:
              $ref: '#/components/schemas/ServiceBenefitCell'
            family:
              $ref: '#/components/schemas/ServiceBenefitCell'
        outNetwork:
          type: object
          properties:
            individual:
              $ref: '#/components/schemas/ServiceBenefitCell'
            family:
              $ref: '#/components/schemas/ServiceBenefitCell'
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
        message:
          type: string
          description: Error message
    ServiceBenefitCell:
      type: object
      properties:
        copay:
          type: string
          description: String containing money formatted copay information
        coinsurance:
          type: string
          description: String containing percentage formatted coinsurance information
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

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