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

# Eligibility

> Find the payer id to send, verify coverage, discover coverage you do not know about, coordinate benefits across payers, resolve a Medicare identifier, and check network status.

## Overview

Eligibility answers a different question per endpoint. Which one you want depends on what you already know:

| You know | You want to know | Call |
| - | - | - |
| The payer's name | Which `payer_id` identifies it? | `GET /v0.1/payers` |
| The payer and the member id | Is coverage active, and what does it cover? | `POST /v0.1/eligibility-verifications` |
| Only the patient's demographics | Which payers cover this patient at all? | `POST /v0.1/insurance-discoveries` |
| One payer the patient has | What else covers them, and who pays first? | `POST /v0.1/benefit-coordinations` |
| The patient is on Medicare | What is their Medicare Beneficiary Identifier? | `POST /v0.1/medicare-id-lookups` |
| A payer and a state | Does OpenLoop have contracted providers for that payer there? | `POST /v0.1/network-status` |

A benefit coordination and a Medicare ID lookup call the payer inside your request and return the answer. A verification and a discovery are accepted and worked out of band: you get an id, and you poll it. A network status check contacts no payer and answers inline. The payer directory contacts no payer either: it reads OpenLoop's daily copy of the payer network's list.

Each endpoint that asks a payer absorbs an identical repeat: it returns the stored answer with `deduplicated: true` rather than asking the payer again. The window is five minutes, except on a Medicare ID lookup, where it is four hours. An unknown field in a request body is a `400` on all of them, never a silently ignored value.

> [!NOTE]
>
> These endpoints appear in the reference but are **not yet enabled on the production edge**, and there is no committed date. The paths, request shapes and response shapes on this page are the final ones — but do not sequence a launch behind them, and confirm status with your OLH implementation contact.

## Authentication and organization

Send a service (M2M) access token as `Authorization: Bearer`. Every endpoint here takes the organization from the token's organization claim — there is no body field or query parameter for it. A token carrying no organization claim is a `401`.

Submitting requires the `eligibility:write` permission; the retrieve calls, a network status check and the payer directory require `eligibility:read`. A missing permission is a `403`.

## Responses

Every success is wrapped. `data` carries the operation's own response body, and `request_id` identifies the HTTP call:

```json theme={null}
{
  "data": { ... },
  "request_id": "3f2c9a1e-8b4d-4f6a-9c2e-1d5b7a8e4f3c"
}
```

`request_id` is the value to quote to support. It is never the id of a check: on submit-then-poll endpoints that is `data.id`, and it is what you poll.

## Finding a payer id

`GET /v0.1/payers` lists the payers whose `payer_id` a verification and a coordination check accept. Pick an entry and send its `payer_id` unchanged, character for character. `GET /v0.1/payers/{payer_id}` resolves a `payer_id` you stored back to its entry.

```bash theme={null}
curl -G 'https://api.openloophealth.com/v0.1/payers' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  --data-urlencode 'search=aetna' \
  --data-urlencode 'state=CA'
```

`data.payers` carries the matches, best match first, and `data.next_cursor` is `null` unless you page. An exact name ranks first, so an entry like this one leads the results:

```json theme={null}
{
  "payer_id": "60054",
  "name": "Aetna",
  "names": [
    "Aetna Affordable Health Choices (SM) SRC",
    "Aetna Insurance Company",
    "Aetna Medicare Advantage"
  ],
  "states": ["NATIONAL"],
  "eligibility_support": "SUPPORTED",
  "programs": []
}
```

> [!WARNING]
>
> **A listed payer says nothing about network status, contracting or billability.** It is a payer an eligibility check can be sent to, and nothing more. The directory is also not a list of the payer ids `POST /v0.1/network-status` accepts.

### What an entry tells you

| `eligibility_support` | What it means |
| - | - |
| `SUPPORTED` | The payer is expected to answer an eligibility check now |
| `ENROLLMENT_REQUIRED` | A check can fail until OpenLoop enrolls with the payer |
| `NOT_SUPPORTED` | A check will fail |

* **`names` are other names, never ids.** Empty when there are none.
* **`states` carries two-letter codes or `NATIONAL`.** A code can be one the `state` parameter refuses, for example `FM`.
* **`programs` is upper case, as the payer network reports it.** It can carry a value the `programs` parameter does not accept yet, so do not validate it against a fixed list.

### Searching and filtering

* **`search` matches names only**: `name` and `names`, never an id. Letter case does not matter. The best match ranks first: an exact name, then a name prefix, then an exact other name, then a substring of any name. Inside each of these, national payers come first. Only when none of these match does a typo-tolerant match run, ordered by how close the name is.
* **`state` keeps payers that operate in that state, and national payers.** `state=NATIONAL` keeps only national payers. It takes the 50 states, `DC`, `PR`, `GU`, `VI`, `AS` and `MP`, in any letter case. A payer with an empty `states` never passes a state filter.
* **`programs` keeps payers that have any of the listed programs**, comma-separated, in any letter case. A payer with an empty `programs` never passes a program filter, so if a search with `programs` finds nothing, try it without.
* **The parameters combine**: search, then state, then programs.
* **No match is a `200`** with an empty `payers`, not a `404`.
* **An unknown query parameter is a `400`.**

### Paging

Paging is off unless you send `limit`, from 1 to 200. Without it, every match comes back in one response. The full list is large: send `Accept-Encoding: gzip`, and responses of 1 KB or more come back compressed.

With `limit`, each page carries `next_cursor`, or `null` on the last page. Send it back as `cursor` with the same `search`, `state`, `programs` and `limit`:

```bash theme={null}
curl -G 'https://api.openloophealth.com/v0.1/payers' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  --data-urlencode 'search=aetna' \
  --data-urlencode 'limit=50' \
  --data-urlencode "cursor=$NEXT_CURSOR"
```

* **The cursor does not remember your parameters.** Change one between pages and you get the wrong page, not an error.
* **A cursor stops working when the directory refreshes.** The request answers `400` and tells you to restart: start again without a cursor.
* **A `cursor` without `limit` is a `400`.**

### Resolving a stored payer id

```bash theme={null}
curl 'https://api.openloophealth.com/v0.1/payers/60054' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

* **The match is exact.** Aliases and other ids do not resolve, and letter case must match.
* **A stored `payer_id` can stop resolving.** A payer that leaves the payer network, or whose id changes, is gone under the old id after the next daily refresh. A `404` for an id that used to resolve means exactly that: search for the payer again.

## Verifying coverage

**1. Submit the check**

`POST /v0.1/eligibility-verifications` with the subscriber, the payer, and the state the encounter takes place in. Take `payer_id` from the [payer directory](#finding-a-payer-id).

```bash theme={null}
curl -X POST 'https://api.openloophealth.com/v0.1/eligibility-verifications' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "subscriber": {
      "first_name": "Phillip",
      "last_name": "Mozee",
      "date_of_birth": "1957-11-10",
      "member_id": "H77465998",
      "address": { "state": "WI" }
    },
    "payer_id": "61101",
    "date_of_service": "2026-08-28"
  }'
```

Omit `date_of_service` to ask whether coverage is active today. Send a past or future date for an earlier encounter or a scheduled visit; the answer is the coverage in force on the date you asked about.

> [!TIP]
>
> A `202` returns `data.id`. Store it — it is the only way to reach the answer. There is no poll interval on this response; your first poll is never refused.

**2. Handle a deduplicated submission**

An identical check from your organization inside **five minutes** answers `200` instead of `202`, carrying the original `id` and `deduplicated: true`. No payer was asked.

Poll the `id` you were given. Do not resubmit — the same request matches the same window again.

**3. Poll for the answer**

`GET /v0.1/eligibility-verifications/{id}`.

```bash theme={null}
curl -G 'https://api.openloophealth.com/v0.1/eligibility-verifications/1c7e9b40-5f2a-4d18-9d3e-8a4c2f6b1e07' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

A pending read carries `retry_after_ms` — wait that long before asking again, or the next poll answers `429`.

A check is kept for 48 hours; after that the id returns `404`.

### Read both statuses

A verification carries two `status` fields, and they answer different questions.

| Field | Question it answers |
| - | - |
| `data.status` | Did the check run? `PENDING`, `COMPLETE`, `TIMEOUT` or `FAILED` |
| `data.result.status` | What did the payer say? `complete.eligible`, `complete.ineligible`, or an `error.*` value |

```json theme={null}
{
  "data": {
    "id": "1c7e9b40-5f2a-4d18-9d3e-8a4c2f6b1e07",
    "status": "COMPLETE",
    "result": {
      "status": "error.member.name",
      "status_reason": "error.member.name",
      "benefits": []
    }
  },
  "request_id": "3f2c9a1e-8b4d-4f6a-9c2e-1d5b7a8e4f3c"
}
```

> [!WARNING]
>
> That check succeeded. `status: COMPLETE` means an answer came back and was stored; the payer's answer was that it could not match the patient on the name that was sent. A caller that only reads the outer `status` will report active coverage it never received — branch on `result.status`.

Only `complete.eligible` and `complete.ineligible` are statements about coverage. Every `error.*` value is the payer declining to answer the question as asked, and it names what it could not match:

| `result.status` | What it means | Yours to fix? |
| - | - | - |
| `error.member.id` | The member id was rejected | Yes — correct it and submit a new check |
| `error.member.dob` | The date of birth did not match | Yes |
| `error.member.name` | The name did not match | Yes |
| `error.member.data` | Another submitted demographic was missing or unusable | Yes |
| `error.member.not_found` | The payer has no such member | No — the member is not at that payer |
| `error.provider` | **OpenLoop's** provider identity was rejected or is not enrolled with that payer | No — contact us |
| `error.payer` | A payer-level rejection: out of network, or not set up for this transaction | No |
| `error.request` | The payer refused the transmission before processing it | Yes — resubmitting may succeed |

> [!NOTE]
>
> **`complete.ineligible` is a payer's statement about coverage, not a clinical decision.** A clinician declining a patient after intake is a different thing entirely, and neither outcome implies the other. A patient can be `complete.eligible` here and still not be approved for care, and the reverse.

**Branch on the family, not the whole string.** Read the prefix before the first `.`: an unrecognised `error.*` value can appear, and should be treated as a match failure.

`result.status_reason` carries a finer code for the same verdict. On `complete.ineligible` an absent one means the payer gave a reason we have no code for — never that coverage is fine.

The outer statuses mean:

| `data.status` | What happened | What to do |
| - | - | - |
| `PENDING` | Still running | Poll again after `retry_after_ms` |
| `COMPLETE` | An answer was stored in `result` | Read `result.status` |
| `TIMEOUT` | Nothing usable arrived in time | Resubmit; it may do better |
| `FAILED` | An answer arrived and is unusable | Read `reason`. Resubmitting the same check cannot change it |

### Cost shares

`result.benefits` is **one entry per network**.

```json theme={null}
{
  "network_status": "IN NETWORK",
  "copay": 25,
  "coinsurance": 0.1,
  "deductible": {
    "individual": { "total": 1500, "remaining": 400 },
    "family": { "total": null, "remaining": null }
  },
  "out_of_pocket": {
    "individual": { "total": 6000, "remaining": 4900 },
    "family": { "total": null, "remaining": null }
  }
}
```

* **`coinsurance` is a fraction, not a percentage.** `0.1` is 10%.
* **`network_status`** is `IN NETWORK` or `OUT OF NETWORK`.
* **`deductible` and `out_of_pocket` always carry both scopes.** Either may be all `null`, which is the payer not reporting it — not zero.
* **A network the payer quoted nothing for has no entry.** An empty array is a real answer, and it is what you get on any non-eligible verdict.

### What a verification does not do

A check here is answered to you and nothing else: it writes to no OpenLoop clinical record and starts no scheduling. If you need the result in a patient's chart, that is a separate integration.

### `state` is the state of care

`subscriber.address.state` must be the state the encounter takes place in, not the patient's mailing address: it selects the OpenLoop entity that submits the inquiry. No provider identifier is accepted — you cannot submit the check as yourself.

A discovery and a Medicare ID lookup take the same field, nested the same way. A coordination check takes no state. A network status check takes `state` at the top level of the body, with no patient around it.

> [!NOTE]
>
> On a verification and a Medicare ID lookup, `address` accepts `state` and nothing else — sending `zip` or `city` there is a `400`. Only a discovery takes the rest of the address, where it improves matching.

## Discovering unknown coverage

Use a discovery when you have demographics and no payer. It is queued rather than answered inline.

```bash theme={null}
curl -X POST 'https://api.openloophealth.com/v0.1/insurance-discoveries' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "subscriber": {
      "first_name": "Erica",
      "last_name": "McDaniel",
      "date_of_birth": "1991-04-27",
      "address": { "state": "WI", "zip": "53703" }
    },
    "date_of_service": "2026-06-23"
  }'
```

Then poll `GET /v0.1/insurance-discoveries/{id}` until `status` is terminal, honouring `retry_after_ms` the same way a verification does. `coverages_found: 0` is a normal answer — the patient may have none to find.

`date_of_service` must be `YYYY-MM-DD`; anything else is a `400`. It decides which cost shares the retrieve call reports as in force. Omit it and the date is chosen for you.

### What a coverage looks like

A finished discovery reports `coverages`. Each entry carries the same `payer` / `plan` / `group` / `benefits` fields a verification's `result` carries, with the same meanings, so one parser reads both. Two extra fields appear here because a discovery is a search rather than a question about one policy:

* **`subscriber` is the policyholder on the coverage that was found**, who is not always the patient: a discovery turns up policies held by a spouse or a parent, and `member_id` sits on whoever holds the policy.
* **`dependent` is present when the payer matched the patient as a dependent** on that policy. Its absence means the patient is the subscriber — which is the difference between billing under their own member id and someone else's.
* `confidence` is an assessment of how well the patient matched.

A discovery the payer network could not answer reports `failure_status` and `failure_reason` instead, drawn from the same vocabulary a verification's `status` and `status_reason` use. **The two shapes never mix**: an answered discovery carries no failure, and a refused one carries nothing about coverage.

`subscriber.ssn` is optional and improves matching.

## Coordinating benefits

`POST /v0.1/benefit-coordinations` asks a payer you already know the patient has what other coverage they have, and which coverage pays first. It answers inline.

```bash theme={null}
curl -X POST 'https://api.openloophealth.com/v0.1/benefit-coordinations' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "subscriber": {
      "first_name": "Phillip",
      "last_name": "Mozee",
      "date_of_birth": "1957-11-10",
      "member_id": "H77465998"
    },
    "payer_id": "60054",
    "date_of_service": "2026-08-10"
  }'
```

The response carries the payer's own verdict. There is no verdict field of ours, no `coverages` array and no recommendation: read `coordination_of_benefits.classification` and `coordination_details`.

* **`coordination_details` entries carry their own scope.** An entry whose `service_type_codes` is dental or vision is a finding about that care, not about a medical claim. Read the scope before acting on a payer name in `related_entities`.
* **A payer rejection is a `200`.** The patient could not be matched, and the rejection is reported as `status` and `status_reason` — a completed check, not a failed request. A rejection carries nothing about coverage, and an answer carries no `status`.
* **A payer that does not answer coordination checks is a `400`**, refused before any payer is contacted. Original Medicare and the Part B MACs are in that group. Nothing is stored, so you may ask again as soon as the payer becomes supported.
* **`payer.identification` is not the id you sent.** Send `60054` and it can come back as `AETNA-USH`; `payer_id` echoes your own value.
* **A repeat inside five minutes returns the stored answer** with `deduplicated: true`. Two identical requests sent at the same moment are two checks.
* `date_of_service` defaults to today. A future date is accepted, for a scheduled visit; a date more than two years old is a `400`.

### Who goes in `subscriber`

Send `dependent` **only** for a patient covered under someone else's policy who has no member identifier of their own, and put the policyholder in `subscriber`. A patient who holds their own member identifier goes in `subscriber` and `dependent` is omitted. Getting the two the wrong way round produces a payer rejection rather than a wrong answer.

Two dependents on one policy are two different questions, and are never served one another's answer.

### SSNs here

`subscriber.ssn` is an alternative to `member_id`, not an addition to it: at least one of the two is required. It is nine digits with **no separators**, unlike `subscriber.ssn` on a Medicare ID lookup, which also accepts hyphens.

## Resolving a Medicare identifier

`POST /v0.1/medicare-id-lookups` resolves a Medicare Beneficiary Identifier from demographics and answers inline. There is nothing to poll; the identifier is at `data.member_id`.

```bash theme={null}
curl -X POST 'https://api.openloophealth.com/v0.1/medicare-id-lookups' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "subscriber": {
      "first_name": "Jane",
      "last_name": "Doe",
      "suffix": "Jr",
      "date_of_birth": "1955-05-05",
      "ssn": "123-45-6789",
      "address": { "state": "WI" }
    }
  }'
```

* **Nothing outside `subscriber` is accepted.** No service type, place of service, date of service or key of your own.
* **`subscriber.address.state` is required on every request**, the SSN variant included. The SSN alone chooses the variant: supplying one selects the higher-matching `MBILU`, omitting it selects `MBILUNOSSN`. Whichever answered comes back as `variant`.
* **`member_id_status` is always present.** `POSSIBLY_OUTDATED` means the payer returned the identifier alongside a rotation warning: it is still the best available value, and there is no way to obtain the newer one.
* **`plan` is a coverage summary, not a benefits answer.** `plan.active` says whether the plan reports active coverage. Use a verification if you need cost shares.
* **A repeat inside four hours returns the stored answer** with `deduplicated: true`.

A `404` means no match, and no match is a normal outcome rather than a fault. It covers a payer no-match, a mismatch on date of birth or name, and Medicare Advantage patients, for whom no identifier exists to find. Retrying an unchanged `404` returns `404` again.

## Checking network status

`POST /v0.1/network-status` asks whether OpenLoop holds contracted, credentialed providers for a payer in a state, within your organization. It answers inline, and there is nothing to poll.

```bash theme={null}
curl -X POST 'https://api.openloophealth.com/v0.1/network-status' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "state": "CA",
    "payer_id": "60054"
  }'
```

```json theme={null}
{
  "data": {
    "in_network": true
  },
  "request_id": "3f2c9a1e-8b4d-4f6a-9c2e-1d5b7a8e4f3c"
}
```

> [!WARNING]
>
> **`in_network` is not the `network_status` on a verification.** A verification's `result.benefits[].network_status` is the payer's own classification of a benefit it quoted for one patient. This endpoint answers OpenLoop's contracting position for the payer, and it takes no patient. The two can disagree, and neither is derived from the other.

* **The body is `state` and `payer_id`, and nothing else.** Any other field is a `400`.
* **`in_network: false` is a complete answer, not a failure.**
* **A payer id we do not hold is a `400`**, refused rather than answered as `in_network: false`.
* **`state` is a US state code.** State input is case-insensitive. A two-letter code that is not a real state is a `400`.
* **Only `eligibility:read` is needed.** A token that holds only `eligibility:write` is a `403`: the check contacts no payer and bills nothing.

## Errors

Every failure returns the platform error shape:

```json theme={null}
{
  "error": {
    "message": "This payer does not answer coordination of benefits checks",
    "error_code": "BAD_REQUEST"
  },
  "request_id": "3f2c9a1e-8b4d-4f6a-9c2e-1d5b7a8e4f3c"
}
```

| Status | `error_code` | What to do |
| - | - | - |
| 400 | `BAD_REQUEST` | The body or a query parameter failed validation, a directory cursor expired, the organization could not be resolved, or the request itself was refused. Read `error.message` |
| 401 | `AUTHENTICATION_ERROR` | The token is missing, invalid, or carries no organization claim |
| 403 | `FORBIDDEN` | A missing `eligibility:read` / `eligibility:write` permission |
| 404 | `NOT_FOUND` | For a retrieve: an unknown id, an id belonging to another organization, or a check older than 48 hours. For a Medicare ID lookup: no beneficiary matched. For a payer lookup: no entry has that `payer_id` |
| 429 | `TOO_MANY_REQUESTS` | You polled inside `retry_after_ms`, or the request was throttled. Back off and retry |
| 502 | `NETWORK_ERROR` | The payer directory has no data yet. Try again later |
| 504 | `REQUEST_TIMEOUT` | The request timed out before an answer arrived. Try again |
| 500 | `UNHANDLED_EXCEPTION` | Something failed that names no cause. The message is fixed prose — quote `request_id` to support |

Branch on the statuses you act on and let everything else fall into one failure path, quoting `request_id` when you report it.

There is no `error.details` on these endpoints, unlike the scheduling ones: a `400` names what failed in `error.message` as prose, not which field.


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