What is an Eligibility Check?
An eligibility check verifies whether a patient has active health insurance coverage and what benefits their plan includes, such as:
Covered services
Co-pays and deductibles
Eligibility dates
Plan limitations
What are Real-Time Eligibility Checks?
A real-time check sends a digital request (X12 270) directly to the payer and returns the response (X12 271) within seconds. It helps you:
Confirm active coverage
Understand the patient’s financial responsibility
Prevent claim denials and administrative delays
When Should You Use Real-Time Checks?
During order processing
At patient registration
When verifying updated or new insurance information
💲 Transaction fees apply. Each eligibility request is billed at your insurance eligibility transaction rate.
⏱️ Rate limit: Both eligibility endpoints allow up to 25 requests per second.
Payer Enrollment May be Required
Some payers require transaction enrollment before you can submit eligibility checks. Enrollment confirms that your organization is authorized to exchange data with that payer. Check with our payer enrollment support team to see whether each payer you plan to query needs it.
Don’t Send Fake Data
Do not submit test eligibility checks with made-up patient or provider information.
⚠️ Important: Some payers, particularly CMS (HETS), strictly prohibit test transactions with fictitious data. Sending them can get your access blocked or revoked. Always use real patient and provider information in production.
Before You Start: Lookups
1. Service Location
GET /v1/organization/locations
The service location must already exist in NikoHealth. Its organization name and NPI are included in the eligibility request.
{
"Count": 1,
"Items": [
{
"Id": "OL1aebcb00cc4ba87960b4a80d06c842d1",
"Npi": "1881144111",
"Name": "Example Medical Supply LLC",
"Address": "123 Main St, Birmingham, AL 35203"
}
]
}
2. Payer, and Plan if Needed
GET /v1/payers/dictionaryreturns a paginated list of 10 by default; filter bynameorclaimCode.GET /v1/payers/{payerId}/plans/dictionary
Only send PayerPlanId when the plan has different electronic eligibility settings from its parent payer. Otherwise, PayerId alone is enough.
3. Service Types (Optional)
GET /v1/insurance/eligibility/service-types?name=Durable
[
{ "Id": "DurableMedicalEquipment", "Code": "DM", "Name": "Durable Medical Equipment" },
{ "Id": "DurableMedicalEquipmentPurchase", "Code": "12", "Name": "Durable Medical Equipment Purchase" },
{ "Id": "DurableMedicalEquipmentRental", "Code": "18", "Name": "Durable Medical Equipment Rental" }
]
In your request, send the Id value (for example DurableMedicalEquipment), not the X12 code.
Option 1: Check Coverage Without a Patient Record
POST /v1/insurance/eligibility
Use this endpoint to send a real-time eligibility check whether or not the patient exists in NikoHealth. It’s useful for:
Verifying coverage before onboarding a new patient
Checking eligibility for one-off encounters
Avoiding unnecessary patient records
Required Fields
Field | Notes |
|
|
| YYYY-MM-DD |
| From |
| From |
| The member ID, up to 80 characters |
|
|
Optional fields
Field | Notes |
|
|
| Only when the plan has its own eligibility settings |
| The policyholder’s name, gender and DOB when the policyholder isn’t the patient |
| For employer-insured policies |
| One date or a range. Defaults to today. We recommend dates no more than 12 months in the past and no later than the end of the current month. |
| Defaults to |
Example: the patient is the policyholder
POST /v1/insurance/eligibility
{
"Patient": {
"Name": { "FirstName": "Jane", "LastName": "Doe" },
"DateOfBirth": "1980-05-14",
"Gender": "Female",
"ServiceLocationId": "OL1aebcb00cc4ba87960b4a80d06c842d1"
},
"Insured": {
"PayerId": "3c8e1f5a9b2d47e6a0c4f81b7d395e2a6f0b4c19",
"PolicyNumber": "XYZ123456789",
"RelationshipToPatient": "Self"
},
"ServiceDates": { "From": "2026-11-10" },
"ServiceTypes": ["DurableMedicalEquipment"]
}
Example: the patient is a dependent and the spouse is the policyholder
{
"Patient": {
"Name": { "FirstName": "Jane", "LastName": "Doe" },
"DateOfBirth": "1980-05-14",
"ServiceLocationId": "OL1aebcb00cc4ba87960b4a80d06c842d1"
},
"Insured": {
"PayerId": "3c8e1f5a9b2d47e6a0c4f81b7d395e2a6f0b4c19",
"PolicyNumber": "XYZ123456789",
"RelationshipToPatient": "Spouse",
"Person": {
"Name": { "FirstName": "John", "LastName": "Doe" },
"Gender": "Male",
"DateOfBirth": "1978-09-02"
}
}
}
Option 2: Check Coverage for an Existing Patient
POST /v1/patients/{patientId}/insurances/{insuranceId}/eligibilityUse this endpoint when the patient and their insurance are already in NikoHealth. The check uses the insurance on file, so it’s tied to the correct patient and payer.
It’s ideal for:
Routine coverage checks for existing patients
Automating checks before order processing
Keeping results tied to existing records
Path Parameters
Parameter | Format |
| Numeric, for example |
| The Patient Insurance ID, for example |
Body (Optional)
Field | Notes |
| Defaults to today |
| If you leave it out, the service type comes from the patient’s insurance record |
Example
POST /v1/patients/10000105/insurances/PI46bd2b00c5eaaaebaf04f17dee14f7e5/eligibility
{
"ServiceDates": { "From": "2026-11-01", "To": "2026-11-30" },
"ServiceTypes": ["DurableMedicalEquipmentRental"]
}
You can also send an empty body {} to use all the defaults.
Response (Both Endpoints)
200 OK returns an Items array. Each item contains:
Field | Description |
| The payer that responded |
| Subscriber details returned by the payer |
| Plan information |
| Coverage, co-pays, deductibles and limitations |
| Warnings from the payer |
| Rejection reasons from the payer, if any |
⚠️ A 200 means the payer responded, not that the patient has coverage. Always check Errors and BenefitsInformation.
Common Errors
Code | Meaning |
400 | Invalid request, such as a missing required field or a bad enum value |
401 | The token is missing, expired or invalid |
403 | You don’t have permission to access this resource |
404 | The patient, insurance or referenced record wasn’t found |
429 | Too many requests (over 25 per second) |
