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

# Benefit Verification

> Run insurance eligibility checks and read past results

# Benefit Verification

The benefits endpoints check a patient's insurance coverage with their payer in
real time (an X12 270/271 eligibility request) and keep every result in your
organization's benefits history. Checks you run through the API also appear in
the HealOS dashboard, and checks run in the dashboard can be read through the
API.

| Endpoint | Scope | What it does |
| - | - | - |
| `GET /benefits/payers/search` | `benefits:read` | Find the `payer_id` for a payer |
| `POST /benefits/eligibility-checks` | `benefits:write` | Run a check and return the result |
| `GET /benefits/eligibility-checks` | `benefits:read` | List past checks, optionally for one patient |
| `GET /benefits/eligibility-checks/{checkId}` | `benefits:read` | Get one check with the full payer response |

> [!WARNING]
>
> Eligibility results contain protected health information (member ids,
> dates of birth, coverage details). Only use these endpoints under your
> business associate agreement with HealOS, and store the results as PHI.

## 1. Find the payer

Search by payer name or id (at least 2 characters). Use the returned `id` as
`payer_id`.

```bash theme={null}
curl "https://api.healos.ai/ext-api/v1/benefits/payers/search?q=aetna" \
  -H "X-API-Key: $HEALOS_API_KEY"
```

```json theme={null}
{ "data": [ { "id": "60054", "name": "Aetna" } ] }
```

## 2. Run a check

You always send the payer and the requesting provider. For the patient, send
either:

* `patient_id` for a patient already in HealOS. HealOS uses the patient's name,
  date of birth, gender, and the member id of their active insurance for this
  payer; or
* `member_id`, `first_name`, `last_name` and `date_of_birth` (YYYY-MM-DD).

| Field | Required | Description |
| - | - | - |
| `payer_id` | Yes | From payer search. |
| `provider_name` | Yes | Requesting provider or practice name. |
| `provider_npi` | Yes | 10-digit NPI of the requesting provider or practice. |
| `patient_id` | One of | A HealOS patient in your organization. |
| `member_id`, `first_name`, `last_name`, `date_of_birth` | One of | The member as the payer knows them. |
| `payer_name` | No | Stored on the check for your records. |
| `middle_name`, `gender` | No | Sent to the payer when given. |
| `service_type` | No | X12 service type code; defaults to `30` (health benefit plan coverage). |
| `insurance_type` | No | `primary` (default) or `secondary`. |
| `linked_check_id` | No | For a secondary check, the id of its primary check. |

```bash theme={null}
curl -X POST https://api.healos.ai/ext-api/v1/benefits/eligibility-checks \
  -H "X-API-Key: $HEALOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payer_id": "60054",
    "payer_name": "Aetna",
    "provider_name": "Riverside Family Medicine",
    "provider_npi": "1234567893",
    "member_id": "W123456789",
    "first_name": "Jordan",
    "last_name": "Rivera",
    "date_of_birth": "1984-03-12"
  }'
```

The call waits for the payer, which usually takes a few seconds; allow up to
a minute before giving up. A `200` means the payer answered; read `status` and
`result` to see whether coverage is active.

```json theme={null}
{
  "data": {
    "id": "3f2b9c1e-6a7d-4e1f-9b0a-2c4d5e6f7a8b",
    "status": "Active",
    "patient_name": "Jordan Rivera",
    "payer_name": "Aetna",
    "member_id": "W123456789",
    "patient_id": null,
    "insurance_type": "primary",
    "linked_check_id": null,
    "checked_at": "2026-10-20T10:00:00.000Z",
    "last_checked_at": "2026-10-20T10:00:00.000Z",
    "result": {
      "subscriber": { "firstName": "Jordan", "lastName": "Rivera", "memberId": "W123456789", "dateOfBirth": "1984-03-12" },
      "payer": { "id": "60054", "organizationName": "Aetna" },
      "plan": { "planNames": ["Choice POS II"], "groupNumber": "123456" },
      "benefits": [
        { "benefit": "Co-Payment", "services": "Professional (Physician) Visit - Office", "coverageLevel": "Individual", "inPlanNetwork": true, "amount": "25", "authRequired": false }
      ]
    }
  }
}
```

### What `result` contains

`result` is the payer's response, normalized:

* `subscriber` (and `dependents`): the member the payer matched.
* `payer` and `provider`: who answered and who asked.
* `plan`: plan names, group number and coverage dates.
* `benefits`: one entry per benefit, with the benefit type (active coverage,
  co-payment, co-insurance, deductible, out-of-pocket), coverage level,
  in/out of network, amount or percentage, time period, and whether prior
  authorization is required.
* `issues` / `warnings`: problems the payer reported, such as a member not found.

### Errors

| Status | `code` | Meaning |
| - | - | - |
| `400` | `VALIDATION_ERROR` | A required field is missing or malformed. |
| `404` | `PATIENT_NOT_FOUND`, `LINKED_CHECK_NOT_FOUND` | The patient or primary check isn't in your organization. |
| `422` | `PAYER_VALIDATION_ERROR` | The payer rejected the request (for example, an invalid member id). |
| `429` | | Over the rate limit (see below). |
| `502` / `504` | `UPSTREAM_ERROR`, `GATEWAY_TIMEOUT` | The payer or clearinghouse failed or didn't answer in time. Retry later. |
| `503` | `SERVICE_UNAVAILABLE` | Eligibility checking isn't available right now. |

## 3. Read past checks

```bash theme={null}
# One patient's checks, most recent first
curl "https://api.healos.ai/ext-api/v1/benefits/eligibility-checks?patient_id=481926357104938271" \
  -H "X-API-Key: $HEALOS_API_KEY"

# One check with its full result
curl https://api.healos.ai/ext-api/v1/benefits/eligibility-checks/3f2b9c1e-6a7d-4e1f-9b0a-2c4d5e6f7a8b \
  -H "X-API-Key: $HEALOS_API_KEY"
```

The list is paginated with `page` and `limit` (default 20, max 100).

## Limits and cost

Every eligibility check is a real request to the payer and is billable, so
`POST /benefits/eligibility-checks` is limited to **10 requests per minute per
API key**, on top of the general [rate limit](/rate-limiting). Reading past
checks and searching payers only count toward the general limit. Re-use a
recent check instead of re-running it when you can.


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