> ## Documentation Index
> Fetch the complete documentation index at: https://docs.healos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Run an eligibility check

> Find the payer, check a patient's coverage and read the result

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. |

> [!WARNING]
>
> There is no test payer. A made-up member can't be checked and the request
> can still be billed (see [Test mode](https://docs.healos.ai/test-mode.md#eligibility-checks)). Build
> against the example response below, then run real checks under your
> business associate agreement.

```bash theme={null}
export HEALOS_API_KEY="hlsk_..."
export HEALOS="https://api.healos.ai/ext-api/v1"
```

**1. Find the payer id**

```bash theme={null}
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`.

**2. 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:

```bash theme={null}
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`.

> [!WARNING]
>
> 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.

**3. Read the result**

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

```bash theme={null}
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](https://docs.healos.ai/benefits#what-result-contains) for the full
shape.

## The same flow in Python

The steps above as one script, using
[requests](https://pypi.org/project/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.

> [!WARNING]
>
> 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.

```python eligibility_check.py theme={null}
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:

```bash theme={null}
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.

## Related

* [Benefit verification guide](https://docs.healos.ai/benefits.md)
* [Run an eligibility check](https://docs.healos.ai/api-reference/benefits/run-an-eligibility-check.md) (reference)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.