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 asAuthorization: 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:
What an entry tells you
namesare other names, never ids. Empty when there are none.statescarries two-letter codes orNATIONAL. A code can be one thestateparameter refuses, for exampleFM.programsis upper case, as the payer network reports it. It can carry a value theprogramsparameter does not accept yet, so do not validate it against a fixed list.
Searching and filtering
searchmatches names only:nameandnames, 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.statekeeps payers that operate in that state, and national payers.state=NATIONALkeeps only national payers. It takes the 50 states,DC,PR,GU,VI,ASandMP, in any letter case. A payer with an emptystatesnever passes a state filter.programskeeps payers that have any of the listed programs, comma-separated, in any letter case. A payer with an emptyprogramsnever passes a program filter, so if a search withprogramsfinds nothing, try it without.- The parameters combine: search, then state, then programs.
- No match is a
200with an emptypayers, not a404. - An unknown query parameter is a
400.
Paging
Paging is off unless you sendlimit, 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
400and tells you to restart: start again without a cursor. - A
cursorwithoutlimitis a400.
Resolving a stored payer id
- The match is exact. Aliases and other ids do not resolve, and letter case must match.
- A stored
payer_idcan stop resolving. A payer that leaves the payer network, or whose id changes, is gone under the old id after the next daily refresh. A404for 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.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}.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 twostatus fields, and they answer different questions.
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..: 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.
coinsuranceis a fraction, not a percentage.0.1is 10%.network_statusisIN NETWORKorOUT OF NETWORK.deductibleandout_of_pocketalways carry both scopes. Either may be allnull, 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.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 reportscoverages. 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:
subscriberis 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, andmember_idsits on whoever holds the policy.dependentis 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.confidenceis an assessment of how well the patient matched.
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.
coverages array and no recommendation: read coordination_of_benefits.classification and coordination_details.
coordination_detailsentries carry their own scope. An entry whoseservice_type_codesis dental or vision is a finding about that care, not about a medical claim. Read the scope before acting on a payer name inrelated_entities.- A payer rejection is a
200. The patient could not be matched, and the rejection is reported asstatusandstatus_reason— a completed check, not a failed request. A rejection carries nothing about coverage, and an answer carries nostatus. - 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.identificationis not the id you sent. Send60054and it can come back asAETNA-USH;payer_idechoes 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_servicedefaults to today. A future date is accepted, for a scheduled visit; a date more than two years old is a400.
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
subscriberis accepted. No service type, place of service, date of service or key of your own. subscriber.address.stateis required on every request, the SSN variant included. The SSN alone chooses the variant: supplying one selects the higher-matchingMBILU, omitting it selectsMBILUNOSSN. Whichever answered comes back asvariant.member_id_statusis always present.POSSIBLY_OUTDATEDmeans 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.planis a coverage summary, not a benefits answer.plan.activesays 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.
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.
- The body is
stateandpayer_id, and nothing else. Any other field is a400. in_network: falseis a complete answer, not a failure.- A payer id we do not hold is a
400, refused rather than answered asin_network: false. stateis a US state code. State input is case-insensitive. A two-letter code that is not a real state is a400.- Only
eligibility:readis needed. A token that holds onlyeligibility:writeis a403: 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.
