> ## 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 with STC/Procedure Code

> Provides real-time access to patient eligibility benefits information, including procedure-specific benefits 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.
</Warning>

## 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](../eligibility/mock-eligibility) 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.

## Coordination of Benefits

This route allows an optional `runCobCheck` flag to automatically call the [Coordination of Benefits](../eligibility/mock-eligibility) 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/v3
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/v3:
    post:
      description: >-
        Provides real-time access to patient eligibility benefits information,
        including procedure-specific benefits 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. Can be found under the enrollments page in the
                    platform, or the [Fetch Enrollments](../fetch-enrollments)
                    API
                providerId:
                  type: string
                  description: >-
                    Provider ID. Can be found by copying the enrollment ID in
                    the enrollments page in the platform, or the [Fetch
                    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: Doe
              patientDOB: 01-01-1991
              patientMemberId: U1234567
              dateOfCoverage: 03-24-2025
              payerId: HGJLR
              providerId: 0195b964-5b2c-7bb3-875a-276ad770dc66
              serviceTypeCodes:
                - '30'
              procedureCodes:
                - '99213'
                - '85025'
              procedureCodesType: CPT
              runCobCheck: true
        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)
                  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/BenefitDetails'
                            family:
                              $ref: '#/components/schemas/BenefitDetails'
                        outNetwork:
                          type: object
                          properties:
                            individual:
                              $ref: '#/components/schemas/BenefitDetails'
                            family:
                              $ref: '#/components/schemas/BenefitDetails'
                        message:
                          type: string
                          description: Message about the benefits information
                  message:
                    type: string
                    description: Overall message about the eligibility check
                  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: AETNA INC
                status: Active Coverage
                memberId: '1234567'
                groupName: N/A
                groupNumber: '7654321'
                insuranceType: PPO
                planName: Open Access Plus
                effectiveDateRange: null
                eligibilityBeginDate: '2009-01-01'
                dependents:
                  - firstName: John
                    lastName: Doe
                    middleName: M
                    dateOfBirth: 01-01-2000
                    relationToSubscriber: Child
                    address:
                      city: PALO ALTO
                      state: CA
                      address1: 3533 LA MATA WAY
                      postalCode: '94306'
                    gender: M
                    insuredIndicator: 'N'
                response:
                  '30':
                    inNetwork:
                      individual:
                        copay: N/A
                        deductible:
                          total: $2,000.00
                          remaining: $2,000.00
                        coinsurance: N/A
                        stopLoss: $6,850.00
                      family:
                        copay: N/A
                        deductible:
                          total: N/A
                          remaining: N/A
                        coinsurance: N/A
                        stopLoss: N/A
                    outNetwork:
                      individual:
                        copay: N/A
                        deductible:
                          total: $6,000.00
                          remaining: $6,000.00
                        coinsurance: N/A
                        stopLoss: $14,000.00
                      family:
                        copay: N/A
                        deductible:
                          total: N/A
                          remaining: N/A
                        coinsurance: N/A
                        stopLoss: N/A
                    message: Benefits information retrieved successfully
                message: Eligibility check successful
                cob:
                  cobCode: CobInstanceExistsPrimacyDetermined
                  requestedPlanBenefits:
                    - payerName: Blue Cross
                      serviceTypeCodes:
                        - code: '30'
                          name: Health Benefit Plan Coverage
                      benefitDate:
                        planStartDate: '2024-01-01'
                  additionalPlanBenefitInfo:
                    - payerName: Aetna
                      payerPrimacy: SecondaryPayer
                      serviceTypeCodes:
                        - code: '30'
                          name: Health Benefit Plan Coverage
                      benefitDate:
                        overlapBeginDate: '2024-01-01'
                        overlapEndDate: '2024-12-31'
                        planStartDate: '2024-01-01'
                        planEndDate: '2024-12-31'
                        coordinationOfBenefits: '2024-01-01'
                      subscriber:
                        firstName: John
                        lastName: Doe
                        dateOfBirth: '1990-01-01'
                        memberId: W9876543
        '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
    BenefitDetails:
      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
        coinsurance:
          type: string
          description: String containing percentage formatted coinsurance information
        stopLoss:
          type: string
          description: String containing money formatted stop loss information
    Error:
      type: object
      properties:
        message:
          type: string
          description: Error message
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````