Opala's PDex Formulary API

This API enables you to use a FHIR interface to retrieve a health insurer's drug formulary information for patients, consumers and prescribers.

The current iteration of Opala's PDex Formulary API is an unauthenticated API, which means that it exchanges formulary data exclusively without including any PHI or PII.

Resource Profiles

Payer Insurance Plan

The Payer Insurance Plan 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.

Links

• Resource Profile: Payer Insurance Plan
• JSON Example

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 the coverage.

Links

• Resource Profile: Formulary
• JSON Example

Example: Formulary

{
    "resourceType" : "InsurancePlan",
    "id" : "9cc6fd07-97c9-476e-b198-76818bd4e523",
    "meta" : {
        "lastUpdated" : "2023-05-04T11:51:03.000+00:00",
        "profile" : [
        "http://hl7.org/fhir/us/davinci-drug-formulary/StructureDefinition/usdf-Formulary"
        ]
    },
    "identifier" : [
        {
        "system": "http://opala.com/navitus/formulary",
        "value" : "11958"
        }
    ],
    "status" : "active",
    "type" : [
        {
        "coding" : [
            {
            "system" : "http://terminology.hl7.org/CodeSystem/v3-ActCode",
            "code" : "DRUGPOL"
            }
        ]
        }
    ],
    "name" : "Brighton Medicare Plus (HMO D-SNP) Medicare Part D Plan"
}

Note: The ID and name values in the example above has been scrambled.

Formulary Item

The Formulary Item profile of the FHIR R4 Basic resource describes a drug's relationship to a drug plan — including drug tier, prior authorization requirements, etc. The set of FormularyItem resources associated with a particular drug plan represents the drug plans formulary.

Links

• Resource Profile: Formulary Item
• JSON Example

Example: FormularyItem

{
    "resourceType" : "Basic",
    "id" : "9cc6fd07-97c9-476e-b198-76818bd4e523",
    "meta" : {
        "lastUpdated" : "2023-05-04T11:51:03.000+00:00",
        "profile" : [
        "http://hl7.org/fhir/us/davinci-drug-formulary/StructureDefinition/usdf-FormularyItem"
        ]
    },
    "extension" : [
        {
        "url" : "http://hl7.org/fhir/us/davinci-drug-formulary/StructureDefinition/usdf-FormularyReference-extension",
        "valueReference" : {
            "reference" : "InsurancePlan/Formulary-89f2bc60-970f-34d8-8d7b-315757cwse97"
        }
        },
        {
        "url" : "http://hl7.org/fhir/us/davinci-drug-formulary/StructureDefinition/usdf-AvailabilityStatus-extension",
        "valueCode" : "active"
        },
        {
        "url" : "http://hl7.org/fhir/us/davinci-drug-formulary/StructureDefinition/usdf-PharmacyBenefitType-extension",
        "valueCodeableConcept" : {
            
            "text" : "unavailable"
        }
        },
        {
        "url" : "http://hl7.org/fhir/us/davinci-drug-formulary/StructureDefinition/usdf-DrugTierID-extension",
        "valueCodeableConcept" : {
            
                "text" : "1"

            }
        },
        {
        "url" : "http://hl7.org/fhir/us/davinci-drug-formulary/StructureDefinition/usdf-PriorAuthorization-extension",
        "valueBoolean" : false
        },
        {
        "url" : "http://hl7.org/fhir/us/davinci-drug-formulary/StructureDefinition/usdf-StepTherapyLimit-extension",
        "valueBoolea" : false
        },
        {
        "url" : "http://hl7.org/fhir/us/davinci-drug-formulary/StructureDefinition/usdf-QuantityLimit-extension",
        "valueBoolean" : false
        }
    ],
    "code" : {
        "coding" : [
        {
            "system" : "http://hl7.org/fhir/us/davinci-drug-formulary/CodeSystem/usdf-InsuranceItemTypeCS",
            "code" : "formulary-item",
            "display" : "Formulary Item"
        }
        ]
    },
    "subject" : {
        "reference" : "MedicationKnowledge/FormularyDrug-73be5e32-b55a-4e7v-2798-2c210020df45"
    }
}

Note: The ID, Formulary, and FormularyDrug values in the example above has been scrambled.

Formulary Drug

The Formulary Drug profile of the FHIR R4 MedicationKnowledge resource provides information about a drug's relationship to a formulary, including its RxNorm code and dose form.

Opala uses http://www.nlm.nih.gov/research/umls/rxnorm as the system for the semantic drug code. This is the system for the RXCUI codes.

Links

• Resource Profile: Formulary Drug
• JSON Example

Example: RxCUI Semantic Drug Code + Group Code

{
    "resourceType": "MedicationKnowledge",
    "id": "73be5e32-b55a-4e7v-2798-2c210020df45",
    "meta": {
        "lastUpdated": "2023-05-04T11:51:03.000+00:00",
        "profile": [
        "http://hl7.org/fhir/us/davinci-drug-formulary/StructureDefinition/usdf-FormularyDrug"
        ]
    },
    "code": {
        "coding": [
        {
        "system": "http://www.nlm.nih.gov/research/umls/rxnorm",
        "code": "313996",
        "display": "gentamicin 40 MG/ML Injectable Solution"
        },
    {
        "system": "http://www.nlm.nih.gov/research/umls/rxnorm",
        "code": "1870215",
        "display": "gentamicin Injectable Product"
        }
    ]
    },
        "status": "active"
}

Note: The ID value in the example above has been scrambled.

Formulary Structure

Formularies in the United States are normally published by health insurers on an annual basis, with minor updates during the year. Each formulary contains a set of drugs with their limits or requirements. Drugs are placed into tiers; 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).

Supported Capabilities

This table provides a summary of the supported capabilities of the PDex Formulary API.

Resource Type	Supported Interactions	Supported Profiles	Supported Searches	Supported _includes	Supported _revincludes	Supported Operations
InsurancePlan	create search-type read vread update patch delete history-instance history-type	Payer Insurance Plan, Formulary	_id _lastUpdated identifier status period type name coverage-type formulary-coverage coverage-area	formulary-coverage
Basic	create search-type read vread update patch delete history-instance history-type	Formulary Item	_id _lastUpdated code subject status period formulary pharmacy-benefit-type drug-tier	subject, formulary
MedicationKnowledge	create search-type read vread update patch delete history-instance history-type	Formulary Drug	_id _lastUpdated status code drug-name doseform
Location	create search-type read vread update patch delete history-instance history-type	Insurance Plan Location	_id _lastUpdated address address-city address-state address-postalcode

Artifacts

These links provide lists of the FHIR artifacts defined as part of Opala's PDex Formulary API. The artifacts define the specific capabilities that different types of systems are expected to have.

• Search Parameter Behavior . This section defines the properties by which a RESTful server can be searched. The parameters can also be used to sort and include related resources.
• Resource Profile Structures . This section defines the constraints placed on FHIR resources in this API.
• Extension Definitions Structures . This section defines the constraints placed on FHIR data types in this API.
• Value Sets Terminology . This section defines the sets of codes used by this API.
• Code Systems Terminology . This section defines new code systems used by this API.
• Example Instances . This section describes example instances that show what data is produced and consumed by this API.

Search Parameters

The following search parameters can be used with this API:

• PayerInsurancePlan & Formulary (InsurancePlan)
  — PayerInsurancePlan - Detailed Descriptions
• FormularyItem (Basic)
  — FormularyItem - Detailed Descriptions
• FormularyDrug (MedicationKnowledge)
  — FormularyDrug - Detailed Descriptions
• InsurancePlanLocation (Location)
  — InsurancePlanLocation - Detailed Descriptions

Using the PDex Formulary Sandbox with Postman

You can use Opala's PDex Formulary Sandbox along with Postman to test the API. The Sandbox provides complete functionality. Use the sandbox environment to test your application's connectivity and validate all aspects of your application against the test data. Opala recommends validating your application against the sandbox environment before registering your application. To access the Sandbox, see Using Postman below.

The base URL for Opala's PDex Formulary Sandbox is https://public.cert.opalahealth.io/formulary/v1/fhir/r4/sandbox/

The metadata URL for Opala's PDex Formulary Sandbox is https://public.cert.opalahealth.io/formulary/v1/fhir/r4/sandbox/metadata.

Note: Your implementation of the Production environment may differ from the Sandbox. The Production environment is defined by the source data provided to Opala which may not be the same as the Sandbox data.

About Postman

Postman is an app designed to assist in API development. It is available as a desktop app and on the web.

A Postman collection is a group of API requests that are already saved in the Postman app and arranged in folders. Opala's Formulary Sandbox is available as a Postman collection called Opala Formulary Collection Sandbox ( or PDex Formulary) that you can run in your Postman app.

Downloading Opala's Postman Collection

Use the Run in Postman button below to import a copy of Opala's PDex Collection Sandbox.

When you select the Run in Postman button, the code launches a process that forks the Opala Collection and installs a copy of it locally. Because Opala forks the collection, you do not need to work in Scratch Pad in order to maintain security.

Working with the Opala Collection

After you have downloaded the PDex Formulary collection, make sure to select public.cert from the Environment drop-down. This ensures that the {{base_url}} variable runs successfully.

For each resource profile in the collection, you can expand the description beneath the title in Postman for more information by clicking the caret icon. For example, the image below shows Opala's Sandbox Provider Directory API.

Within each folder are pre-defined requests you can run using Postman. For example, you can use a drug code to find all FormularyItems and their respective FormularyDrugs within a specific formulary with that specific drug code:

The complete URL for the request is:

GET {{base_url}}/Basic?code=http://hl7.org/fhir/us/davinci-drug-formulary/CodeSystem/usdf-InsuranceItemTypeCS|formulary-item&formulary=InsurancePlan/Formulary-10207VA0380001&subject:MedicationKnowledge.code=http://www.nlm.nih.gov/research/umls/rxnorm|1000091&_include=Basic:subject

This request returns a bundle that includes all FormularyDrugs in the FormularyItem "Formulary-10207VA0380001" with an rxnorm code of "1000091".

Anticipated Queries

The following presents some of the queries you can run against the PDex Formulary API.

Retrieve Opala's PDex Formulary Capability Statement

Opala's Formulary Capability Statement (metadata) documents the set of capabilities and behaviors available from the Formulary service implementation. This Capability Statement includes information about supported FHIR resources and security protocols and should be used by applications as the set of rules the application should follow.

Read the Past States of a Resource (History)

Retrieve the history of a resource. The _summary parameter requests that the server return a designated subset of the resource; the _since parameter requests that the server only include resource versions that were created at or after the given instant in time; the _at parameter requests that the server only include resource versions that were current at some point during the time period specified in the date time value; and the _list parameter requests that the server only include resource versions that are referenced in the specified list (current list references are allowed).

Read the Current State of a Resource

Retrieve the current state of a resource. The _summary parameter requests that the server return a designated subset of the resource; and the _elements parameter requests that the server return a collection of elements from the resource.

Find All PayerInsurancePlans

PayerInsurancePlans may have any number of types found in the http://hl7.org/fhir/us/davinci-pdex-plan-net/CodeSystem/InsuranceProductTypeCS CodeSystem. Each PayerInsurancePlan conformant will have one or more memberPlan extensions that reference a formulary.

Find All Insurance Plans with Drug Coverage

Use a coverage.type of http://terminology.hl7.org/CodeSystem/v3-ActCode|DRUGPOL to search for a PayerInsurancePlan with drug coverage.

Find All Formulary Resources

Use type to find a formulary.

Find a Formulary by Its Name

Use type and name to find a formulary using its name.

Find a Formulary by Its Identifier

Use type and identifier to find a formulary using its identifier.

Find All PayerInsurancePlans by a Formulary

Use formulary.coverage to find all PayerInsurancePlans that include a coverage with a specific formulary by the formulary's ID.

Find All PayerInsurancePlans by Coverage Area

Use coverage.area to find all PayerInsurancePlans with a coverage area location by the location's ID.

Find All FormularyItems and FormularyDrugs in a Formulary

Use a Formulary ID to find all FormularyItems and their respective FormularyDrugs in a specific formulary.

Find All FormularyItems and FormularyDrugs in a Formulary by Drug Tier

Use a Formulary ID and specified drug tier to find all FormularyItems and their respective FormularyDrugs within a specific formulary and drug-tier.

Find All FormularyItems and FormularyDrugs in a Formulary by Pharmacy Benefit Type

Use a Formulary ID and pharmacy-benefit-type to find all FormularyItems and their respective FormularyDrugs in a specific formulary with a specific pharmacy benefit type.

Find All FormularyItems and FormularyDrugs in a Formulary by Drug Name

Use a Formulary ID and drug-name to find all FormularyItems and their respective FormularyDrugs in a specific formulary with a specific drug name.

Find All FormularyItems and FormularyDrugs in a Formulary by Drug Code

Use a Formulary ID and a drug code to find all FormularyItems and their respective FormularyDrugs in a specific formulary using a drug's RxNorm code.

Find All FormularyItems and Covering Formulary Resources by Drug Code

To find all FormularyItems and the Formulary resources that include them for a specific drug, use the RxNorm code.