Contact Us

Formulary API

Formulary API Use Cases

This section provides examples and guidance for querying the Opala PDex Formulary API using supported search parameters and criteria. Developers can use these search operations to retrieve formulary and payer insurance plan information, including drug coverage details, formulary associations, and related plan data. These examples are designed to help simplify integration and support efficient access to formulary information through standardized FHIR based queries.

Find a Formulary

Use type to find a formulary.

Example GET request:

GET {{base_url}}/InsurancePlan?type=http://terminology.hl7.org/CodeSystem/v3-ActCode|DRUGPOL

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.

Example GET request:

GET {{base_url}}/InsurancePlan?type=http://hl7.org/fhir/us/davinci-pdex-plan-net/CodeSystem/InsuranceProductTypeCS|

Find All PayerInsurancePlans by Coverage Area

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

Example GET request:

GET {{base_url}}/InsurancePlan?coverage-area=Location/[LocationID]

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.

Example GET request:

GET {{base_url}}/InsurancePlan?coverage-type=http://terminology.hl7.org/CodeSystem/v3-ActCode|DRUGPOL

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.

Example GET request:

GET {{base_url}}/InsurancePlan?formulary-coverage=InsurancePlan/[formularyID]

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.

Example GET request:

GET {{base_url}}/metadata?_format=[string]&_pretty=[boolean]&_summary=count&_elements=[element1,element2]

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.

Example GET request:

GET {{base_url}}/MedicationKnowledge/:rid?_summary=count&_format=[string]&_pretty=[boolean]&_elements=[element1,element2]

Find a Formulary by Identifier

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

Example GET request:

GET {{base_url}}/InsurancePlan?type=http://terminology.hl7.org/CodeSystem/v3-ActCode|DRUGPOL&identifier=[identifier]

Find All FormularyItems and FormularyDrugs in a Formulary

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

Example GET request:

GET {{base_url}}/Basic?code=http://hl7.org/fhir/us/davinci-drug-formulary/CodeSystem/usdf-InsuranceItemTypeCS|formulary-item&formulary=InsurancePlan/[formularyID]&_include=Basic:subject

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.

Example GET request:

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

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.

Example GET request:

GET {{base_url}}/Basic?code=http://hl7.org/fhir/us/davinci-drug-formulary/CodeSystem/usdf-InsuranceItemTypeCS|formulary-item&formulary=InsurancePlan/[formularyID]&subject:MedicationKnowledge.drug-name=[drug-name]&_include=Basic:subject

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.

Example GET request:

GET {{base_url}}/Basic?code=http://hl7.org/fhir/us/davinci-drug-formulary/CodeSystem/usdf-InsuranceItemTypeCS|formulary-item&formulary=InsurancePlan/[formularyID]&pharmacy-benefit-type=http://hl7.org/fhir/us/davinci-drug-formulary/CodeSystem/usdf-PharmacyBenefitTypeCS|[pharmacy benefit type]&_include=Basic:subject

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.

Example GET request:

GET {{base_url}}/Basic?code=http://hl7.org/fhir/us/davinci-drug-formulary/CodeSystem/usdf-InsuranceItemTypeCS|formulary-item&formulary=InsurancePlan/[formularyID]&drug-tier=http://hl7.org/fhir/us/davinci-drug-formulary/CodeSystem/usdf-DrugTierCS|[drug tier]&_include=Basic:subject

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.

Example GET request:

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

Find a Formulary by Name

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

Example GET request:

GET {{base_url}}/InsurancePlan?type=http://terminology.hl7.org/CodeSystem/v3-ActCode|DRUGPOL&name=[name]

Read the Past States of a Resource (History)

Retrieve the history of a resource. The parameters work as follows:

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

Example GET request:

GET {{base_url}}/_history?_summary=count&_format=[string]&_pretty=[boolean]&_elements=[element1,element2]&_count=[number]&_since=[since]&_at=[at]&_list=[string]

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, represents a formulary list that includes the set of drugs covered and the requirements and limitations of the coverage.

Example:

{
    "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 have been scrambled.

Additional Resources

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 RXCUI codes.

Example:

{
    "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.

Additional Resources

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 plan’s formulary.

Notes:

  • Basic.extension:usdf-DrugTier-extension : Opala has extended the valueset to include the custom drug tiers that the customer provides its members.
  • Basic.extension:usdf-PharmacyBenefitType-extension : Opala has extended the valueset to include "unknown" if the information provided by the customer does not fit into the valueset

Example:

{
    "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",
            "valueBoolean": 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 have been scrambled.

Additional Resources

Formulary Structure

Formularies in the United States are typically published by health insurers on an annual basis, with minor updates throughout the year. Each formulary contains a set of drugs along with any limits or requirements.

Drugs are placed into tiers, and the number and purpose of tiers vary across payers. Each tier has an associated cost-sharing model, which may include deductibles and/or coinsurance components for drugs in that tier when purchased through various pharmacy benefit types.

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

Search Parameters

The following search parameters can be used with this API: