Coverages (270/271)

Eligibility is why this platform can answer "does this need prior authorization" at all - and the reason it does not need a curated rule list to do it.

#The finding

POST /v1/coverages accepts a procedureCode parameter, and the response carries NetworkBenefit.authorizationRequired and NetworkBenefit.authorizationRequiredUnknown. The payer answers, for this member, on this plan, right now.

Why this beats a curated list

It is the payer's own answer rather than our reading of their PDF; it is plan-specific, and the same CPT under the same payer differs by plan; it cannot go stale, so there is no verification queue and no expiry; and it needs no licence, no reviewer and no refresh pipeline.

#Three-valued, not boolean

javascript

authorizationRequiredUnknown === true  → 'unknown'
authorizationRequired === true         → 'required'
authorizationRequired === false        → 'not_required'
field absent entirely                  → 'unknown'

authorizationRequiredUnknown beats a bare false, and both fields can be present. A payer that says "we do not know" has not said "no", and preferring the false would manufacture a negative.

#Read all four network buckets

Availity fans every benefit into inNetwork, outOfNetwork, noNetwork and notApplicableNetwork. Reading only the first is the documented way integrations get this wrong, and for prior authorization it is worse than a misquote - in-network and out-of-network frequently disagree about whether authorization is needed, so collapsing them produces a confident wrong answer.

The canonical result keeps the split and rolls up conservatively: if any applicable network requires authorization, the answer is required, and the response says which networks disagree.

#The 200/202 trap

POST answers 200 OR 202

A client that always polls after POST makes a call it does not need and can race the delete. One that never polls silently loses every asynchronous answer. Both are easy to write and neither fails loudly, so the branch is explicit in the adapter.

#Coverage varies by payer

Not every payer populates the indicator - which is exactly why unknown is a first-class answer rather than an error. The mock adapter reproduces this deliberately: one payer answers fully across networks, one answers in-network only, one answers at service-type level but not per code, and one never populates it at all. A simulator where every payer answers cleanly would teach the platform that this rail is reliable, and it is not.

#It is a disclosure

An eligibility call discloses a member to a payer. It requires a PHI atom, it is audited with a purpose of use, and it is rate-limited - the risk is volume, not any single call. It is deliberately not gated: a human approving every lookup buys nothing and pushes the work back to the fax machine it replaced.