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

# POST /api/eligibility/v2

`POST /api/eligibility/v2`

## Request

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

Provides real-time access to patient eligibility benefits information, such as deductibles, copays, etc.

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

## 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)
  - `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: Message of response. Any errors will be displayed here.

## Other responses

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

## Changes

- **2026-11-03** `b32380ccde9a`: 3 info
  - added the non-success response with the status `400`
  - added the optional property `error` to the response with the `401` status
  - added the optional property `error` to the response with the `500` status

[Operation history](https://skmtc.dev/cairhealth/apis/cair-health-apis/changes/api/eligibility/v2/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)