InsurancePlan

InsurancePlan is a FHIR resource that describes a health insurance product or plan, including plan-level benefits, costs, coverage area, and issuer details.

Flexpa API generates InsurancePlan resources for supported Medicare Advantage Part C Coverage resources only when the user consents through the Medicare.gov (CMS Blue Button) endpoint and the returned Coverage contains enough plan identifiers to match CMS Plan Benefit Package (PBP) reference data. This gives developers a structured view of the plan's benefit design even when the payer API only returns the member-specific Coverage.

InsurancePlan resources are generated from CMS reference data, not returned directly by the payer. They can be searched through the FHIR API and read by ID when available to the presented access token.

Generated InsurancePlan resources may include, when available from CMS PBP, landscape, and directory data:

Plan identity: plan name and type, MA or MA-PD coverage type, plan year, and CMS contract, plan, segment, and formulary IDs.
Carrier and geography: issuer names, parent organization, tax status, service contacts, service area, and Medicare Advantage region.
Quality and scale: overall, Part C, and Part D star ratings, contract enrollment, and contract effective date.
Drug coverage: formulary ID and Part D benefit category and type, such as enhanced alternative coverage.
Premiums and plan-level costs: monthly premiums, medical and drug deductibles, in-network and combined maximum out-of-pocket amounts, and Part D out-of-pocket threshold.
Covered benefits: CMS medical and supplemental benefit categories, including hospital, skilled nursing, emergency and urgent care, office visits, mental health and substance use, therapy, telehealth, dialysis, DME, ambulance and transportation, lab and imaging, preventive services, dental, vision, hearing, OTC, meals, acupuncture, and related benefits.
Benefit-level rules and costs: in-network and out-of-network availability, prior authorization or referral requirements, benefit dollar limits, copays, coinsurance, tiered ranges, and day-based cost sharing.
Conditional plan flags: SNP, LIS, benchmark, voluntary de minimis, sanctioned-plan, and related plan indicators when the plan qualifies.

FHIR API

https://api.flexpa.com/fhir/InsurancePlan

New to FHIR?

Intro to FHIR

FHIR, or Fast Healthcare Interoperability Resources, is a standard for exchanging healthcare information electronically

Read introduction →

#Availability

Flexpa currently generates InsurancePlan resources for supported Medicare Advantage Part C coverage returned by the Medicare.gov (CMS Blue Button) endpoint when the patient's Coverage can be resolved to a CMS PBP plan for the relevant plan year and service area.

A generated InsurancePlan is not guaranteed for every Coverage. If the Coverage is missing the necessary plan identifiers, plan year, or location details, the Coverage is still returned normally but no InsurancePlan is generated.

InsurancePlan generation depends on CMS PBP reference data being available for the plan year. The resource's meta.source points to the CMS PBP benefits data set used to create the resource.

Coverage reference extension

{
  "resourceType": "Coverage",
  "id": "0f713b1a-cc7e-4f08-8cb9-01cdd1923a8c",
  "extension": [
    {
      "url": "https://api.flexpa.com/fhir/StructureDefinition/insurance-plan-reference",
      "valueReference": {
        "reference": "InsurancePlan/2f6fa785-24bd-4ed5-a833-68ec53293f43"
      }
    }
  ]
}

#Schema

#Overview

The FHIR R4 InsurancePlan resource describes an insurance plan at the plan level. In Flexpa API, generated InsurancePlan resources use CMS PBP benefits data for plan design details and CMS Medicare Advantage landscape and directory data for related issuer, service area, and contact details when available.

Coverage and InsurancePlan answer different questions. Coverage is member-specific and describes a patient's enrollment or policy. InsurancePlan is plan-specific and describes the benefit design for the plan identified by the Coverage.

Elements

idid: The unique identifier for the generated InsurancePlan resource.
metaMeta: Metadata about the generated resource.
sourceuri: The CMS PBP benefits data source used to generate the resource, for example https://www.cms.gov/data-research/statistics-trends-and-reports/medicare-advantagepart-d-contract-and-enrollment-data/benefits-data/pbp-benefits-2026.
lastUpdatedinstant: The timestamp from the CMS PBP source record, when available.
extensionarray: Flexpa extensions for CMS plan context, when available from the matched reference data.
star-ratingExtension: CMS star ratings for the contract, such as overall, Part C, and Part D ratings.
ma-regionExtension: The Medicare Advantage region code and display name.
drug-benefitExtension: Part D benefit category and type, such as enhanced alternative coverage.
contract-enrollmentExtension: CMS contract enrollment count.
contract-effective-dateExtension: CMS contract effective date.
identifierarray: Plan identifiers from HPMS, including the contract, plan, and segment identifiers.
statuscode: The plan status derived from CMS PBP plan status fields. Generated values may include active, draft, or retired.
typearray: The plan type, such as Local PPO, HMO, or another CMS plan type.
namestring: The plan name from the CMS PBP source data.
periodPeriod: The plan year represented as a FHIR Period.
containedarray: Supporting resources embedded in the generated InsurancePlan.
OrganizationResource: The issuer or contract organization, including HPMS contract identifiers, name, aliases, parent organization, tax status, and address when available.
LocationResource: The matched plan service area or region name when available.
ownedByReference(Organization): The issuer or owning organization, when available.
administeredByReference(Organization): The administering organization, when available. For generated CMS PBP resources, this often references the contained issuer organization.
coverageAreaarray: The service area or geographic name for the matched plan, when available.
contactarray: Customer service or administrative contact details from CMS directory data, including phone, fax, email, and mailing address when available.
coveragearray: The categories of coverage and benefits described by the plan.
typeCodeableConcept: A broad coverage grouping, such as medical coverage.
benefitarray: Benefit categories from the CMS PBP benefits file. Each benefit may include HPMS category coding, Medicare-covered or supplemental category type, and a Flexpa benefit-offered extension indicating in-network, out-of-network, or combined availability when available.
planarray: Plan-level cost-sharing information, including general costs and benefit-specific costs.
typeCodeableConcept: The MA coverage type, such as MA-only or MA-PD.
generalCostarray: Plan-wide costs such as monthly premiums, Part C and Part D premiums, deductibles, in-network and combined maximum out-of-pocket amounts, and Part D thresholds when available.
specificCostarray: Benefit-specific costs grouped by CMS PBP benefit category.
categoryCodeableConcept: The CMS PBP benefit category for the cost group.
benefit.costarray: Copays, coinsurance, limits, applicability such as in-network or out-of-network, and qualifiers such as day ranges or visit types when available.

InsurancePlan Example

{
  "resourceType": "InsurancePlan",
  "id": "2f6fa785-24bd-4ed5-a833-68ec53293f43",
  "meta": {
    "source": "https://www.cms.gov/data-research/statistics-trends-and-reports/medicare-advantagepart-d-contract-and-enrollment-data/benefits-data/pbp-benefits-2026",
    "lastUpdated": "2025-08-05T09:11:32-04:00"
  },
  "extension": [
    {
      "url": "https://api.flexpa.com/fhir/StructureDefinition/star-rating",
      "extension": [
        {
          "url": "overall",
          "valueDecimal": 4.5
        },
        {
          "url": "partC",
          "valueDecimal": 4.5
        },
        {
          "url": "partD",
          "valueDecimal": 4
        }
      ]
    },
    {
      "url": "https://api.flexpa.com/fhir/StructureDefinition/drug-benefit",
      "extension": [
        {
          "url": "category",
          "valueString": "Enhanced"
        },
        {
          "url": "type",
          "valueString": "Enhanced Alternative"
        }
      ]
    }
  ],
  "identifier": [
    {
      "system": "https://hpms.cms.gov/contract-plan-segment",
      "value": "H5215-012-000"
    },
    {
      "system": "https://hpms.cms.gov/contract-plan-id",
      "value": "H5215_012"
    },
    {
      "system": "https://hpms.cms.gov/contract-plan-segment-id",
      "value": "H5215_012_0"
    }
  ],
  "status": "active",
  "type": [
    {
      "coding": [
        {
          "system": "https://hpms.cms.gov/plan-type",
          "code": "04",
          "display": "Local PPO"
        }
      ],
      "text": "Local PPO"
    }
  ],
  "name": "Network Health Zero (PPO)",
  "period": {
    "start": "2026-01-01",
    "end": "2026-12-31"
  },
  "contained": [
    {
      "resourceType": "Organization",
      "id": "issuer",
      "identifier": [
        {
          "system": "https://hpms.cms.gov/contract",
          "value": "H5215"
        }
      ],
      "name": "NETWORK HEALTH INSURANCE CORPORATION",
      "alias": ["Network Health Medicare Advantage Plans"],
      "partOf": {
        "display": "Network Health, Inc."
      }
    },
    {
      "resourceType": "Location",
      "id": "area",
      "name": "East Central Wisconsin"
    }
  ],
  "ownedBy": {
    "reference": "#issuer",
    "display": "Network Health Medicare Advantage Plans"
  },
  "administeredBy": {
    "reference": "#issuer",
    "display": "Network Health Medicare Advantage Plans"
  },
  "coverageArea": [
    {
      "reference": "#area",
      "display": "East Central Wisconsin"
    }
  ],
  "contact": [
    {
      "purpose": {
        "coding": [
          {
            "system": "http://terminology.hl7.org/CodeSystem/contactentity-type",
            "code": "ADMIN"
          }
        ]
      },
      "name": {
        "text": "Customer Service"
      },
      "telecom": [
        {
          "system": "phone",
          "value": "1-800-378-5234"
        }
      ]
    }
  ],
  "coverage": [
    {
      "type": {
        "text": "Medical"
      },
      "benefit": [
        {
          "type": {
            "coding": [
              {
                "system": "https://hpms.cms.gov/pbp-benefit-category",
                "code": "1a",
                "display": "Inpatient Hospital-Acute"
              },
              {
                "system": "https://hpms.cms.gov/pbp-category-type",
                "code": "1",
                "display": "Medicare-covered"
              }
            ]
          },
          "extension": [
            {
              "url": "https://api.flexpa.com/fhir/StructureDefinition/benefit-offered",
              "valueString": "in-and-out-of-network"
            }
          ]
        },
        {
          "type": {
            "coding": [
              {
                "system": "https://hpms.cms.gov/pbp-benefit-category",
                "code": "7a",
                "display": "Primary Care Physician Services"
              },
              {
                "system": "https://hpms.cms.gov/pbp-category-type",
                "code": "1",
                "display": "Medicare-covered"
              }
            ]
          }
        }
      ]
    }
  ],
  "plan": [
    {
      "identifier": [
        {
          "system": "https://hpms.cms.gov/contract-plan-segment",
          "value": "H5215-012-000"
        }
      ],
      "type": {
        "coding": [
          {
            "system": "https://hpms.cms.gov/ma-coverage-type",
            "code": "MA-PD",
            "display": "Medicare Advantage with prescription drug coverage"
          }
        ]
      },
      "generalCost": [
        {
          "type": {
            "text": "Monthly consolidated premium (Part C + D)"
          },
          "cost": {
            "value": 0,
            "currency": "USD"
          }
        },
        {
          "type": {
            "text": "In-network maximum out-of-pocket"
          },
          "cost": {
            "value": 3860,
            "currency": "USD"
          }
        }
      ],
      "specificCost": [
        {
          "category": {
            "coding": [
              {
                "system": "https://hpms.cms.gov/pbp-benefit-category",
                "code": "1a",
                "display": "Inpatient Hospital-Acute"
              }
            ]
          },
          "benefit": [
            {
              "type": {
                "coding": [
                  {
                    "system": "https://hpms.cms.gov/pbp-benefit-category",
                    "code": "1a",
                    "display": "Inpatient Hospital-Acute"
                  }
                ]
              },
              "cost": [
                {
                  "type": {
                    "text": "Copayment"
                  },
                  "applicability": {
                    "coding": [
                      {
                        "system": "http://terminology.hl7.org/CodeSystem/applicability",
                        "code": "in-network"
                      }
                    ]
                  },
                  "value": {
                    "value": 340,
                    "unit": "USD",
                    "system": "urn:iso:std:iso:4217",
                    "code": "USD"
                  },
                  "qualifiers": [
                    {
                      "text": "Days 1-7"
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

#API

GEThttps://api.flexpa.com/fhir/InsurancePlan

#Search

Search returns InsurancePlan resources available through the presented access token. For patient-scoped access, this means generated InsurancePlan resources associated with the authorized patient's matched Coverage.

Request headers

Authorizationstring: An Authorization: Bearer header value must be presented with a Patient Access Token or an Application Access Token.

Request

GET

/fhir/InsurancePlan

ACCESS_TOKEN=flexpa-link-access-token

curl "https://api.flexpa.com/fhir/InsurancePlan" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response

{
  "resourceType": "Bundle",
  "type": "searchset",
  "entry": [
    {
      "fullUrl": "https://api.flexpa.com/fhir/InsurancePlan/2f6fa785-24bd-4ed5-a833-68ec53293f43",
      "resource": {
        "resourceType": "InsurancePlan",
        "id": "2f6fa785-24bd-4ed5-a833-68ec53293f43",
        "status": "active",
        "name": "Network Health Zero (PPO)"
      }
    }
  ]
}

GEThttps://api.flexpa.com/fhir/InsurancePlan/:id

#Read

A read retrieves a single InsurancePlan by ID.

Request path parameters

idstring: The identifier of the InsurancePlan resource to retrieve.

Request

GET

/fhir/InsurancePlan/:id

ACCESS_TOKEN=flexpa-link-access-token

curl "https://api.flexpa.com/fhir/InsurancePlan/2f6fa785-24bd-4ed5-a833-68ec53293f43" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Coverage - member-specific enrollment and policy details. For generated InsurancePlan resources, the Coverage may include a Flexpa extension that references the generated plan.