Skip to main content

Overview

Eligibility answers a different question per endpoint. Which one you want depends on what you already know: 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.
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:
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.
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:
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

  • 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:
  • 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

  • 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.
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.
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}.
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.
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:
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:

Cost shares

result.benefits is one entry per network.
  • 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.
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.
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.
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.
  • 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.
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:
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.