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 plans, as well as for specific lines of business for the following payers:

UnitedHealthcare, the insurance arm of UnitedHealth Group and the largest health insurer in the United States.
Aetna, a national health insurer and a CVS Health company.
Cigna, the health benefits business of The Cigna Group, operating as Cigna Healthcare.
Health Care Service Corporation (HCSC), the largest customer-owned health insurer in the United States, operating the Blue Cross and Blue Shield plans of Illinois, Montana, New Mexico, Oklahoma, and Texas.

For Part C plans, plan design comes from CMS Plan Benefit Package (PBP) reference data when the user consents through the Medicare.gov (CMS Blue Button) endpoint and the returned Coverage contains enough plan identifiers to match a PBP plan. For UHC, Aetna, Cigna and HCSC plan design comes from the payer's own data.

The InsurancePlan resource gives a structured view of the plan's benefit design even when the payer API only returns the member-specific Coverage.

A generated InsurancePlan describes the product, not the member. Everyone enrolled in the same plan and coverage line shares one InsurancePlan, and each of their Coverage resources carries an insurance-plan-reference extension pointing at it. Member-specific amounts, such as how much of a deductible has been met, are not part of the plan.

InsurancePlan resources are not returned by Patient/$everything. That operation returns the resources in a patient's compartment, and an InsurancePlan describes a product rather than a person, so it is never in one. Search for it with GET /fhir/InsurancePlan, or read it by ID using the insurance-plan-reference extension on the patient's Coverage.

What a plan carries depends on what its source publishes. The coverage by source tables below list every data point, its FHIR path, and which sources populate it.

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

Medicare Advantage Part C InsurancePlans are generated when the patient's Coverage can be resolved to a CMS PBP plan for the relevant plan year and service area.

For certain UnitedHealthcare, Aetna, Cigna, and HCSC lines of business, a plan is generated per coverage line when the payer publishes plan design for it.

Source	Medical	Drug	Dental
Medicare Advantage	Yes	Formulary only	Yes, as a benefit
UnitedHealthcare	Yes	Yes	Yes
Aetna	Yes	Yes	Yes
Cigna	Yes	Yes	Yes
HCSC	Yes	Yes	No

A generated InsurancePlan is not guaranteed for every Coverage. If the plan identifiers, plan year, location details, or payer benefit design are missing, the Coverage is still returned normally and no InsurancePlan is generated.

Medicare Advantage InsurancePlan generation depends on the user consenting through Flexpa's connection to the CMS Blue Button API. To get both claims and plan design information, the member should consent with both their Medicare Advantage payer and the CMS Blue Button API. Flexpa supports both connections within the same Consent flow.

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.

Which fields are present depends on the source, and the coverage by source tables below give the breakdown.

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 source the resource was generated from. Medicare Advantage plans point at the CMS PBP benefits data set, for example https://www.cms.gov/data-research/statistics-trends-and-reports/medicare-advantagepart-d-contract-and-enrollment-data/benefits-data/pbp-benefits-2026. The other four plans point at the payer endpoint.
lastUpdatedinstant: The timestamp of the source record, when available.
extensionarray: Flexpa extensions carrying plan context FHIR has no element for. There are 76 of them and the coverage by source tables list every one, with the path that reads it and which sources publish it, so they are not repeated here.
identifierarray: Plan identifiers from the source, each under a system naming the payer that issued it. Which identifier is which gives the system for every one.
statuscode: The plan status. Generated values may include active, draft, or retired. Derived from CMS PBP plan status fields for Medicare Advantage, and from the coverage status the payer reports for the four other payers.
typearray: The kind of plan, always a single concept. Medicare Advantage plans carry the CMS plan type, such as Local PPO or HMO. The four other payers carry the coverage line the plan covers, coded twice in one concept so it can be read from either vocabulary: HIP and medical, DRUGPOL and drug, or DENTAL and dental.
namestring: The plan name as published by the source. Absent when the source publishes no official product name, which is the case for UnitedHealthcare drug plans. Aetna publishes no plan.type, so on an Aetna plan the name is the only element a product or network model could appear in.
periodPeriod: The period the plan is effective for, as a FHIR Period. For Medicare Advantage this is the plan year. Far-future end dates that a payer uses to mean "no end date" are suppressed rather than published.
containedarray: Supporting resources embedded in the generated InsurancePlan.
OrganizationResource: For Medicare Advantage, the issuer or contract organization, including HPMS contract identifiers, name, aliases, parent organization, tax status, and address when available. For all other plans, the employer or organization sponsoring the plan, where the payer names one. UnitedHealthcare drug plans also carry the pharmacy benefit manager.
LocationResource: Medicare Advantage only. The matched plan service area or region name when available.
ownedByReference(Organization): The organization that underwrites the risk, when available. For Medicare Advantage this is the issuer. For the four other payers it is the entity carrying the risk, which may be the insurer or the employer depending on the funding arrangement.
administeredByReference(Organization): The administering organization, when available. For Medicare Advantage this often references the contained issuer organization. For all other plans it is the payer, or the pharmacy benefit manager on UnitedHealthcare drug plans.
coverageAreaarray: Medicare Advantage only. The service area or geographic name for the matched plan, when available.
contactarray: Medicare Advantage only. 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: The benefits the plan covers, each with a label and any dollar or visit limit. For Medicare Advantage these are benefit categories from the CMS PBP benefits file, and each 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. For all other plans these are the payer's own service labels. UnitedHealthcare adds a benefit-document-name extension naming the plan document each figure came from, and Cigna adds the payer's own service code in type.coding, since Cigna names services by code alone. A benefit with no published price still appears here, so a covered service is never dropped for lack of a number.
planarray: Plan-level cost-sharing information, including general costs and benefit-specific costs.
typeCodeableConcept: Two unrelated facts share this element. Medicare Advantage puts the MA coverage type here, MA-only or MA-PD, which reports whether the plan includes Part D. Everyone else puts the product or provider network: Cigna as a coding, HCSC and UnitedHealthcare dental plans as text. Not set on UnitedHealthcare medical or drug plans, and never set by Aetna, whose product is in name. The coverage line is on type at the top level, not here.
generalCostarray: Plan-wide costs as Money. For Medicare Advantage, monthly premiums, Part C and Part D premiums, deductibles, in-network and combined maximum out-of-pocket amounts, and Part D thresholds when available, each named in type.text alone. For the four other payers, deductibles and out-of-pocket maximums, reported separately for individual and family and for in-network and out-of-network, and coded in coverage-copay-type so one query finds them across payers.
specificCostarray: Benefit-specific costs, grouped by category. Medicare Advantage groups them by CMS PBP benefit category. The four other payers emit one group per coverage line, holding every priced benefit on that line.
categoryCodeableConcept: The category the cost group covers. Medicare Advantage uses the CMS PBP benefit category. The four other payers use the coverage line, coded in insurance-plan-type.
benefit.costarray: Copays, coinsurance, and deductibles for the benefit. Each cost states whether it applies in-network or out-of-network, and carries its amount as a Quantity: US dollars for a flat fee, or a percentage for coinsurance. Qualifiers add the conditions attached to the cost: day ranges or visit types for Medicare Advantage, a minimum charge, a supply length, or applying only after the deductible is met for UnitedHealthcare, and the setting, the provider type, or an age band for Cigna.

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"
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

#Coverage by source

This section helps explain which data points a plan carries, where on the InsurancePlan resource it can be found, and which payers publish it. MA is Medicare Advantage, UHC is UnitedHealthcare, HCSC is Health Care Service Corporation. [FLEXPA] stands in for https://api.flexpa.com/fhir/StructureDefinition, the base Flexpa extension URL.

#Plan identity

Data point	Where to look	MA	UHC	Aetna	Cigna	HCSC
What the plan is called	`name`	✓	✓	✓	✓	✓
Any other name it goes by	`alias`	✓	✓	—	—	✓
Whether it covers medical, dental or drug	`type.coding.where(system = 'http://terminology.hl7.org/CodeSystem/v3-ActCode' or system = 'http://terminology.hl7.org/CodeSystem/insurance-plan-type')`	—	✓	✓	✓	✓
Which product or provider network it runs on	`plan.type.coding.where(system = 'https://www.cigna.com/productTypeCode' or system = 'https://www.cigna.com/dentalPlanType')` for Cigna, `plan.type.text` for HCSC and UHC, `name` field for Aetna	—	text, dental only	name	code	text
Whether the plan is still in force	`status`	✓	✓	✓	✓	✓
Which plan year the design describes	`period.start`, `period.end`	✓	✓	✓	✓	✓
The payer's own reference number for the plan	`identifier`, which one is which	✓	✓	✓	✓	✓
Which kind of Medicare Advantage plan it is, such as Local PPO	`type.coding.where(system = 'https://hpms.cms.gov/plan-type')`	✓	—	—	—	—
Whether a Medicare Advantage plan includes Part D drug coverage	`plan.type.coding.where(system = 'https://hpms.cms.gov/ma-coverage-type')`	✓	—	—	—	—

#Which identifier is which

The identifier field can hold several different business identifiers, so pick one by its system. HCSC's host varies with the Blue Cross entity servicing the member, bcbsil.com for Illinois and its siblings elsewhere.

Source	System	What the value is
Cigna	`https://www.cigna.com/groupId`	the employer group the policy belongs to
Cigna	`https://www.cigna.com/accountNumber`	Cigna's account number for that group
UnitedHealthcare	`https://www.uhc.com/policyNumber`	the policy number
UnitedHealthcare	`https://www.uhc.com/groupNumber`	the employer group number
UnitedHealthcare	`https://www.uhc.com/benefitPlanId`	United's id for the benefit plan
UnitedHealthcare	`https://www.uhc.com/planVariationCode`	which variation of that plan the group bought
UnitedHealthcare	`https://www.uhc.com/reportingCode`	United's internal reporting code
UnitedHealthcare	`https://www.uhc.com/obligorId`, `https://www.uhc.com/marketNumber`	who carries the obligation, and the market the plan is sold in
Aetna	`https://sources.aetna.com/groupId`, `https://sources.aetna.com/planSponsorId`	the employer group, and Aetna's id for the sponsor
HCSC	`https://www.bcbsil.com/groupNumber`, `.../groupSectionNumber`, `.../bluestarAccountNumber`	the group, the section within it, and the account
HCSC	`https://www.bcbsil.com/planType`, `.../productType`	HCSC's own plan and product codes
HCSC	`https://www.bcbsil.com/rxBin`, `.../rxPCN`	the pharmacy routing numbers a pharmacist needs to bill the plan
Medicare Advantage	`https://hpms.cms.gov/formulary-id`	the CMS formulary the drug plan uses
Medicare Advantage	`https://hpms.cms.gov/contract-plan-id` and its siblings	the CMS contract, plan and segment identifiers
Every source	`[PAYER_ENDPOINT]/InsurancePlan/SourceResourceId`	the id Flexpa minted before the resource was stored, added by Flexpa rather than by the payer

Data point	Where to look	MA	UHC	Aetna	Cigna	HCSC
Administering payer	`administeredBy.reference`	✓	✓	✓	✓	✓
Entity underwriting the risk	`ownedBy.reference`	✓	✓	✓	—	✓
Entity (often the employer) the policy is written for	`extension.where(url = '[FLEXPA]/plan-sponsor').valueReference.reference`	—	✓	—	✓	—
Service contacts	`contact`	✓	—	—	✓	—
Service area	`coverageArea`	✓	—	—	—	—

#Plan-level costs

Data point	Where to look	MA	UHC	Aetna	Cigna	HCSC
Deductible	`plan.generalCost.where(type.coding.where(system = 'http://terminology.hl7.org/CodeSystem/coverage-copay-type').code = 'deductible')` where the cost is coded, `plan.generalCost.where(type.text.contains('deductible'))` where it is text only	text	code	code	code	code
Out-of-pocket maximum	`plan.generalCost.where(type.coding.where(system = 'http://terminology.hl7.org/CodeSystem/coverage-copay-type').code = 'maxoutofpocket')` where the cost is coded, `plan.generalCost.where(type.text.contains('maximum out-of-pocket'))` where it is text only	text	code	code	code	code
Amount of a plan-level cost	`plan.generalCost.cost.value`, `plan.generalCost.cost.currency`	✓	✓	✓	✓	✓
Individual or family	`plan.generalCost.extension.where(url = '[FLEXPA]/cost-scope').valueCode`	—	✓	✓	✓	✓
In-network or out-of-network	`plan.generalCost.extension.where(url = '[FLEXPA]/cost-network').valueCoding.code`	—	✓	✓	✓	✓
CARIN Digital Insurance Card code for the same cost	`plan.generalCost.type.coding.where(system = 'http://hl7.org/fhir/us/insurance-card/CodeSystem/C4DICExtendedCopayTypeCS').code`	—	✓	✓	✓	✓
The payer's own wording for the cost	`plan.generalCost.extension.where(url = '[FLEXPA]/source-label').valueString`	—	—	✓	—	✓
An amount the payer states in words rather than as a number	`plan.generalCost.comment`	✓	✓	—	—	✓
Monthly premium	`plan.generalCost.where(type.text.contains('premium'))`	✓	—	—	—	—
Part D out-of-pocket threshold	`plan.generalCost.where(type.text = 'Part D out-of-pocket threshold')`	✓	—	—	—	—

#Covered benefits

Data point	Where to look	MA	UHC	Aetna	Cigna	HCSC
Benefit name	`coverage.benefit.type.text`	✓	✓	✓	✓	✓
The payer's own code for the benefit	`coverage.benefit.type.coding.where(system = 'https://www.cigna.com/benefitServiceId' or system = 'https://www.uhc.com/medicalServiceId')`	—	✓	—	✓	—
Benefit description	`coverage.benefit.extension.where(url = '[FLEXPA]/benefit-description').valueString`	—	✓	—	✓	✓
Dollar or count limit	`coverage.benefit.limit.value.value`, `coverage.benefit.limit.value.unit`	✓	✓	✓	✓	—
What the limit is called	`coverage.benefit.limit.code.text`	✓	✓	✓	✓	—
The payer's own code for the kind of ceiling	`coverage.benefit.limit.code.coding.where(system = 'https://www.cigna.com/benefitLimitCode')`	—	—	—	✓	—
When the limit resets	`coverage.benefit.limit.extension.where(url = '[FLEXPA]/limit-period').valueCode`	—	—	—	✓	—
Whether the limit is one person's or the household's	`coverage.benefit.limit.extension.where(url = '[FLEXPA]/cost-scope').valueCode`	—	—	—	✓	—
Referral or prior authorization needed	`coverage.benefit.requirement`	✓	—	—	✓	—
Which document the benefit was quoted from	`coverage.benefit.extension.where(url = '[FLEXPA]/benefit-document-name').valueString`	—	✓	—	—	—
Whether the benefit is offered in-network, out-of-network, or not at all	`coverage.benefit.extension.where(url = '[FLEXPA]/benefit-offered').valueString`	✓	—	—	—	—
A service the plan says it does not cover	`coverage.benefit.extension.where(url = '[FLEXPA]/excluded-benefit')`	—	—	—	✓	—
Aetna's own group the service is filed under	`coverage.benefit.extension.where(url = '[FLEXPA]/rollup-group-id').valueString`	—	—	✓	—	—

Data point	Where to look	MA	UHC	Aetna	Cigna	HCSC
Copay	`plan.specificCost.benefit.cost.where(type.coding.where(system = 'http://terminology.hl7.org/CodeSystem/coverage-copay-type').code = 'copay')` where the cost is coded, `plan.specificCost.benefit.cost.where(type.text = 'Copayment')` where it is text only	text	code	code	code	code
Coinsurance	`plan.specificCost.benefit.cost.where(type.coding.where(system = 'http://terminology.hl7.org/CodeSystem/coverage-copay-type').code = 'copaypct')` where the cost is coded, `plan.specificCost.benefit.cost.where(type.text = 'Coinsurance')` where it is text only	text	code	code	code	code
Per-benefit deductible	`plan.specificCost.benefit.cost.where(type.coding.where(system = 'http://terminology.hl7.org/CodeSystem/coverage-copay-type').code = 'deductible')` where the cost is coded, `plan.specificCost.benefit.cost.where(type.text = 'Deductible')` where it is text only	text	code	—	code, dental only	code
Amount, in dollars or percent	`plan.specificCost.benefit.cost.value.value`, `plan.specificCost.benefit.cost.value.unit`	✓	✓	✓	✓	✓
In-network or out-of-network	`plan.specificCost.benefit.cost.applicability.coding.code`	✓	✓	✓	✓	✓
Conditions on the cost, such as a setting or a days supply	`plan.specificCost.benefit.cost.qualifiers.text`	✓	✓	✓	✓	✓
Whether the cost counts toward the out-of-pocket maximum	`plan.specificCost.benefit.cost.extension.where(url = '[FLEXPA]/cost-applies-to-oop').valueBoolean`	—	—	—	✓	—
Which coverage line the costs belong to	`plan.specificCost.category.coding.code`	✓	✓	✓	✓	✓

#Drug coverage

Data point	Where to look	MA	UHC	Aetna	Cigna	HCSC
The plan the drug benefits sit on	`InsurancePlan.where(type.coding.where(system = 'http://terminology.hl7.org/CodeSystem/v3-ActCode').code = 'DRUGPOL')`	—	✓	✓	✓	✓
Which drug tier, and whether it is retail or mail order	`plan.specificCost.benefit.type.text`	—	✓	✓	✓	✓
Cost sharing for that tier	`plan.specificCost.benefit.cost`	—	✓	✓	✓	✓
Days supply	`plan.specificCost.benefit.cost.qualifiers.text`	—	✓	✓	✓	—
Pharmacy deductible	`plan.generalCost`, on that plan	—	✓	—	✓	—
Whether the pharmacy deductible is combined with the medical one	`extension.where(url = '[FLEXPA]/pharmacy-deductible-combined').valueBoolean`	—	✓	—	—	—
Whether the pharmacy out-of-pocket maximum is combined with the medical one	`extension.where(url = '[FLEXPA]/pharmacy-oop-combined').valueBoolean`	—	✓	—	—	—
Whether the drug line draws on the medical accumulators	`extension.where(url = '[FLEXPA]/accumulators-shared-with-medical').valueBoolean`	—	—	—	✓	—
Which other product groups share the deductible	`extension.where(url = '[FLEXPA]/deductible-shared').extension.where(url = 'sharedWith').valueCoding.code`	—	—	—	✓	—
Which other product groups share the out-of-pocket maximum	`extension.where(url = '[FLEXPA]/oop-max-shared').extension.where(url = 'sharedWith').valueCoding.code`	—	—	—	✓	—
Which Part D benefit design the plan uses	`extension.where(url = '[FLEXPA]/drug-benefit').extension.where(url = 'category').valueString` and `.where(url = 'type').valueString`	✓	—	—	—	—
Formulary ID	`identifier.where(system = 'https://hpms.cms.gov/formulary-id').value`	✓	—	—	—	—
Pharmacy routing numbers a pharmacist bills against	`identifier.where(system = 'https://www.bcbsil.com/rxBin').value`, `.../rxPCN`	—	—	—	—	✓
Drug list code	`extension.where(url = '[FLEXPA]/cigna-drug-list-code').valueString`	—	—	—	✓	—
Highest drug tier the plan prices	`extension.where(url = '[FLEXPA]/max-tier-number').valueString`	—	—	—	✓	—
Days supply for a specialty drug at retail	`extension.where(url = '[FLEXPA]/specialty-drug-days-retail').valueString`	—	—	—	✓	—
Days supply for a specialty drug by mail order	`extension.where(url = '[FLEXPA]/specialty-drug-days-mail-order').valueString`	—	—	—	✓	—
Fills of a 30-day supply the plan permits	`extension.where(url = '[FLEXPA]/fills-per-30-day-supply').valueString`	—	—	—	✓	—
Whether the 90-day retail program is voluntary or mandatory	`extension.where(url = '[FLEXPA]/retail-90-day-program-type').valueString`	—	—	—	✓	—

deductible-shared and oop-max-shared are complex extensions rather than simple ones. Each carries a sharedWith child naming the other product group and, where the tier can be coded, a network child.

#Plan characteristics

Data point	Where to look	MA	UHC	Aetna	Cigna	HCSC
Commercial, Medicare or Medicaid	`extension.where(url = '[FLEXPA]/program-type').valueString`	—	✓	✓	—	✓
Line of business, as United's own token	`extension.where(url = '[FLEXPA]/united-line-of-business').valueString`	—	✓	—	—	—
Market segment, employer group or individual	`extension.where(url = '[FLEXPA]/market-segment').valueString`	—	—	—	—	✓
Market the plan is sold in, as United's own code	`extension.where(url = '[FLEXPA]/united-market-type').valueString`	—	✓	—	—	—
Product, as United's own code	`extension.where(url = '[FLEXPA]/united-product-code').valueString`	—	✓	—	—	—
How a shared funding arrangement is split, as United's own code	`extension.where(url = '[FLEXPA]/shared-arrangement-code').valueString`	—	✓	—	—	—
Funding arrangement, as a decoded word	`extension.where(url = '[FLEXPA]/funding-arrangement').valueString`	—	✓	—	—	—
Funding arrangement, as Cigna's own code	`extension.where(url = '[FLEXPA]/cigna-funding-arrangement-type').valueString`	—	—	—	✓	—
Whether a referral from a primary care provider is required	`extension.where(url = '[FLEXPA]/pcp-referral-required').valueBoolean`	—	✓	—	—	—
Whether a referral is required	`extension.where(url = '[FLEXPA]/referral-required').valueBoolean`	—	—	—	✓	—
Care must go through a primary care provider to be covered	`extension.where(url = '[FLEXPA]/gated-plan').valueBoolean`	—	✓	—	—	—
Virtual visits available	`extension.where(url = '[FLEXPA]/virtual-visits-available').valueBoolean`	—	✓	—	—	—
Whether a primary care provider may be elected	`extension.where(url = '[FLEXPA]/pcp-eligibility').valueString`	—	✓	—	—	—
Whether primary care referrals apply	`extension.where(url = '[FLEXPA]/pcp-referrals').valueString`	—	✓	—	—	—
Whether a primary care provider is required or recommended	`extension.where(url = '[FLEXPA]/pcp-requirement').valueString`	—	—	—	✓	—
Whether a primary care medical group must be chosen	`extension.where(url = '[FLEXPA]/pcp-medical-group-required').valueBoolean`	—	—	—	—	✓
Covers the ten essential health benefits	`extension.where(url = '[FLEXPA]/essential-health-benefits').valueBoolean`	—	✓	—	—	—
High-deductible health plan	`extension.where(url = '[FLEXPA]/high-deductible-health-plan').valueBoolean`	—	✓	—	—	—
Eligible for a health savings account	`extension.where(url = '[FLEXPA]/hsa-eligible').valueBoolean`	—	✓	—	—	—
Eligible for a health reimbursement arrangement	`extension.where(url = '[FLEXPA]/hra-eligible').valueBoolean`	—	✓	—	—	—
Provider network name	`extension.where(url = '[FLEXPA]/network-name').valueString`	—	—	—	✓	—
Provider network id	`extension.where(url = '[FLEXPA]/cigna-network-id').valueString`	—	—	—	✓	—
Provider network category	`extension.where(url = '[FLEXPA]/cigna-network-category').valueString`	—	—	—	✓	—
Which network tiers the policy covers	`extension.where(url = '[FLEXPA]/cigna-network-coverage').valueString`	—	—	—	✓	—
Whether the plan has a deductible at all	`extension.where(url = '[FLEXPA]/has-deductible').valueBoolean`	—	—	—	✓	—
Whether the plan has an out-of-pocket maximum at all	`extension.where(url = '[FLEXPA]/has-oop-maximum').valueBoolean`	—	—	—	✓	—
Whether the plan caps what it pays out in a year	`extension.where(url = '[FLEXPA]/has-plan-maximum').valueBoolean`	—	—	—	✓	—
State whose insurance law governs the contract	`extension.where(url = '[FLEXPA]/situs-state').valueString`	—	✓	—	✓	—
Blue Cross and Blue Shield entity servicing the member	`extension.where(url = '[FLEXPA]/hcsc-plan-state').valueString`	—	—	—	—	✓
Sold on a public exchange	`extension.where(url = '[FLEXPA]/on-exchange').valueBoolean`	—	—	—	—	✓
Medicare supplement	`extension.where(url = '[FLEXPA]/medicare-supplement').valueBoolean`	—	—	—	—	✓
Grandfathered under the Affordable Care Act	`extension.where(url = '[FLEXPA]/grandfathered-plan').valueBoolean`	—	—	—	✓	—
Whether a flat copay counts toward the out-of-pocket maximum	`extension.where(url = '[FLEXPA]/copay-applies-to-oop').valueBoolean`	—	—	—	✓	—
Whether the deductible counts toward the out-of-pocket maximum	`extension.where(url = '[FLEXPA]/deductible-applies-to-oop').valueBoolean`	—	—	—	✓	—
Whether the plan is sold alongside another as a supplement	`extension.where(url = '[FLEXPA]/supplemental-plan').valueBoolean`	—	✓	—	—	—
Pharmacy benefit administered by someone else	`extension.where(url = '[FLEXPA]/pharmacy-carve-out').valueBoolean`	—	✓	—	—	—
Another benefit administered by a third party	`extension.where(url = '[FLEXPA]/third-party-carve-out').valueBoolean`	—	✓	—	—	—
Employer's own branding on the plan	`extension.where(url = '[FLEXPA]/private-label-customer').valueString`	—	✓	—	—	—
Multiplier the plan applies to a member's maximum	`extension.where(url = '[FLEXPA]/consumer-max-multiplier').valueString`	—	✓	—	—	—
Dental product type	`extension.where(url = '[FLEXPA]/dental-plan-type').valueString`	—	✓	—	—	—
Whose accumulators the figures describe	`extension.where(url = '[FLEXPA]/plan-scope').valueString`	—	—	✓	—	—
Aetna's own plan characteristic tokens	`extension.where(url = '[FLEXPA]/view-characteristic').valueString`	—	—	✓	—	—
CMS contract effective date	`extension.where(url = '[FLEXPA]/contract-effective-date').valueDate`	✓	—	—	—	—
CMS contract enrollment count	`extension.where(url = '[FLEXPA]/contract-enrollment').valueInteger`	✓	—	—	—	—
Sanctioned by CMS	`extension.where(url = '[FLEXPA]/sanctioned-plan').valueBoolean`	✓	—	—	—	—
Issuer tax status	`contained.ofType(Organization).extension.where(url = '[FLEXPA]/tax-status').valueString`	✓	—	—	—	—
Voluntary de minimis premium reduction	`extension.where(url = '[FLEXPA]/voluntary-de-minimis').valueBoolean`	✓	—	—	—	—
Medicare Advantage region	`extension.where(url = '[FLEXPA]/ma-region').extension.where(url = 'code').valueString` and `.where(url = 'name').valueString`	✓	—	—	—	—
Star rating, overall and for Part C and Part D	`extension.where(url = '[FLEXPA]/star-rating').extension.where(url = 'overall' or url = 'partC' or url = 'partD').valueDecimal`	✓	—	—	—	—
Special Needs Plan type	`extension.where(url = '[FLEXPA]/snp').extension.where(url = 'type').valueString`, with `institutionalType` and `chronicConditions` beside it	✓	—	—	—	—
How a dual-eligible Special Needs Plan is integrated	`extension.where(url = '[FLEXPA]/dsnp-integration').extension.where(url = 'integrationStatus').valueString`, with `hasApplicableIntegratedPlan` and `zeroDollarCostSharing` as booleans	✓	—	—	—	—
Low-income subsidy auto-enrollment	`extension.where(url = '[FLEXPA]/lis-auto-enrollment').valueBoolean`	✓	—	—	—	—
Part D premium at or below benchmark	`extension.where(url = '[FLEXPA]/part-d-premium-at-or-below-benchmark').valueBoolean`	✓	—	—	—	—

#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.