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.
Mock Requests
To send a mock request without incurring charges, set themockRequest parameter in the body to true. There are 4 scenarios you may test with. Refer to
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 anN/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%" }
response includes:
deductible.total,deductible.remaining, anddeductible.yearToDate(when reported)stopLoss(total out-of-pocket maximum),stopLossRemaining, andstopLossYearToDate(when reported)
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).
Coordination of Benefits
This route allows an optionalrunCobCheck flag to automatically call the Coordination of Benefits using the information
in the eligibility check request. Using this flag may incur additional costs. Reach out to Cair for pricing.Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
Patient and coverage information
Patient first name
Patient last name
Patient Date of Birth, formatted as MM-DD-YYYY
Member ID of patient's insurance policy
Date to request coverage information. Formatted as MM-DD-YYYY
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 API
Billing Provider ID. Accepts either the CAIR logical provider ID (from /admin/provider/) or the clearinghouse provider ID from the Fetch Enrollments API
Optional flag to only return mock data
Service type codes to request coverage information for
CPT or CDT codes to check coverage for
Type of procedure codes being provided. Must be either 'CPT' or 'CDT'
CPT, CDT Whether to run a coordination of benefits check
Response
Eligibility check successful
Name of the insurance payer
Coverage status
Active Coverage, Inactive Member ID of the subscriber
Group name from the plan
Group number from the plan
Type of insurance (e.g. PPO, HMO, Commercial)
Name of the plan
Effective date range of the plan
Eligibility begin date (YYYY-MM-DD)
Dependent details when the policy is mapped from a family member
Map of service type codes to benefit information
Overall message about the eligibility check
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
Coordination of benefits information, only present if runCobCheck was true