For AI agents: the documentation index is at /docs/payerbox/llms.txt. A Markdown version of this page is available at /docs/payerbox/data-integration/drug-formulary/payer-plans.md or by requesting it with the Accept: text/markdown header.
Payerbox Docs

Payer Plans

Datasets

Part of the Drug Formulary feed, built to Da Vinci PDex US Drug Formulary STU 2.1.0. The feed's data conventions apply.

A payer plan is one Payer Insurance Plan (InsurancePlan). The profile nests several repeating structures, and every one that may repeat is its own dataset here: the root file carries what occurs once per plan, and each child file carries one repeating element, keyed back to its parent. This mirrors the profile's slices one to one.

A repeating element is carried one of two ways. A structure with fields of its own is a child dataset, one row per occurrence. A repeating reference, code or short text with no fields of its own is a ;-separated list column on its parent row. Free-text lists such as aliases must not contain ; inside a value; a value that needs one goes in a single-value column or its own row.

DatasetElementCardinalityParent
payer_plansInsurancePlanone per plan
plan_identifiersidentifier1..*payer_plans
plan_contactscontact0..*, must supportpayer_plans
coverage_areascoverageArea, an Insurance Plan Location0..*, must supportpayer_plans, drug_plans, formularies
plan_drug_coveragescoverage:drug-coverage1..*payer_plans
drug_coverage_benefitscoverage:drug-coverage.benefit:drug-plan1..*plan_drug_coverages
drug_plansplan:drug-plan1..*payer_plans
drug_plan_specific_costsplan:drug-plan.specificCost1..*drug_plans
drug_plan_tier_benefitsplan:drug-plan.specificCost.benefit1..*drug_plan_specific_costs
drug_plan_tier_costsplan:drug-plan.specificCost.benefit.cost1..*drug_plan_tier_benefits
drug_plan_general_costsplan:drug-plan.generalCost0..*drug_plans

Repeating references and codes that carry no fields of their own stay as ;-separated lists on their parent row: network_ids, coverage_area_ids, formulary_ids, plan_aliases.

payer_plans

One row per plan: the elements of the InsurancePlan that occur once.

ColumnRequiredFormat / valuesExample
plan_idYesyour stable key for the plan; every child dataset references it, and it is the same value as in Provider Directory plansPLAN-DSNP
plan_nameRecommendedtextExample Health D-SNP
plan_aliasesIf renamedearlier names, ;-separated, up to three
statusYesactive, draft, retired, unknown publication-statusactive
plan_typeYesmediadv Medicare Advantage, mediadvhmo MA HMO InsuranceProductTypeVSmediadv
period_startRecommendeddate the plan year begins2027-01-01
period_endRecommendeddate the plan year ends2027-12-31
coverage_area_idsRecommendedkeys from coverage_areas, ;-separatedAREA-NY
owned_by_org_identifierRecommendedPlan issuer99999
administered_by_org_identifierYesProduct administrator99999
network_idsIf availablenetworks of the product, keys from Provider Directory networks, ;-separated; each must be a network that feed has published, or the plan waits for itNET-001
last_updatedYesdatetime with a timezone offset, YYYY-MM-DDThh:mm:ss±hh:mm, when the plan last changed in your system; a date alone holds the row back2026-10-01T09:00:00-05:00
is_deletedIf retractingtrue sets the published plan's status to retired; every child row that references it goes with ittrue
  • plan_id becomes the plan's first identifier, under the identifier namespace fixed for your engagement. Further identifiers, such as the CMS contract-plan-segment, are rows in plan_identifiers.
  • A plan is complete only with its children. The profile requires at least one drug coverage and at least one drug plan with a cost table, so a payer_plans row with no plan_drug_coverages row or no drug_plans row is reported and not published.
  • Plan-Net defines ownedBy as "the entity that is providing the health insurance product and underwriting the risk. This is typically an insurance carriers, other third-party payers, or health plan sponsors commonly referred to as 'payers'."
  • Plan-Net defines administeredBy as "an organization which administer other services such as underwriting, customer service and/or claims processing on behalf of the health insurance product owner."
  • is_deleted on the plan retracts the whole tree. Child rows have their own is_deleted for dropping one contact, one cost cell or one identifier from the plan; a child row absent from the snapshot is dropped the same way when the plan is next built.

How the datasets become the resource

ElementCardinalityFilled from
meta.lastUpdated1..1payer_plans.last_updated
identifier1..*plan_id, then one per plan_identifiers row
status, type, name, alias, periodpayer_plans columns
ownedBy, administeredByowned_by_org_identifier, administered_by_org_identifier
coverageArea0..*, must supportone Insurance Plan Location per coverage_area_ids value, from coverage_areas
contact0..*, must supportone per plan_contacts row
networknetwork_ids
coverage:drug-coverage1..*one per plan_drug_coverages row; type fixed to drug policy; the formulary-reference extension holds each formulary_ids value
coverage:drug-coverage.benefit:drug-plan1..*one per drug_coverage_benefits row; type fixed to drug
plan:drug-plan1..*one per drug_plans row; type fixed to drug; identifier from drug_plan_id
plan:drug-plan.specificCost1..*, must supportone per drug_plan_specific_costs row; category is the pharmacy benefit type
plan:drug-plan.specificCost.benefit1..*, must supportone per drug_plan_tier_benefits row; type is the drug tier
plan:drug-plan.specificCost.benefit.cost1..*one per drug_plan_tier_costs row, into the copay or coinsurance slice by cost_type
plan:drug-plan.generalCost0..*one per drug_plan_general_costs row

Every column maps to an element of the IG's own profiles; the feed defines no extensions. The one element the profile leaves optional and this feed does not collect is endpoint.

These resources are served by Patient Access.

Last updated: