---
title: "POST /api/eligibility/v4"
method: POST
path: "/api/eligibility/v4"
---

# POST /api/eligibility/v4

`POST /api/eligibility/v4`

## Request

- Base URL: `https://forecaster.cairhealth.com`
- URL: `https://forecaster.cairhealth.com/api/eligibility/v4`
- Auth: HTTP bearer

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.

## Request body

- object
  - `patientFirstName` string, required: Patient first name
  - `patientLastName` string, required: Patient last name
  - `patientDOB` string, required: Patient Date of Birth, formatted as MM-DD-YYYY
  - `patientMemberId` string, required: Member ID of patient's insurance policy
  - `dateOfCoverage` string, required: Date to request coverage information. Formatted as MM-DD-YYYY
  - `payerId` string, required: 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` string, required: 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` boolean: Optional flag to only return mock data
  - `serviceTypeCodes` string[]: Service type codes to request coverage information for
  - `procedureCodes` string[]: CPT or CDT codes to check coverage for
  - `procedureCodesType` 'CPT' | 'CDT': Type of procedure codes being provided. Must be either 'CPT' or 'CDT'
  - `runCobCheck` boolean: Whether to run a coordination of benefits check

## Response `200`

Eligibility check successful

- object
  - `payerName` string: Name of the insurance payer
  - `status` 'Active Coverage' | 'Inactive': Coverage status
  - `memberId` string: Member ID of the subscriber
  - `groupName` string: Group name from the plan
  - `groupNumber` string: Group number from the plan
  - `insuranceType` string: Type of insurance (e.g. PPO, HMO, Commercial)
  - `planName` string: Name of the plan
  - `effectiveDateRange` object, nullable: Effective date range of the plan
    - `start` string: Start date (YYYY-MM-DD)
    - `end` string: End date (YYYY-MM-DD)
  - `eligibilityBeginDate` string: Eligibility begin date (YYYY-MM-DD)
  - `dependents` EligibilityDependent[]: Dependent details when the policy is mapped from a family member
    - `firstName` string: Dependent first name
    - `lastName` string: Dependent last name
    - `middleName` string: Dependent middle name
    - `dateOfBirth` string: Dependent date of birth
    - `relationToSubscriber` string: Relationship to subscriber (e.g. Spouse, Child)
    - `relationToSubscriberCode` string: X12 code for relationship to subscriber
    - `groupNumber` string: Group number for the dependent
    - `address` object
      - `address1` string
      - `city` string
      - `state` string
      - `postalCode` string
    - `gender` string: Dependent gender
    - `insuredIndicator` string: Whether the dependent is the insured
    - `maintenanceTypeCode` string: Maintenance type code
    - `maintenanceReasonCode` string: Maintenance reason code
  - `response` object: Map of service type codes to benefit information
  - `message` string: Overall message about the eligibility check
  - `serviceBenefits` object: 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
    - `officeVisit` ServiceBenefitValues: 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.
      - `copay` string: String containing money formatted copay information
      - `coinsurance` string: String containing percentage formatted coinsurance information
      - `inNetwork` object
        - `individual` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
        - `family` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
      - `outNetwork` object
        - `individual` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
        - `family` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
    - `specialist` ServiceBenefitValues: 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.
      - `copay` string: String containing money formatted copay information
      - `coinsurance` string: String containing percentage formatted coinsurance information
      - `inNetwork` object
        - `individual` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
        - `family` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
      - `outNetwork` object
        - `individual` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
        - `family` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
    - `preventiveCare` ServiceBenefitValues: 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.
      - `copay` string: String containing money formatted copay information
      - `coinsurance` string: String containing percentage formatted coinsurance information
      - `inNetwork` object
        - `individual` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
        - `family` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
      - `outNetwork` object
        - `individual` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
        - `family` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
    - `urgentCare` ServiceBenefitValues: 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.
      - `copay` string: String containing money formatted copay information
      - `coinsurance` string: String containing percentage formatted coinsurance information
      - `inNetwork` object
        - `individual` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
        - `family` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
      - `outNetwork` object
        - `individual` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
        - `family` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
    - `emergency` ServiceBenefitValues: 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.
      - `copay` string: String containing money formatted copay information
      - `coinsurance` string: String containing percentage formatted coinsurance information
      - `inNetwork` object
        - `individual` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
        - `family` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
      - `outNetwork` object
        - `individual` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
        - `family` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
    - `diagnosticLab` ServiceBenefitValues: 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.
      - `copay` string: String containing money formatted copay information
      - `coinsurance` string: String containing percentage formatted coinsurance information
      - `inNetwork` object
        - `individual` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
        - `family` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
      - `outNetwork` object
        - `individual` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
        - `family` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
    - `diagnosticXRay` ServiceBenefitValues: 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.
      - `copay` string: String containing money formatted copay information
      - `coinsurance` string: String containing percentage formatted coinsurance information
      - `inNetwork` object
        - `individual` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
        - `family` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
      - `outNetwork` object
        - `individual` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
        - `family` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
    - `advancedImaging` ServiceBenefitValues: 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.
      - `copay` string: String containing money formatted copay information
      - `coinsurance` string: String containing percentage formatted coinsurance information
      - `inNetwork` object
        - `individual` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
        - `family` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
      - `outNetwork` object
        - `individual` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
        - `family` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
    - `telehealth` ServiceBenefitValues: 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.
      - `copay` string: String containing money formatted copay information
      - `coinsurance` string: String containing percentage formatted coinsurance information
      - `inNetwork` object
        - `individual` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
        - `family` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
      - `outNetwork` object
        - `individual` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
        - `family` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
    - `inpatientHospital` ServiceBenefitValues: 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.
      - `copay` string: String containing money formatted copay information
      - `coinsurance` string: String containing percentage formatted coinsurance information
      - `inNetwork` object
        - `individual` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
        - `family` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
      - `outNetwork` object
        - `individual` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
        - `family` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
    - `outpatientHospital` ServiceBenefitValues: 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.
      - `copay` string: String containing money formatted copay information
      - `coinsurance` string: String containing percentage formatted coinsurance information
      - `inNetwork` object
        - `individual` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
        - `family` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
      - `outNetwork` object
        - `individual` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
        - `family` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
    - `chiropractic` ServiceBenefitValues: 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.
      - `copay` string: String containing money formatted copay information
      - `coinsurance` string: String containing percentage formatted coinsurance information
      - `inNetwork` object
        - `individual` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
        - `family` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
      - `outNetwork` object
        - `individual` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
        - `family` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
    - `physicalTherapy` ServiceBenefitValues: 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.
      - `copay` string: String containing money formatted copay information
      - `coinsurance` string: String containing percentage formatted coinsurance information
      - `inNetwork` object
        - `individual` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
        - `family` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
      - `outNetwork` object
        - `individual` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
        - `family` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
    - `occupationalTherapy` ServiceBenefitValues: 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.
      - `copay` string: String containing money formatted copay information
      - `coinsurance` string: String containing percentage formatted coinsurance information
      - `inNetwork` object
        - `individual` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
        - `family` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
      - `outNetwork` object
        - `individual` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
        - `family` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
    - `speechTherapy` ServiceBenefitValues: 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.
      - `copay` string: String containing money formatted copay information
      - `coinsurance` string: String containing percentage formatted coinsurance information
      - `inNetwork` object
        - `individual` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
        - `family` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
      - `outNetwork` object
        - `individual` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
        - `family` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
    - `mentalHealth` ServiceBenefitValues: 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.
      - `copay` string: String containing money formatted copay information
      - `coinsurance` string: String containing percentage formatted coinsurance information
      - `inNetwork` object
        - `individual` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
        - `family` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
      - `outNetwork` object
        - `individual` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
        - `family` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
    - `pharmacy` ServiceBenefitValues: 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.
      - `copay` string: String containing money formatted copay information
      - `coinsurance` string: String containing percentage formatted coinsurance information
      - `inNetwork` object
        - `individual` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
        - `family` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
      - `outNetwork` object
        - `individual` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
        - `family` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
    - `dental` ServiceBenefitValues: 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.
      - `copay` string: String containing money formatted copay information
      - `coinsurance` string: String containing percentage formatted coinsurance information
      - `inNetwork` object
        - `individual` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
        - `family` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
      - `outNetwork` object
        - `individual` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
        - `family` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
    - `vision` ServiceBenefitValues: 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.
      - `copay` string: String containing money formatted copay information
      - `coinsurance` string: String containing percentage formatted coinsurance information
      - `inNetwork` object
        - `individual` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
        - `family` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
      - `outNetwork` object
        - `individual` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
        - `family` ServiceBenefitCell
          - `copay` string: String containing money formatted copay information
          - `coinsurance` string: String containing percentage formatted coinsurance information
  - `cob` object: Coordination of benefits information, only present if runCobCheck was true
    - `cobCode` string: Code indicating the type of coordination of benefits
    - `requestedPlanBenefits` object[]: Information about the requested plan benefits
      - `payerName` string: Name of the payer
      - `serviceTypeCodes` object[]: Service type codes and their descriptions
        - `code` string: Service type code
        - `name` string: Description of the service type
      - `benefitDate` object
        - `planStartDate` string: Start date of the plan
    - `additionalPlanBenefitInfo` object[]: Additional information about plan benefits
      - `payerName` string: Name of the payer
      - `payerPrimacy` string: Indicates if this is the primary or secondary payer
      - `serviceTypeCodes` object[]: Service type codes and their descriptions
        - `code` string: Service type code
        - `name` string: Description of the service type
      - `benefitDate` object
        - `overlapBeginDate` string: Start date of benefit overlap
        - `overlapEndDate` string: End date of benefit overlap
        - `planStartDate` string: Start date of the plan
        - `planEndDate` string: End date of the plan
        - `coordinationOfBenefits` string: Coordination of benefits date
      - `subscriber` object
        - `firstName` string: Subscriber's first name
        - `lastName` string: Subscriber's last name
        - `dateOfBirth` string: Subscriber's date of birth
        - `memberId` string: Subscriber's member ID

## Other responses

- `400`: Invalid request body or validation error
- `401`: Unauthorized access or invalid organization ID
- `500`: Server error or provider/payer enrollment issue

## Changes

- **2026-11-03** `b32380ccde9a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/cairhealth/apis/cair-health-apis/changes/api/eligibility/v4/post.md)

---

[API](https://skmtc.dev/cairhealth/apis/cair-health-apis.md) - [All operations](https://skmtc.dev/cairhealth/apis/cair-health-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/cairhealth/apis/cair-health-apis/revisions/b32380ccde9a?raw)