Run an eligibility check

Use this before a visit to confirm a patient’s insurance is active and to see copays, deductibles and whether prior authorization is needed.


Scopes	`benefits:read`, `benefits:write`
Cost	Billable. Step 2 is a paid request to the payer. Steps 1 and 3 are free.
Rate limit	Step 2: about 10 per minute per key, on top of the shared limit of about 60 per minute
Outside systems	Yes. Step 2 sends the member’s details to the payer through our clearinghouse.
Time	Usually a few seconds; allow up to a minute.

There is no test payer. A made-up member can’t be checked and the request can still be billed (see Test mode). Build against the example response below, then run real checks under your business associate agreement.

export HEALOS_API_KEY="hlsk_..."
export HEALOS="https://api.healos.ai/ext-api/v1"

Find the payer id

curl "$HEALOS/benefits/payers/search?q=aetna" -H "X-API-Key: $HEALOS_API_KEY"

Expect 200 with a list such as [{ "id": "60054", "name": "Aetna" }]. Queries shorter than 2 characters return an empty list. Save the right id as the payer_id.

Run the check

For a patient already in HealOS, send patient_id. HealOS uses their name, date of birth, gender and the member id on their active insurance for this payer:

curl -X POST "$HEALOS/benefits/eligibility-checks" \
  -H "X-API-Key: $HEALOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payer_id": "60054",
    "provider_name": "Riverside Family Medicine",
    "provider_npi": "1234567893",
    "patient_id": "481926357104938271"
  }'

Otherwise send member_id, first_name, last_name and date_of_birth (YYYY-MM-DD) instead of patient_id. provider_npi is the 10-digit NPI of the requesting provider or practice.Expect 200 with the saved check. Save data.id as CHECK_ID.

Don’t retry a request that returned 200 or a 4xx: each request is a new, billable check. Retry only after 502, 503 or 504, and wait first.

Read the result

The 200 response already holds the result. Read it again at any time, free of charge:

curl "$HEALOS/benefits/eligibility-checks/$CHECK_ID" -H "X-API-Key: $HEALOS_API_KEY"

Look at these fields:

Field	What it tells you
`data.status`	The coverage status the payer reported, for example `Active`
`data.result.plan`	Plan names, group number and coverage dates
`data.result.benefits`	One entry per benefit: co-payment, co-insurance, deductible, out-of-pocket, network, amount and whether prior auth is required
`data.result.issues`, `data.result.warnings`	Problems the payer reported, such as member not found

See what result contains for the full shape.

The same flow in Python

The steps above as one script, using requests (pip install requests). It reads the key and the HealOS patient id from environment variables, so nothing about a real patient lives in the code.

Step 2 is a billable payer request every time it runs. The script sends it once and retries only a 502, 503 or 504, once, after a wait. After a timeout it stops and asks you to check the history instead of sending the check again.

eligibility_check.py

import os
import time

import requests

BASE = "https://api.healos.ai/ext-api/v1"
http = requests.Session()
http.headers["X-API-Key"] = os.environ["HEALOS_API_KEY"]
patient_id = os.environ["HEALOS_PATIENT_ID"]  # a patient already in HealOS

# 1. Find the payer id (free).
payers = http.get(f"{BASE}/benefits/payers/search", params={"q": "aetna"}, timeout=30).json()["data"]
payer_id = payers[0]["id"]  # pick the right one from the list in real code

# 2. Run the check (billable).
request = {
    "payer_id": payer_id,
    "provider_name": "Riverside Family Medicine",
    "provider_npi": "1234567893",
    "patient_id": patient_id,
}
try:
    res = http.post(f"{BASE}/benefits/eligibility-checks", json=request, timeout=90)
    if res.status_code in (502, 503, 504):
        time.sleep(30)
        res = http.post(f"{BASE}/benefits/eligibility-checks", json=request, timeout=90)
except requests.Timeout:
    raise SystemExit(
        "No response. List this patient's recent checks before running another: "
        f"GET /benefits/eligibility-checks?patient_id={patient_id}"
    )

body = res.json()
if not res.ok:
    raise SystemExit(f"{res.status_code} {body.get('code')}: {body.get('error')}")
check_id = body["data"]["id"]

# 3. Read the result (free; the response above already holds it).
check = http.get(f"{BASE}/benefits/eligibility-checks/{check_id}", timeout=30).json()["data"]
print("Coverage status:", check["status"])
for issue in (check.get("result") or {}).get("issues", []):
    print("Payer issue:", issue)

Expected outcomes

Case	Expected result	What to do
Member found, coverage active	`200`, `status` `Active`, benefits listed	Use the benefits
Member found, coverage ended	`200`, a non-active `status`	Ask the patient for current insurance
Payer can’t match the member	`200` with `result.issues`, or `422` `PAYER_VALIDATION_ERROR`	Check member id, name and date of birth against the card
Missing or malformed field	`400` `VALIDATION_ERROR`	Fix the request; no payer request was made
`patient_id` not in your organization	`404` `PATIENT_NOT_FOUND`	No payer request was made
More than 10 checks in a minute	`429`	Wait for the next minute
Payer or clearinghouse slow or down	`502` or `504`	Wait, then retry once
Eligibility checking unavailable	`503` `SERVICE_UNAVAILABLE`	Retry later

Read past checks

Checks run in the HealOS dashboard and through the API share one history:

curl "$HEALOS/benefits/eligibility-checks?patient_id=481926357104938271" \
  -H "X-API-Key: $HEALOS_API_KEY"

Reuse a recent check instead of running a new one when you can.

Benefit verification guide
Run an eligibility check (reference)

Get Started

Recipes

Product Guides

Connections

EHR Integrations

Trust

Go Live

Run an eligibility check

The same flow in Python

Expected outcomes

Read past checks

​The same flow in Python

​Expected outcomes

​Read past checks

​Related

The same flow in Python

Expected outcomes

Read past checks

Related