> ## Documentation Index > Fetch the complete documentation index at: https://docs.haau3.com/llms.txt > Use this file to discover all available pages before exploring further. # Plan Benefits > What a Medicare Advantage or ACA Marketplace plan covers and what a member pays, as FHIR R4 InsurancePlan, read from the files CMS publishes. 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](/benefits/pharmacy) 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](/errors) 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](/terminology/terminology-service), the [Provider directory](/provider-directory/provider-directory), [Questionnaires](/questionnaires/questionnaires), [MedList](/medlist/medlist) and [Pharmacy Benefits](/benefits/pharmacy) 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 ```bash theme={null} 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: ```bash theme={null} 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`: ```bash theme={null} 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: ```bash theme={null} 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](https://fhir.haau3.com/SearchParameter-InsurancePlan-coverage-area-state.html) 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](https://fhir.haau3.com/SearchParameter-InsurancePlan-coverage-area-county.html) | | `type` | `mediadv` for Medicare Advantage or `qhp` for the Marketplace, from HL7's [insurance product type](https://terminology.hl7.org/CodeSystem-insurance-product-type.html) | | `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](https://fhir.haau3.com/SearchParameter-InsurancePlan-sold-to.html) | 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: ```bash theme={null} 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: ```bash theme={null} 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](https://fhir.haau3.com/OperationDefinition-InsurancePlan-in-network.html). An answer for a Medicare Advantage plan, with illustrative NPIs and directory records: ```json theme={null} { "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: ```json theme={null} { "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://fhir.haau3.com/StructureDefinition-haau3-insurance-plan.html), `https://haau3.com/fhir/StructureDefinition/haau3-insurance-plan`, whose page states every rule in full; and * the [SBC InsurancePlan profile](https://hl7.org/fhir/us/insurance-card/2.0.0-202609-ballot/StructureDefinition-sbc-insurance-plan.html) 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](/errors), 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.