Plan Benefits

Plan Benefits is one of haau3’s two Benefits services, the two halves of CMS’s Real-Time Benefits use case. Plan Benefits answers what a Medicare Advantage or Marketplace plan covers and what a member pays, from CMS’s plan files; Pharmacy Benefits answers what a medication would cost, in real time. Look up a Medicare Advantage or ACA Marketplace plan and get what it covers and what a member pays: its deductibles and out-of-pocket maximums, and the cost of core services such as a primary care visit, an emergency room visit or a hospital stay, in network and out of network. Each plan is a FHIR InsurancePlan, read from the files the Centers for Medicare & Medicaid Services (CMS) publishes, and each names the CMS release it was read from. This is plan design, the same for every member of a plan. Nothing about a member is sent here.

Service base

https://api.haau3.com/v1/fhir/r4

Everything hangs off that base, exactly as the FHIR REST specification describes. /v1/ is the version of the haau3 platform API contract, not a FHIR version. The FHIR release is r4, and every response says so:

Content-Type: application/fhir+json; fhirVersion=4.0

You never have to ask for a release. A plain Accept: application/fhir+json, or no Accept header at all, works fine. If you do ask for one we do not serve, or for a format other than JSON (in Accept or _format), you get a 406 rather than a silent substitution. Every error on this base is a FHIR OperationOutcome, including the 401 you get without a key and a 429, so a FHIR client only ever has one error shape to parse. Errors, limits and request ids lists the statuses every service shares.

The uppercase form /v1/fhir/R4/... redirects to the lowercase base with a 308, which preserves the method and body so a POST is not quietly turned into a GET.

The Terminology service, the Provider directory, Questionnaires, MedList and Pharmacy Benefits use this same base and the same CapabilityStatement.

What is served

Resource	Interactions
`InsurancePlan`	read; search by `identifier`, `name`, `coverage-area-state`, `coverage-area-county`, `type` and `sold-to`; the `$counties` and `$in-network` operations

GET [base]/metadata returns the CapabilityStatement. Its InsurancePlan entry names the release each program is serving, and anything missing from it is refused by name. Two programs are served:

Medicare Advantage, from CMS’s Plan Benefit Package (PBP) Benefits files for plan year 2027.
ACA Marketplace, from CMS’s Marketplace public use files for plan year 2026: the plans sold through HealthCare.gov.

Plans to try

Plan	Id	What it shows
AARP Medicare Advantage from UHC FL-0021 (PPO)	`H2406-013-000`	A Medicare Advantage PPO: copay ranges, hospital costs by day, care out of network
Aetna Medicare Select Extra (HMO-POS)	`H1609-028-000`	A Medicare Advantage HMO with a point-of-service option
UHC Bronze Essential ($0 Virtual Urgent Care)	`68398FL0030058-01`	A Marketplace bronze plan
AvMed Entrust Gold 125 (2026)	`19898FL0340001-01`	A Marketplace gold plan with two in-network tiers

Read a plan

curl -H "Authorization: Bearer $HAAU3_API_KEY" \
  "https://api.haau3.com/v1/fhir/r4/InsurancePlan/H2406-013-000"

A plan’s id is the id people know it by:

Medicare Advantage: CMS’s plan id, contract, plan and segment, with the segment written in three digits: H2406-013-000.
ACA Marketplace: the 17-character HIOS plan id, the 14-character standard component and a two-digit variant: 19898FL0340001-01. Each cost-sharing reduction variant of a plan is a plan of its own.

A plan the releases being served do not hold answers 404. So does a drug-only or dental-only plan, which is held but is not a medical plan, and the OperationOutcome says so.

Search

Find the plans sold in a state whose name contains some words:

curl -G -H "Authorization: Bearer $HAAU3_API_KEY" \
  --data-urlencode "coverage-area-state=FL" \
  --data-urlencode "name:contains=gold" \
  "https://api.haau3.com/v1/fhir/r4/InsurancePlan"

Find the plans a person can buy on their own in one county, Miami-Dade County, Florida, whose county code is 12086:

curl -G -H "Authorization: Bearer $HAAU3_API_KEY" \
  --data-urlencode "coverage-area-county=12086" \
  --data-urlencode "sold-to=individuals" \
  "https://api.haau3.com/v1/fhir/r4/InsurancePlan"

Find a plan by an id you already hold, in either form:

curl -G -H "Authorization: Bearer $HAAU3_API_KEY" \
  --data-urlencode "identifier=H2406_013_0" \
  "https://api.haau3.com/v1/fhir/r4/InsurancePlan"

Parameter	Matches
`identifier`	A plan id, as `value` or `system\|value`. Medicare Advantage: CMS’s plan id (`http://cms.gov/medicare/ma-plan-id`, `H2406-013-000`) or its bid_id (`https://haau3.com/fhir/NamingSystem/cms-ma-bid-id`, `H2406_013_0`). Marketplace: the HIOS plan id (`https://haau3.com/fhir/NamingSystem/hios-plan-id`, `19898FL0340001-01`) or the standard component (`https://haau3.com/fhir/NamingSystem/hios-standard-component-id`, `19898FL0340001`), which finds every variant
`name`	The start of the plan’s name, ignoring case and accents. `name:contains` matches anywhere in the name and `name:exact` the whole name exactly
`coverage-area-state`	A two-letter state code: the plans sold in that state. A search parameter the haau3 implementation guide defines, because in FHIR R4 `address-state` searches a plan’s contact address
`coverage-area-county`	A five-digit county code: the plans sold in that county, in whole or in part. Bare (`12086`) or with HL7’s system for county codes (`http://terminology.hl7.org/CodeSystem/FIPS64\|12086`). Defined by the haau3 implementation guide
`type`	`mediadv` for Medicare Advantage or `qhp` for the Marketplace, from HL7’s insurance product type
`sold-to`	`individuals` for the plans a person can buy on their own, or `employer-groups` for the plans sold only to employer and union groups (Medicare Advantage) or to small employers (Marketplace SHOP plans). Defined by the haau3 implementation guide

A search needs identifier, a form of name, coverage-area-state or coverage-area-county. type and sold-to narrow a search but are not one, so a search for every Marketplace plan is refused. Every other parameter is refused by name rather than ignored, so a search never quietly answers a different question than the one asked. A drug-only or dental-only plan is never in a name, state or county search; an identifier search that finds one answers no plan and an OperationOutcome entry saying why.

Where a plan is sold

CMS’s files say where a plan is sold county by county, so a county search lists the plans a person in that county can choose from, where a state search lists every plan sold anywhere in the state.

The county code is the county’s five-digit FIPS code: two digits for the state and three for the county. A code that names no county is refused.
Find a county’s code by its name with the $counties operation, which lists a state’s counties and their codes:
curl -G -H "Authorization: Bearer $HAAU3_API_KEY" \ --data-urlencode "state=FL" \ "https://api.haau3.com/v1/fhir/r4/InsurancePlan/\$counties"
It answers a Parameters resource with one county parameter per county, sorted by name. Its code part is a Coding holding the county code, with the county’s name as its display, and its state part the state’s code. The list is the U.S. Census Bureau’s 2020 county codes.
A plan sold in only part of a county is listed for the whole county. A county search cannot tell which part of the county a person lives in, so the plan’s own documents are the place to check.
Employer and union group plans. In many counties most Medicare Advantage plans are sold only to employer and union groups: in Miami-Dade County, 731 of the 832 in the 2027 files. Add sold-to=individuals to list only the plans a person can buy on their own.
A regional PPO is sold in every county of its region’s states.

Paging

Every result is the whole plan, sorted by name and then id, and every page states the total. _count sets the page size, from 1 to 50, and is 10 by default; a larger value is refused rather than quietly reduced. Follow the link with relation next to continue. Its cursor belongs to that one search. If the plans are updated while you page, for example when a new plan year is loaded, the next page answers 410 and you start the search again, so a search never skips or repeats a plan without saying so.

Whether a provider is in a plan’s network

$in-network asks the CMS National Provider Directory, for up to 20 providers, whether it lists each one in a network the plan names, for the plan’s year:

curl -G -H "Authorization: Bearer $HAAU3_API_KEY" \
  --data-urlencode "npi=1992700001" \
  --data-urlencode "npi=1992700002" \
  "https://api.haau3.com/v1/fhir/r4/InsurancePlan/H2406-013-000/\$in-network"

Send each NPI as its own npi parameter, or several separated by commas. An NPI is ten digits, a practitioner’s or an organization’s; a duplicate counts once. The answer is a Parameters resource:

plan, the plan checked;
data-date, the day the directory last reloaded its record of the plan;
one network per network checked, with its name and organizations-listed, the number of organizations the directory lists in it;
reason, when the plan has no network data;
directory, a Marketplace plan’s own provider directory;
one provider per NPI, in the order sent, with its status and, when it is listed, an evidence reference to each listing, a PractitionerRole or an OrganizationAffiliation you can read on this base;
source, the directory, whenever it was asked.

`status`	Meaning
`in-network`	The directory lists the provider in a network the plan names, for the plan’s year
`not-found`	The directory holds the provider, and none of the plan’s networks lists them
`not-in-directory`	The directory holds no practitioner or organization with this NPI
`no-network-data`	The directory holds no network data for this plan in its year, so no provider can be checked. `reason` says why: `marketplace` (a Marketplace plan’s insurer publishes its directory itself, given in `directory`), `plan-not-in-directory`, or `other-plan-year` (the directory holds the plan only for another year)

The status codes and the reason codes are defined in the haau3 implementation guide. An answer for a Medicare Advantage plan, with illustrative NPIs and directory records:

{
  "resourceType": "Parameters",
  "parameter": [
    { "name": "plan", "valueReference": { "reference": "InsurancePlan/H2406-013-000" } },
    { "name": "data-date", "valueDate": "2026-10-07" },
    { "name": "network", "part": [
      { "name": "network", "valueReference": { "reference": "Organization/Organization-example-network", "display": "Example Medicare Advantage Network" } },
      { "name": "organizations-listed", "valueInteger": 2618 } ] },
    { "name": "provider", "part": [
      { "name": "npi", "valueIdentifier": { "system": "http://hl7.org/fhir/sid/us-npi", "value": "1992700001" } },
      { "name": "status", "valueCoding": { "system": "https://haau3.com/fhir/CodeSystem/plan-benefits-network-status", "code": "in-network", "display": "In network" } },
      { "name": "evidence", "valueReference": { "reference": "PractitionerRole/PractitionerRole-example-role" } } ] },
    { "name": "provider", "part": [
      { "name": "npi", "valueIdentifier": { "system": "http://hl7.org/fhir/sid/us-npi", "value": "1992700002" } },
      { "name": "status", "valueCoding": { "system": "https://haau3.com/fhir/CodeSystem/plan-benefits-network-status", "code": "not-found", "display": "Not found in the network's listings" } } ] },
    { "name": "provider", "part": [
      { "name": "npi", "valueIdentifier": { "system": "http://hl7.org/fhir/sid/us-npi", "value": "1992700003" } },
      { "name": "status", "valueCoding": { "system": "https://haau3.com/fhir/CodeSystem/plan-benefits-network-status", "code": "not-in-directory", "display": "Not in the directory" } } ] },
    { "name": "source", "valueString": "CMS National Provider Directory: https://directory.cms.gov/fhir" }
  ]
}

And for a Marketplace plan, which the directory holds no network data for:

{
  "resourceType": "Parameters",
  "parameter": [
    { "name": "plan", "valueReference": { "reference": "InsurancePlan/19898FL0340001-01" } },
    { "name": "reason", "valueCodeableConcept": {
      "coding": [ { "system": "https://haau3.com/fhir/CodeSystem/plan-benefits-no-network-data-reason", "code": "marketplace", "display": "Marketplace plan" } ],
      "text": "A Marketplace plan's insurer publishes its provider directory itself, outside the CMS National Provider Directory, so the directory holds no network data for it. The plan's own directory is given beside this answer." } },
    { "name": "directory", "valueUrl": "https://avmed.healthsparq.com/healthsparq/public/#/one/insurerCode=AVMED_I&brandCode=AVMED" },
    { "name": "provider", "part": [
      { "name": "npi", "valueIdentifier": { "system": "http://hl7.org/fhir/sid/us-npi", "value": "1992700001" } },
      { "name": "status", "valueCoding": { "system": "https://haau3.com/fhir/CodeSystem/plan-benefits-network-status", "code": "no-network-data", "display": "No network data" } } ] }
  ]
}

What an answer can and cannot tell you:

A listing is not a contract. in-network says the directory lists the provider in the plan’s network. Whether the provider takes the plan for a given service is for the plan and the provider to confirm.
not-found never means out of network. The directory’s network data is incomplete: many networks list no one yet. A provider not found may still be in the network.
Only the plan’s own year counts. A plan’s network can change between years, so a directory record for another year is not used, and the answer says so.
organizations-listed counts organizations only. The directory cannot count the practitioners a network lists, so a network listing no organizations may still list practitioners.
How fresh an answer is. Each answer asks the directory, and the directory’s answers are kept for up to a day, or up to an hour when nothing was found.
All or nothing. A lookup that fails fails the whole answer, with a 502, 503 or 504, never a partial list.
Usage. Each call counts as one Plan Benefits request; the directory lookups it makes are not counted as Provider directory requests.

What a plan contains

Every plan conforms to two profiles, and names both in meta.profile:

the haau3 Plan Benefits profile, https://haau3.com/fhir/StructureDefinition/haau3-insurance-plan, whose page states every rule in full; and
the SBC InsurancePlan profile of the CARIN Digital Insurance Card guide, hl7.fhir.us.insurance-card version 2.0.0-ballot.

In short:

Identity and type. identifier carries the plan’s ids, type its program, plan.type its network type (HMO, PPO and so on) with CMS’s own words, and ownedBy the issuer.
The release. An extension names the CMS release, and for each of CMS’s files its address, the date CMS last changed it and its SHA-256, so you can fetch the same file and check it.
Where it is sold. The plan’s states, searched with coverage-area-state. Its counties are searched with coverage-area-county and are not in the resource.
Plan facts. What each program files about a plan, such as a Marketplace plan’s metal level or a Medicare Advantage plan’s special needs type.
Deductibles and out-of-pocket maximums, in plan.generalCost, each scoped to a network, to one member or a family, and to medical care, drugs or both.
Costs of services, in plan.specificCost, each coded twice: the SBC benefit category and CMS’s own reference. Services the SBC categories have no code for, such as lab tests, home health care, hospital observation and a visit to a nurse or physician assistant, are in an extension shaped the same way.

A cost the files do not state is never written as $0. It carries a code saying why it has no amount, such as “not in the public files” or “not stated”, and a data-absent reason in place of the number. Some Medicare Advantage plans charge Original Medicare’s own amount for a deductible or a hospital stay; those costs say so and carry Original Medicare’s published amounts, labelled with their year.

What the public files do not hold

Marketplace premiums. They depend on the member’s age and where they live, and are not in these files. A Marketplace plan’s premium says so.
Plans from the state-run exchanges, such as California’s and New York’s. Only plans sold through HealthCare.gov are in the Marketplace files.
Which providers are in a network. A plan names its provider directory; the files do not list the providers. $in-network asks the CMS National Provider Directory instead.
A member’s own numbers, such as the visits used or how much of the deductible is met.
Drug-only and dental-only plans, and pharmacy benefits.

Errors

Status	When
`400`	A parameter this service does not serve, a repeated parameter, a comma-separated list of values, a value of the wrong form, a county code that names no county, or a search with no criteria. One issue per offending parameter, naming it. For `$in-network`, a missing `npi`, an NPI that is not ten digits, or more than 20 NPIs
`404`	No plan with that id in the releases being served, or a plan that is not a medical plan. For `$counties`, a code that names no state, district or territory
`410`	A later page of a search, after the plans were updated
`502`	The plans could not be read, or, for `$in-network`, the directory failed a lookup or answered in a way that could not be read with confidence. Never reported as an empty result, a missing plan or a provider not found
`503`	No release is being served for the program a request needs, or, for a county search, where its plans are sold is not loaded yet. The `OperationOutcome` names the program. For `$in-network`, also the directory asking for fewer requests, which carries `Retry-After`
`504`	The plans, or for `$in-network` the directory, did not answer in time

The statuses every service shares, among them 401, 405, 406, 415, 429 and 500, are on Errors, limits and request ids, which also says when to send a 502, 503 or 504 again, including inside a batch.

Data source and licensing

The plans are read from public files the Centers for Medicare & Medicaid Services publishes, a work of the U.S. Government: the PBP Benefits files and the Health Insurance Exchange Public Use Files, its Service Area file included. County names and codes are the U.S. Census Bureau’s 2020 county codes, also a work of the U.S. Government. $in-network reads network listings from the CMS National Provider Directory when asked. CMS does not endorse haau3.

Get started

Build

Scheduling

Terminology

Provider directory

Questionnaires

Benefits

MedList

API reference

Service base

What is served

Plans to try

Read a plan

Search

Where a plan is sold

Paging

Whether a provider is in a plan’s network

What a plan contains

What the public files do not hold

Errors

Data source and licensing

​Service base

​What is served

​Plans to try

​Read a plan

​Search

​Where a plan is sold

​Paging

​Whether a provider is in a plan’s network

​What a plan contains

​What the public files do not hold

​Errors

​Data source and licensing

Service base

What is served

Plans to try

Read a plan

Search

Where a plan is sold

Paging

Whether a provider is in a plan’s network

What a plan contains

What the public files do not hold

Errors

Data source and licensing