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

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.

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

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

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.

{
  "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

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

Getting Started

Resources

Benefit Verification

Benefit Verification

1. Find the payer

2. Run a check

What `result` contains

Errors

3. Read past checks

Limits and cost

​Benefit Verification

​1. Find the payer

​2. Run a check

​What result contains

​Errors

​3. Read past checks

​Limits and cost

Benefit Verification

1. Find the payer

2. Run a check

What `result` contains

Errors

3. Read past checks

Limits and cost