DaVinci Payer Data Exchange (PDex) US Drug Formulary
2.0.1 - STU 2 United States of America flag

DaVinci Payer Data Exchange (PDex) US Drug Formulary, published by HL7 International / Pharmacy. This guide is not an authorized publication; it is the continuous build for version 2.0.1 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/davinci-pdex-formulary/ and changes regularly. See the Directory of published versions

Use Cases and Overview

Page standards status: Informative

Conformance Expectations

  • This guide inherits all conformance expectations identified in the Health Record Exchange (Hrex) Conformance Expectations section. All systems claiming conformance to this guide SHALL conform to the requirements listed in that section.

  • Server systems claiming conformance to this guide SHALL meet the capability statement expectation requirements identified in the US Drug Formulary Server Capability Statement and SHALL have a CapabilityStatement that has a CapabilityStatement.instantiates with a URL of http://hl7.org/fhir/us/davinci-drug-formulary/CapabilityStatement/usdf-server or a URL to the appropriate version of the CapabilityStatement.

Use Cases


  • Member: A person to whom health care coverage has been extended by the policyholder (generally their employer) or any of their covered family members. Sometimes referred to as the insured or insured person. The cost of medications for a member is a function of the drug coverage under their health insurance plan, their benefits based on their already satisfied deductibles, and the pharmacy where their prescriptions are filled.
  • Consumer: A person who may or may not be a member, who wishes to explore the formulary content and plan-level co-insurance.
  • Health Plan: A provider of insurance coverage that often includes a drug coverage plan which publishes formulary content and plan-level co-insurance information through the Drug Formulary FHIR API.

Medication Copay Under Health Plan

This use case allows a member to determine the plan level estimated costs of each of their medications under the drug coverage of their current health plan. An application queries the formulary service for cost information about the drugs that the member has interest in and provides the plan level estimated cost for each medication under the member’s current health plan.

Note that for this use case the health plan would provide authenticated access to the formulary.

Unauthenticated Access Workflow

Shopping for Health Plans

This use case allows a consumer to compare the drug coverage of several different health plans and determine which plan has the lowest plan level estimated cost based on their medications of interest. The application can retrieve the consumer’s medication list from an electronic health record system where the consumer’s patient data is stored (outside the scope of this implementation guide). The consumer could also independently maintain their medication list in the application or elsewhere. The application identifies the relevant formulary endpoint through means that are beyond the scope of this implementation guide (see Disclaimers and Assumptions). For each payer, the application queries the payer’s formulary service to retrieve the list of health plans provided by that payer. Then, for each plan,the application queries the formulary service to retrieve the plan-level estimated costs specific to the consumer’s medication list.

Note that for this use case the health plan could provide non-authenticated or open access to the formulary. Non-authenticated access should not maintain any records that could associate an individual with the medications or plans queried.

Authenticated Access Workflow

Access Methods

The formulary service can potentially be accessed two different ways:

  1. Authenticated API: Access to the formulary service when integrated with protected health information (PHI) or personally identifiable information (PII) as part of the Patient Access API SHALL be protected through an authorized, authenticated transaction as described in the Da Vinci Health Record Exchange (HRex) FHIR Implementation Guide Security and Privacy Section.
  2. Unauthenticated API: When exchanging formulary data exclusively, which is public information without any PHI or PII, the formulary service MAY also be accessed through an API that does not require authentication or authorization. The formulary server SHALL NOT maintain any records through the unauthenticated API that could associate the consumer with the medications queried.


When accessing data through an authenticated API, the response for queries on InsurancePlan depends on whether the authenticated member has access to the plan in relation to their membership.

For the Payer Insurance Plan, this is the overall plan or plans that the individual is a member of. For Formulary, this means all Formularies that are generally available to the member. If the member is in a group, all group associated formularies are returned. If not in a group, all generally available formularies (that is, those that are not restricted to only one or more groups) are returned. Clients can determine the Formulary InsurancePlan(s) that the member is subscribed by first retrieving the Payer Insurance Plan(s) and identifying the Formulary(s) through the Payer Insurance Plan InsurancePlan.coverage.

The following table indicates how the Formulary API should respond to requests when a Formulary Insurance plan (by resource reference) is specified and when it is not.

InsurancePlan specified – GET by resource ID InsurancePlan reference not specified - Search
Return plan if covered by insurer and included in group if member is part of a group
If not, return 400
Return all plans if covered by insurer and included in group if member is part of a group
If none, return 200

Access to other profiled resources in this IG (FormularyItem & FormularyDrug) is not constrained by this IG.

Server implementers SHALL make other profiled resources in this IG (FormularyItem, FormularyDrug) associated to a member’s available plans available through authenticated access. This IG does not define restrictions on authenticated access to resources not associated with a member’s available plan or the Plan Location resource.


When accessing data through an unauthenticated API, the conformant payer formulary service SHALL NOT require an application to send consumer identifying information in order to query for the list of health plans provided by that payer and the medication and costs for each plan.

Formulary Structure

Formularies in the United States are normally published by health insurers on an annual basis, with minor updates during the year. It is critical that health insurers update their published formularies following these minor updates.

Insurers regularly administer multiple health insurance and drug coverage plans and each of those plans may have its own formulary.

Each formulary contains a set of drugs and their limits or requirements. Drugs are placed into tiers that largely determine the cost to the consumer/patient. The number and purpose of drug tiers varies across payers. Each tier has an associated cost-sharing model that includes deductibles and/or coinsurance components for drugs in the tier when purchased through various pharmacy benefit types.

In addition to the drug tier, drugs may also list requirements on the patient (e.g., age or gender) or limitations on prescription (e.g., quantity limits).

Resource Relationships

This Implementation Guide (IG) was significantly influenced by the formulary information model of the formularies for Qualified Health Plans (QHPs) on the federal health insurance marketplace for healthcare.gov. Publishing formularies in the QHP format should be familiar to many payers. Drugs are specified by RxNorm semantic drug codes. The QHP data model mandates specific value sets for some data types (e.g., types of copayments), but leaves value sets for other data types at the discretion of the payer (e.g., drug tier codes, pharmacy benefit types). The following object model shows the relationships between the resources in this IG. The Formulary profiled resource combined with its associated FormularyItem and FormularyDrug profiled resources represent a formulary list that includes the set of drugs covered and the requirements and limitations of that coverage.

A FormularyDrug represents the individual prescribable drug defined with a specific RxNorm semantic drug code that includes ingredient, strength, dose form, and brand name for branded drugs. These codes are represented in RxNorm with the Term Type (TTY) of Semantic Clinical Drug (SCD), Semantic Branded Drug (SBD), Generic Pack (GPCK), or Branded Pack (BPCK). Additionally, a more general RxNorm semantic drug form group code SHOULD be present for searching across drugs with the same ingredient, brand, and form (regardless of strength). These codes are represented in RxNorm with the Term Type (TTY) of Semantic Clinical Drug Form (SCDG) and Semantic Branded Drug Form Group (SBDG). All drugs with RxNorm Term Type of SCD or SBD SHALL have a coding repetition and RxNorm Term Type of SCDG or SBDG respectively. Drug packs, represented by RxNorm codes GPCK or BPCK may not have a corresponding drug form group. The FormularyItem links a drug with a formulary and includes the attributes that drug has in relation to the formulary, including the drug tier and coverage constraints.

Cost Sharing Relationship

Cost sharing information such as copay amounts and coinsurance rates are determined by a payer in the insurance plan. The amount of copay and percentage of coinsurance is a function of the pharmacy benefit type (e.g. in network mail order) and the drug tier (e.g. preferred generic). These specific costs are defined in the PayerInsurancePlan . The pharmacy benefit types and drug tiers, without the cost information, may optionally be included in the Formulary as a convenience for client applications to quickly identify the pharmacy benefit types and drug tiers contained on the formulary without having to retrieve the PayerInsurancePlan.

The costs for a particular drug in a plan will be determined by the pharmacy benefit types and drug tier as indicated in the properties of the FormularyItem. These properties are used to link the PayerInsurancePlan specificCost properties (Pharmacy Benefit Type - InsurancePlan.plan.specificCost.category and Drug Tier - InsurancePlan.plan.specificCost.benefit.type) to identify the costs for the drug under the plan.

Bulk Data

Bulk data guidance in this version of the IG is draft only. It has not appeared in ballot and has not been fully tested.

A server MAY support Bulk Data IG for the retrieval of formulary data not related to an individual. The Bulk Data IG may be used because the data set for formularies could be large as a server may manage multiple formularies, each of which may contain thousands of drugs. If and how authorization is supported is not defined by this specification, however, the Bulk IG does provide guidance on SMART Backend Service Authorization.

If a Formulary server supports bulk data export:

  • All InsurancePlan: The server SHOULD support the export operation on the InsurancePlan resource [base]/InsurancePlan/$export to export all plan & formulary information.
    • The server SHOULD support providing all InsurancePlan, Basic, MedicationKnowledge, and Location resource types containing formulary related data associated with all formulary related plans.
    • The server SHOULD support the graph structure Payer Insurance Plan Bulk Data Graph Definition in returned results.
    • The server MAY support a graph parameter using (e.g. [base]/InsurancePlan/$export?graph=usdf-PayerInsurancePlanBulkDataGraphDefinition) to request returning results starting at the PayerInsurancePlan.
    • The server MAY support a graph parameter using (e.g. [base]/InsurancePlan/$export?graph=usdf-FormularyBulkDataGraphDefinition) to request returning results starting at the Formulary. This request would not return PayerInsurancePlan resources.
  • Specific InsurancePlan: The server SHOULD support the export operation on the InsurancePlan resource [base]/InsurancePlan/[id]/$export to export plan specific plan & formulary information.
  • The server SHOULD return only formulary related resources conformant to this guide.
  • The server SHOULD support the Bulk Data Kick-off Request.
  • The server SHOULD support the Bulk Data File Request.
  • The server MAY support the Bulk Data Status Request.
  • The server MAY support the Bulk Data Delete Request.

Searching Formulary Drugs

This guide provides a mechanism for rudimentary drug searching and filtering based on drug codes, names, and forms, by requiring server systems to support this data. This capability is not robust and client systems are encouraged to augment their drug searching capabilities using outside services or data sources to better meet the needs of their users.

Searching for formulary drugs can be done by RxNorm code, RxNorm drug name, and dose form. In a formulary API, payers are likely to only include the specific drugs, specific down to form and strength, that are included in the coverage. If a search does not return the anticipated or desireable results, it is recommended that the client broaden the search (e.g. include both generic and brand RxNorm codes, search on name without strength, or search on an RxNorm code that does not include strength - see more guidance about supported RxNorm code term types below). Additionally, drugs that have special coverage rules may or may not be included in an API. These rules are often expressed in additional formulary documentation, referenced by the InsurancePlan.contact, which SHOULD be presented to the user of the client application.

Formulary searches may be restricted to just the drugs supported by the payer therefore it is up to the user or calling application to convert patient searching requirements for branded or equivalent drugs into one or more formulary searches.

Covered drugs may appear in the formulary and non-covered drugs are simply not included. For example, a payer may pay for a generic form of a drug, but does not have a brand in their formulary. To retrieve matching drugs and available alternatives, it may be necessary for a client to search using the ingredient (generic) in addition to a brand.

Note: In addition to the guidance and requirements below regarding searching for drugs based on an RxNorm code or display, servers may wish to support additional coding systems and display values in order to represent specific drugs that may have the same RxNorm code, but have different coverage specifics as defined in the Specific Drug Coverage Details section. This may result in more than one FormularyDrug with the same RxNorm code and display value.

Searching By Drug Code

The preferred way to search for drugs is to use an RxNorm code (RxCUI). The RxNorm codes and names are freely available and services to look-up codes exist. If a client application is performing a query with the intent on finding generic or brand alternatives, the client application SHOULD search using both the brand and the generic RxNorm code.

Servers SHALL support a MedicationKnowledge.code.coding repetition including the detailed drug, strength, and form, including RxNorm Term Types (TTY) of SCD (Semantic Clinical Drug), SBD Semantic Branded Drug), GPCK (Generic Pack), or BPCK (Branded Pack). Additionally, servers SHALL support a MedicationKnowledge.code.coding repetition including the general RxNorm code (and name) with Term Type of SCDG (Semantic Clinical Drug Form Group) or SBDG (Semantic Branded Drug Form Group) when there is a concept matching the primary code represented by the Term Type SCD or SBD respectively. This requirement includes using the respective RxNorm name in the display of the coding repetition.

Searches for drugs with the above RxNorm Term Types (SCDG and SBDG) by either code will provide the client with a way to search for drugs without a specified strength.

Searching By Drug Name

This Implementation Guide provides the ability to search for FormularyDrug (MedicationKnowledge) resources by drug name through the drug-name search parameter. This search parameter is based on the MedicationKnowledge.code.coding.display and provides a full (exact) or partial (contains) equals (eq) string match. Per the FHIR Specification, the Correct RxNorm Display is the Full RxNorm name of either the Semantic Clinical Drug (SCD) or Semantic Brand Drug (SBD). The full drug name has several components presented in the following formats:

  • SCD = Ingredient + Strength + Dose Form
  • SBD = Ingredient + Strength + Dose Form + [Brand Name]

In addition to these RxNorm names, drug combination packs may also appear in formularies. Drug combination packs can contain multiple drugs or strengths that are packaged and prescribed together, under a brand or generic drug name, to meet a particular set of administration requirements. The full name for drug combination packs have components presented in the following formats:

  • GPCK = {# (Ingredient + Strength + Dose Form) / # (Ingredient + Strength + Dose Form)} Pack
  • BPCK = {# (Ingredient + Strength + Dose Form) / # (Ingredient + Strength + Dose Form)} Pack [Brand Name]

Servers are required to support the more general drug form group code and name where one exists. This display name will be included in any drug name search for which the general drug form group code exists. The RxNorm name of these codes has several components presented in the following formats:

  • SCDG = Ingredient + Dose Form Group
  • SBDG = Ingredient + Dose Form Group + [Brand Name]

The drug-name SearchParameter includes the multipleAnd capability, which allows for multiple drug-name search parameters within a single query. With this capability it is possible to search by drug name and form where a dose form group is not available. This capability should be used sparingly, as each additional partial string search parameter increases the load on the server.

For Example: MedicationKnowledge?drug-name:contains=acetaminophen&drug-name:contains=Tablet

This search will return all matching drug names with both the ingredient “acetaminophen” and dose form “Tablet”. This will also return any matching combination or pack drugs.

Another factor clients need to consider when searching for drugs by name, is that individual drug names may be contained within combination drugs (e.g., a search on acetaminophen will return many combination drugs). Clients may need to filter search results to fit their requirements.

Additional Guidance

Specific Drug Coverage Details

RxNorm codes and descriptions were chosen as the mechanism for searching and describing covered drugs for consumer use because that is what consumers will generally have access to given the requirements laid out in US regulation. RxNorm is also the code system used for many outpatient pharmacy prescribing transactions.

RxNorm provides a consumer accessible categorization for prescribable drugs. This categorization may not be specific enough for payers that have very detailed coverage constraints they feel are necessary to express to their members.

This IG Provides the following ways to express various levels of coverage (coverage status, requirements, or costs) for multiple drugs represented under one RxNorm code.

  • Specific drugs identified by unique FormularyDrug resource instances that are associated to a Formulary with specific coverage conditions, requirements, and costs through a FormularyItem.
    • A specific drug code using NDC or other code system is included as a FormularyDrug MedicationKnowledge.code.coding that includes the specific name in the display to enable searching.
  • Drugs identified by a general RxNorm code in a single FormularyDrug MedicationKnowledge resource with specific coverage conditions and requirements communicated in the referenced FormularyItem.
    • Specific details including drugs covered or not covered, coverage conditions, or requirements are specified in the FormularyItem Basic.extensions.

Presenting Drug Alternatives

Finding appropriate alternatives of a prescribed medication is complex and often depends on additional clinical information about the patient well as the condition or set of conditions for which the medication is meant to address. The means to identify therapeutic alternatives to drugs does exist in the industry, but such capability is complex, requires clinical information about the patient that is not within in scope of this guide, and a clinical understanding of the intended therapeutic use of the medication which is not generally within the competency of most members. The information and business rules necessary to identify possible therapeutic alternatives, and therefore the ability to search for such alternatives, currently lies outside of the scope of this guide.

Representing Drug Tiers

Drug tiers are not standardized. The current Implementation Guide provides a defined, but extensible value set for tier identifiers based on the example list in the QHP formulary specification. A move towards standardization might make this data more useful for clients of the interface.

Representing Pharmacy Benefit Types

Pharmacy benefit types are not standardized. The current Implementation Guide provides a defined value set for tier identifiers based on the example list in the QHP formulary specification which mixes channels (retail and mail order) with quantity prescribed (1 month, 3 month, etc). A move towards standardization might make this data more useful for clients of the interface.