Formularies

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.

Dataset	US Drug Formulary STU 2.1.0 target profile
`formularies`	Formulary (InsurancePlan)

The formulary's identifiers and contacts repeat, so they are the datasets formulary_identifiers and formulary_contacts.

One row per formulary. A formulary is a plan-year list; a new plan year is a new row with a new formulary_id.

Column	Required	Format / values	Example
`formulary_id`	Yes	your stable key; `payer_plans` and `formulary_items` reference it	`FORM-2027-A`
`formulary_name`	Recommended	text	`Example Health 2027 Part D Formulary`
`formulary_aliases`	If renamed	earlier names, `;`-separated, up to three, so old searches still find it
`status`	Yes	`active`, `draft`, `retired`, `unknown` publication-status	`active`
`period_start`	Recommended	date the formulary takes effect	`2027-01-01`
`period_end`	Recommended	date the formulary expires	`2027-12-31`
`owned_by_org_npi`	Recommended	10 digits, Luhn-valid over the `80840` prefix; the plan sponsor that issues the formulary; key from `organizations`	`9999999979`
`administered_by_org_npi`	If different	10 digits, Luhn-valid over the `80840` prefix; the PBM or administrator that maintains it; key from `organizations`	`9999999961`
`network_ids`	If available	pharmacy networks the formulary applies to, keys from Provider Directory `networks`, `;`-separated; each must be a network that feed has published, or the formulary waits for it	`NET-001`
`coverage_area_ids`	If available	keys from `coverage_areas`, `;`-separated	`AREA-NY`
`last_updated`	Yes	datetime with a timezone offset, `YYYY-MM-DDThh:mm:ss±hh:mm`, when the formulary last changed in your system; a date alone holds the row back	`2026-10-01T09:00:00-05:00`
`is_deleted`	If retracting	`true` sets the published formulary's `status` to `retired`; its identifier and contact rows go with it	`true`

The profile requires at least one identifier. formulary_id becomes it, under the identifier namespace fixed for your engagement. Every other identifier, such as the CMS formulary id from your HPMS submission, is a row in formulary_identifiers with its own namespace.
A formulary needs a name or an id; both are better. Payerbox sets its type to drug policy and its plan type to drug, which is what marks an InsurancePlan as a formulary rather than a payer plan.
owned_by_org_npi, administered_by_org_npi and network_ids are the same keys the Provider Directory plans dataset uses, so a formulary and the plan that uses it name the same sponsor and networks. coverage_area_ids point at the same coverage_areas rows the plans use. An NPI that fails the check digit is reported as invalid_npi and the sponsor is left off; the formulary still publishes.
A formulary revised within the plan year keeps its formulary_id; last_updated on the formulary and on the changed items is how a revision is told from the previous one. The IG has no version element, and none is added.
Contacts, including the printable formulary the IG expects to be reachable from the resource, are rows in formulary_contacts.
Not collected: endpoint, and the Formulary's own coverage and plan structures. The IG uses the Formulary as an organizing construct; cost sharing lives on the payer plan.

These resources are served by Patient Access.