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

Home

Official URL: http://hl7.org/fhir/us/davinci-drug-formulary/ImplementationGuide/hl7.fhir.us.davinci-drug-formulary				Version: 2.1.0	Highlight text changes?
IG Standards status: Trial-use					Computable Name: Formulary
Other Identifiers: OID:2.16.840.1.113883.4.642.40.5

Da Vinci Payer Data Exchange (PDex) US Drug Formulary

This implementation guide defines a FHIR interface to a health insurer's drug formulary information for patients/consumers. A drug formulary is a list of brand-name and generic prescription drugs a health insurer agrees to pay for, at least partially, as part of health insurance coverage. Drug formularies are developed based on the efficacy, safety, and cost of drugs. The primary use cases for this FHIR interface enable consumers/members/patients to understand the costs and alternatives for drugs that have been prescribed, and to compare their drug costs across different insurance plans.

A key architectural issue that is beyond the scope of this implementation guide is how a user finds the FHIR endpoint for a particular formulary. This implementation guide assumes that the FHIR endpoint is known to the user.

Introduction

This Implementation Guide (IG) includes a number of profiles, extensions, search parameters, and value sets.

• PayerInsurancePlan: The PayerInsurancePlan profile of the FHIR R4 InsurancePlan resource defines the health insurance product including coverage benefits that are offered and additional information about the offering, such as a coverage area, contact information, brochure locations, etc. The health insurance product can offer one or more types of coverage, each of which may define a plan of covered benefits with the particular cost sharing structure offered to a consumer. Health insurance plans that include drug coverage reference a formulary that provides details about drugs that are covered under the plan including requirements and limitations of the coverage specific to each drug.
• Formulary: The Formulary profile of the FHIR R4 InsurancePlan resource provides general information about a formulary and acts as an organizing construct that associated FormularyItem resources point to. The Formulary combined with its associated FormularyItem and FormularyDrug resources represent a formulary list that includes the set of drugs covered and the requirements and limitations of that coverage.
• FormularyItem: The FormularyItem profile of the FHIR R4 Basic resource describes a drug's relationship to a formulary, including drug tier, prior authorization requirements, and more.
• FormularyDrug: The FormularyDrug profile of the FHIR R4 MedicationKnowledge resource provides information about a prescribable drug including its RxNorm code and dose form. Drugs not included in a formulary may not be represented by a FormularyDrug instance.

A detailed description of the relationship between the profiles in this guide can be found in the Formulary Structure section.

Several searchParameters have been defined in this guide to facilitate the anticipated use cases. See the Anticipated Client Queries section for a description of how to query for resources in support of the anticipated use cases. Below are some of the search parameters defined in this guide.

• coverage-type: Makes the coverage.type CodeableConcept of each PayerInsurancePlan accessible for query to find InsurancePlan resources that have a specific coverage type, like drug coverage.
• formulary-coverage: Makes the coverage extension formulary reference of each PayerInsurancePlan accessible for query to find InsurancePlan resources that reference specific formulary.
• coverage-area: Makes the coverageArea reference of each PayerInsurancePlan accessible for query to find an InsurancePlan by coverage location.
• formulary: Makes the extension Formulary reference of each FormularyItem accessible for query to find drugs included in a particular formulary.
• drug-tier: Makes the extension DrugTier codeableConcept of each FormularyItem accessible for query to find drugs in a specific tier.
• pharmacy-benefit-type: Makes the extension PharmacyBenefitType codeableConcept of each FormularyItem accessible for query to find drugs in available through a specific pharmacy benefit type.
• drug-name: Makes the RxNorm name of eachFormularyDrug accessible for query to find drugs by name, strength and form.

Information about searching for formulary drugs can be found in the Searching for Formulary Drugs section.

Content and Organization

The IG is organized into the following sections:

• Conformance Expectations: Conformance rules for this IG.
• Use Cases: Provides examples of how this specification can be used healthcare organizations.
• Access Methods: Describes the methods for accessing the server (authenticated or unauthenticated).
• Formulary Structure: Describes how formularies are structured in this IG including relationships between profiles.
• Bulk Data: Describes the Formulary IG approach to bulk data.
• Searching Formulary Drugs: Describes how to search for drugs by code or name.
• Additional Guidance: Provides additional guidance on using the IG.
• Anticipated Client Queries: Example queries that should be useful to implementers.
• Artifacts: The computable FHIR artifacts (profiles, value sets, etc.) for this specification.

Expected Users

This Implementation Guide is intended for insurers within the United States. Currently, many insurers make their formularies available to patients using PDFs or drug search forms through their websites. Providing formularies using FHIR may allow patients to find alternatives to reduce their medication costs, easily comparison-shop between plans, and could help insurers educate consumers about the differences between various drug tiers and pharmacy benefit types.

Disclaimers and Assumptions

• Drug Formulary Data Use: The intent of this implementation guide is to make the plan-level information regarding formulary content and cost-sharing available through a standard interface to enable consumers to have an informed discussion with their practitioner about their medication options. Most consumers will access this data through a third party application. These applications SHOULD clearly communicate to the user that the cost-sharing information in the formulary may not tell them precisely what they will pay at the pharmacy, and might not fully reflect their drug benefit. Situational inclusions, exclusions, and requirements may apply. The presence or lack of presence of a particular drug in a query response should not be construed as a guarantee of coverage or lack thereof. An insurer may only support searching for drugs that are part of the formulary or formularies in the context of the query. Insurers SHOULD provide appropriate information and disclaimers regarding the interpretation and expected use of the data made available through this guide, including how the presence or lack of presence of a drug should be interpreted.
• The FHIR MedicationKnowledge Resource is immature: The HL7 Pharmacy WG felt that MedicationKnowledge was the best choice for representing a formulary drug, even with its low maturity, since it is more suitable as an artifact and already included some of fields that would be required as extensions to the Medication resource. The MedicationKnowledge resource and FormularyDrug profile will co-evolve moving forward.
• The formulary endpoint is known to the client: This guide assumes that the formulary endpoint is known to the client. The mechanism for FHIR endpoint discovery is important, but considered out of scope for this guide.

Dependencies

Package hl7.fhir.uv.extensions.r4#5.2.0 This IG defines the global extensions - the ones defined for everyone. These extensions are always in scope wherever FHIR is being used (built Mon, Feb 10, 2025 21:45+1100+11:00)

Package hl7.fhir.uv.extensions.r4#5.3.0 This IG defines the global extensions - the ones defined for everyone. These extensions are always in scope wherever FHIR is being used (built Sat, May 16, 2026 18:32+1000+10:00)

Package hl7.fhir.uv.extensions.r4#1.0.0 This IG defines the global extensions - the ones defined for everyone. These extensions are always in scope wherever FHIR is being used (built Sun, Mar 26, 2023 08:46+1100+11:00)

Package hl7.fhir.uv.bulkdata#2.0.0 FHIR based approach for exporting large data sets from a FHIR server to a client application (built Fri, Nov 26, 2021 05:56+1100+11:00)

Package hl7.fhir.uv.sdc#3.0.0 The SDC specification provides an infrastructure to standardize the capture and expanded use of patient-level data collected within an EHR. This includes two components: * Support more sophisticated questionnaire/form use-cases such as those needed for research, oncology, pathology and other clinical domains. *Support pre-population and auto-population of EHR data into forms/questionnaires for uses outside direct clinical care (patient safety, adverse event reporting, public health reporting, etc.). (built Tue, Mar 8, 2022 18:32+0000+00:00)

Package ihe.formatcode.fhir#1.1.0 Implementation Guide for IHE defined FormatCode vocabulary. (built Thu, Feb 24, 2022 16:55-0600-06:00)

Package hl7.fhir.us.core#6.1.0 The US Core Implementation Guide is based on FHIR Version R4 and defines the minimum conformance requirements for accessing patient data. The Argonaut pilot implementations, ONC 2015 Edition Common Clinical Data Set (CCDS), and ONC U.S. Core Data for Interoperability (USCDI) v1 provided the requirements for this guide. The prior Argonaut search and vocabulary requirements, based on FHIR DSTU2, are updated in this guide to support FHIR Version R4. This guide was used as the basis for further testing and guidance by the Argonaut Project Team to provide additional content and guidance specific to Data Query Access for purpose of ONC Certification testing. These profiles are the foundation for future US Realm FHIR implementation guides. In addition to Argonaut, they are used by DAF-Research, QI-Core, and CIMI. Under the guidance of HL7 and the HL7 US Realm Steering Committee, the content will expand in future versions to meet the needs specific to the US Realm. These requirements were originally developed, balloted, and published in FHIR DSTU2 as part of the Office of the National Coordinator for Health Information Technology (ONC) sponsored Data Access Framework (DAF) project. For more information on how DAF became US Core see the US Core change notes. (built Fri, Jun 30, 2023 14:02+0000+00:00)

Package hl7.fhir.us.core#7.0.0 The US Core Implementation Guide is based on FHIR Version R4 and defines the minimum conformance requirements for accessing patient data. The Argonaut pilot implementations, ONC 2015 Edition Common Clinical Data Set (CCDS), and ONC U.S. Core Data for Interoperability (USCDI) v1 provided the requirements for this guide. The prior Argonaut search and vocabulary requirements, based on FHIR DSTU2, are updated in this guide to support FHIR Version R4. This guide was used as the basis for further testing and guidance by the Argonaut Project Team to provide additional content and guidance specific to Data Query Access for purpose of ONC Certification testing. These profiles are the foundation for future US Realm FHIR implementation guides. In addition to Argonaut, they are used by DAF-Research, QI-Core, and CIMI. Under the guidance of HL7 and the HL7 US Realm Steering Committee, the content will expand in future versions to meet the needs specific to the US Realm. These requirements were originally developed, balloted, and published in FHIR DSTU2 as part of the Office of the National Coordinator for Health Information Technology (ONC) sponsored Data Access Framework (DAF) project. For more information on how DAF became US Core see the US Core change notes. (built Wed, May 8, 2024 15:33+0000+00:00)

Package hl7.fhir.uv.extensions.r4#5.1.0 This IG defines the global extensions - the ones defined for everyone. These extensions are always in scope wherever FHIR is being used (built Sat, Apr 27, 2024 18:39+1000+10:00)

Package hl7.fhir.us.davinci-hrex#1.1.0 The Da Vinci Payer Health Record exchange (HRex) Framework/library specifies the FHIR elements used in multiple Da Vinci implementation guides. This includes FHIR profiles, functions, operations, and constraints on other specifications such as CDS-Hooks and other aspects of Da Vinci Use Cases that are common across more than a single use case.\n\nDa Vinci HRex Implementation Guide (IG) will make use of US Core profiles that are based on the FHIR R4 specification wherever practical. The HRex IG will use the HL7 FHIR Release 4/US Core STU3 specification as its base but will provide additional guidance and documentation to support implementations that follow the HL7 FHIR STU3/US Core STU2 and HL7 FHIR DSTU2/Argonaut specifications.\n\nThe HRex profiles documented in this IG will be used to exchange data between providers systems (e.g. EHRs) and other providers, payers, and third-party applications where appropriate. In addition, exchanges from payer systems to providers, other payers, and third-party applications are supported by the HRex profiles and operations.\n\nHRex may define new extensions, profiles, value sets, constraints/extension to other specification (e.g. specific CDS-Hooks) that are specific Da Vinci requirements. Where appropriate these Da Vinci specific artifacts will be promoted for incorporation into the future versions of existing standards (e.g. R4 US Core profiles) and deprecated in this guide on publication in the updated standard. (built Tue, Dec 10, 2024 16:43+0000+00:00)

Package hl7.fhir.us.davinci-pdex-plan-net#1.2.0 Da Vinci PDex Plan Net (built Tue, Feb 25, 2025 19:12+0000+00:00)

Package hl7.fhir.uv.xver-r5.r4#0.1.0 Extensions for Using Data Elements from FHIR R5 in FHIR R4 (built Fri, Mar 20, 2026 15:40+1100+11:00)

Package hl7.fhir.uv.tools.r4#1.1.2 This IG defines the extensions that the tools use internally. Some of these extensions are content that are being evaluated for elevation into the main spec, and others are tooling concerns (built Tue, Mar 24, 2026 11:13+1100+11:00)

Intellectual Property Considerations

This implementation guide and the underlying FHIR specification are licensed as public domain under the FHIR license. The license page also describes rules for the use of the FHIR name and logo.

This publication includes IP covered under the following statements.

• ISO maintains the copyright on the country codes, and controls its use carefully. For further details see the ISO 3166 web page: https://www.iso.org/iso-3166-country-codes.html
  Show Usage
  • ISO 3166-1 Codes for the representation of names of countries and their subdivisions — Part 1: Country code: AdditionalCoverageInformation, AvailabilityPeriod... Show 57 more, AvailabilityStatus, BenefitCostTypeCS, BenefitCostTypeVS, CoinsuranceOptionVS, CopayOptionVS, CostShareOptionCS, DrugTierCS, DrugTierID, DrugTierVS, Formulary, FormularyBulkDataGraphDefinition, FormularyDrug, FormularyGraphDefinition, FormularyItem, FormularyReference, InsuranceItemTypeCS, InsuranceItemTypeVS, InsurancePlanCoverage, InsurancePlanLocation, NonPackSemanticDrugVS, PayerInsurancePlan, PayerInsurancePlanBulkDataGraphDefinition, PayerInsurancePlanGraphDefinition, PharmacyBenefitType, PharmacyBenefitTypeCS, PharmacyBenefitTypeVS, PlanContactTypeCS, PlanContactTypeVS, PriorAuthorization, PriorAuthorizationNewStartsOnly, QuantityLimit, QuantityLimitDetail, SemanticDrugFormGroupVS, SemanticDrugVS, StepTherapyLimit, StepTherapyLimitNewStartsOnly, USDFBasicCode, USDFBasicDrugTier, USDFBasicFormulary, USDFBasicLastUpdated, USDFBasicPeriod, USDFBasicPharmacyBenefitType, USDFBasicStatus, USDFBasicSubject, USDFInsurancePlanCoverageArea, USDFInsurancePlanCoverageType, USDFInsurancePlanFormularyCoverage, USDFInsurancePlanLastUpdated, USDFInsurancePlanName, USDFInsurancePlanPeriod, USDFInsurancePlanStatus, USDFInsurancePlanType, USDFMedicationKnowledgeCode, USDFMedicationKnowledgeDrugName, USDFMedicationKnowledgeLastUpdated, USDFMedicationKnowledgeStatus and UsdfServerCapabilityStatement
• The UCUM codes, UCUM table (regardless of format), and UCUM Specification are copyright 1999-2009, Regenstrief Institute, Inc. and the Unified Codes for Units of Measures (UCUM) Organization. All rights reserved. https://ucum.org/trac/wiki/TermsOfUse
  Show Usage
  • Unified Code for Units of Measure (UCUM): Sample Medicare Advantage Plan A1002, Sample Medicare Advantage Plan A3001, Sample Medicare Advantage Plan A3002 and Sample Medicare Advantage Plan A3004t
• This material derives from the HL7 Terminology (THO). THO is copyright ©1989+ Health Level Seven International and is made available under the CC0 designation. For more licensing information see: https://terminology.hl7.org/license.html
  Show Usage
  • Contact entity type: PayerInsurancePlan, PlanContactTypeVS... Show 4 more, Sample Medicare Advantage Plan A1002, Sample Medicare Advantage Plan A3001, Sample Medicare Advantage Plan A3002 and Sample Medicare Advantage Plan A3004t
  • Coverage Class Codes: Coverage/InsurancePlanCoverageExample and InsurancePlanCoverage
  • Insurance plan type: Formulary, PayerInsurancePlan... Show 4 more, Sample Medicare Advantage Plan A1002, Sample Medicare Advantage Plan A3001, Sample Medicare Advantage Plan A3002 and Sample Medicare Advantage Plan A3004t
  • Organization type: Acme Health Plan
  • SubscriberPolicyholder Relationship Codes: Coverage/InsurancePlanCoverageExample
  • identifierType: Coverage/InsurancePlanCoverageExample, InsurancePlanCoverage and Patient/example
  • ActCode: Coverage/InsurancePlanCoverageExample, Formulary... Show 9 more, PayerInsurancePlan, Sample Medicare Advantage Part D Formulary D1002, Sample Medicare Advantage Part D Formulary D3001, Sample Medicare Advantage Part D Formulary D3002, Sample Medicare Advantage Part D Formulary D3004t, Sample Medicare Advantage Plan A1002, Sample Medicare Advantage Plan A3001, Sample Medicare Advantage Plan A3002 and Sample Medicare Advantage Plan A3004t
  • NullFlavor: Patient/example
  • TribalEntityUS: Patient/example
• Using RxNorm codes of type SAB=RXNORM as this specification describes does not require a UMLS license. Access to the full set of RxNorm definitions, and/or additional use of other RxNorm structures and information requires a UMLS license. The use of RxNorm in this specification is pursuant to HL7's status as a licensee of the NLM UMLS. HL7's license does not convey the right to use RxNorm to any users of this specification; implementers must acquire a license to use RxNorm in their own right.
  Show Usage
  • RxNorm: FormularyDrug, MedicationKnowledge/FormularyDrug-1000091... Show 7 more, MedicationKnowledge/FormularyDrug-1049640, MedicationKnowledge/FormularyDrug-1541228, MedicationKnowledge/FormularyDrug-209459, MedicationKnowledge/FormularyDrug-284520, NonPackSemanticDrugVS, SemanticDrugFormGroupVS and SemanticDrugVS