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.

DatasetUS Drug Formulary STU 2.1.0 target profile
payer_plansPayer Insurance Plan (InsurancePlan), with its coverage area as Insurance Plan Location

payer_plans

One row per plan, pharmacy benefit type and drug tier. A plan with eight benefit types and five tiers produces up to forty rows; the plan-level columns repeat on each and must agree. Payerbox builds one InsurancePlan per plan_id and one cost-sharing entry per row.

payer_plans.csv Data template with example rows
ColumnRequiredFormat / valuesExample
plan_idYesyour stable key for the plan; the same value as in Provider Directory plansPLAN-DSNP
plan_identifierIf MAH#####-###-###, contract-plan-segment, as in Provider Directory plansH6776-001-000
drug_plan_idIf differentidentifier of the drug plan inside the product, used to link a member's Coverage; blank when it equals plan_id
plan_nameRecommendedtextExample Health D-SNP
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_statesRecommended2-letter USPS states where the plan is offered, ;-separated; US for nationwideNY
owned_by_org_npiRecommended10 digits; the plan sponsor; key from organizations9999999993
administered_by_org_npiIf different10 digits; the administrator or PBM; key from organizations
network_idsIf availablepharmacy networks of the drug benefit, keys from Provider Directory networks, ;-separatedNET-001
member_phoneRecommended10 digits; member services line8885551002
marketing_urlRecommendedplan marketing pagehttps://example.org/plans/dsnp
summary_urlRecommendedsummary of drug benefits pagehttps://example.org/plans/dsnp/benefits
formulary_urlRecommendedprintable formulary pagehttps://example.org/plans/dsnp/formulary
formulary_idsYeskeys from formularies, ;-separated; one in the usual caseFORM-2027-A
pharmacy_benefit_typeYessee Pharmacy benefit types1-month-in-retail
drug_tierYessee Drug tiersgeneric
copay_amountYes, unless coinsurance_rate is sentdecimal; flat amount per fill5.00
copay_optionIf copay_amountafter-deductible, before-deductible, no-charge, no-charge-after-deductible, charge, copay-not-applicable, deductible-waived CopayOptionVScharge
coinsurance_rateYes, unless copay_amount is sentpercent, 0 to 10025
coinsurance_optionIf coinsurance_rateafter-deductible, no-charge, no-charge-after-deductible, charge, coinsurance-not-applicable, deductible-waived CoinsuranceOptionVSafter-deductible
last_updatedYesdatetime the plan last changed in your system2026-10-01T09:00:00-05:00
is_deletedIf retractingtrue retracts every row of this plan_idtrue
  • Each row must carry a copay, a coinsurance, or both. The option column says how the amount interacts with the deductible; copay-not-applicable and coinsurance-not-applicable are how a tier says it has no copay or no coinsurance while still stating the other. Send 0.00 with no-charge for a tier that is free.
  • The pharmacy benefit types and tiers a plan uses in payer_plans are the vocabulary its formulary items may use. A formulary_items row whose drug_tier or pharmacy_benefit_types the plan's cost table does not define is reported.
  • coverage_area_states is the one place Payerbox creates a resource without a key from you: one Location per state code, named after the state, with the state as its address. US yields a single nationwide Location.
  • member_phone and the three URLs become the plan's contacts, typed member information, marketing, summary and formulary. The IG expects payers to point members at the printed formulary for rules the structured data cannot express.
  • The profile requires at least one identifier. plan_id becomes it, under the identifier namespace fixed for your engagement. plan_identifier becomes a second identifier under the CMS Medicare Advantage plan-id namespace, the same way the Provider Directory publishes it.
  • owned_by_org_npi, administered_by_org_npi and network_ids reuse the Provider Directory keys, so the same plan described in both feeds names one sponsor and one set of networks.
  • drug_plan_id exists for the 2.1.0 link from a member's Coverage to the drug plan inside a product. Send it when your enrollment system identifies the Part D plan separately from the product; otherwise Payerbox uses plan_id.

Pharmacy benefit types

pharmacy_benefit_type says through which channel and supply length a cost applies. The set is the IG's own PharmacyBenefitTypeVS, extensible: a plan may add its own codes, and then defines them in a code system Payerbox registers per engagement.

ValueMeaning
1-month-in-retail1-month supply, in-network retail pharmacy
1-month-out-retail1-month supply, out-of-network retail pharmacy
1-month-in-mail1-month supply, in-network mail order
1-month-out-mail1-month supply, out-of-network mail order
3-month-in-retail3-month supply, in-network retail pharmacy
3-month-out-retail3-month supply, out-of-network retail pharmacy
3-month-in-mail3-month supply, in-network mail order
3-month-out-mail3-month supply, out-of-network mail order

Drug tiers

drug_tier is the plan's own tier for the drug. The IG ships an example set, DrugTierVS, and expects plans to use their own where these do not fit. Send the code your plan documents use; if it is not one of these, tell us during scoping so the tier is registered.

ValueMeaning
preferred-genericcommonly prescribed generic drugs
genericgeneric drugs that cost more than preferred generics
non-preferred-genericgeneric drugs that cost more than the generic tier
preferred-brandbrand-name drugs preferred by the plan
brandbrand-name drugs that cost more than preferred brands
non-preferred-brandbrand-name drugs that cost more than the brand tier
preferreddrugs preferred by the plan, where tiers are not split by generic and brand
non-preferreddrugs that cost more than the preferred tier
specialtydrugs for complex conditions, generic or brand, often with special handling
zero-cost-share-preventativepreventive drugs available at no cost
medical-servicedrugs administered by a clinician or in a facility, covered under the medical benefit

These resources are served by Patient Access.

Last updated: