Skip to main content

Insurance Eligibility via API

API endpoints for checking coverage without a patient record and for an existing patient.

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/dictionary returns a paginated list of 10 by default; filter by name or claimCode.

  • 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

Patient.Name.FirstName / LastName

Patient.DateOfBirth

YYYY-MM-DD

Patient.ServiceLocationId

From GET /v1/organization/locations

Insured.PayerId

From GET /v1/payers/dictionary

Insured.PolicyNumber

The member ID, up to 80 characters

Insured.RelationshipToPatient

Self, Spouse, Parent, Employer or Other

Optional fields

Field

Notes

Patient.Gender

Male or Female

Insured.PayerPlanId

Only when the plan has its own eligibility settings

Insured.Person

The policyholder’s name, gender and DOB when the policyholder isn’t the patient

Insured.EmployerName

For employer-insured policies

ServiceDates.From / To

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.

ServiceTypes

Defaults to HealthBenefitPlanCoverage (code 30)

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}/eligibility

Use 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

patientId

Numeric, for example 10000105

insuranceId

The Patient Insurance ID, for example PI46bd2b00c5eaaaebaf04f17dee14f7e5 (from GET /v1/patients/{patientId}/insurances)

Body (Optional)

Field

Notes

ServiceDates.From / To

Defaults to today

ServiceTypes

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

Payer

The payer that responded

Subscriber

Subscriber details returned by the payer

Plans

Plan information

BenefitsInformation

Coverage, co-pays, deductibles and limitations

Alerts

Warnings from the payer

Errors

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)

Did this answer your question?