Test Sandbox APIs
Using Data
API Reference
Capability Statement

Drug Formulary

Humana offers a Drug Formulary service that enables members to see which medications are covered by their Humana insurance plan. This service includes multiple FHIR APIs: MedicationKnowledge, List, and Medication.

The List resource enables the user to retrieve information about the plan and corresponding formulary.

The MedicationKnowledge resource offers details about each medication within the formulary.

Though not required in order to retrieve Drug Formulary information, Humana also provides a Medication resource, where a user can retrieve additional information for a given medication code.

Below, we have outlined the steps required to enable members to understand what medications are covered by their plan’s formulary and important details about those medications (for example: drug tiers, whether prior authorization and/or step therapy are required, and whether the medication qualifies for mail order).

These APIs follow the HL7 R4 FHIR specification, as well as the DaVinci DrugFormulary specifications.

Step 1

Identify the member’s drug plan by calling the /Coverage resource to retrieve the drug plan’s corresponding planID. Please note, an access token is required to retrieve data from this endpoint.

URL


Headers

ACCEPT application/json
AUTHORIZATION Bearer {ACCESS_TOKEN}

Sample Request

curl -X GET \
https://fhir.humana.com/api/ \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {your access token}' \

In the response, all of the member’s coverages will be returned. In order to identify the member’s drug plan specifically, look for “status”: “active” and type.coding.code = “DRUGPOL”.

Response Snippet – DRUGPOL

        "status": "active",
        "type": {
          "coding": [
            {
              "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
              "code": "DRUGPOL",
              "display": "drug policy"
            }
          ],
          "text": "drug policy"
        }

Once you’ve identified the member’s drug plan, in the same response, locate the corresponding class.value to get the member’s planID (for example, “H5216-107-000-2021”).

Response Snippet – PLANID

        "class": [
  {
    "type": {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/coverage-class",
          "code": "subplan"
        }
      ]
    },
    "value": "H5216-107-000-2021"
  }
]

Step 2

Now you can use the planID to identify all the medications in the drug formulary for this member’s plan. To do this, call the /List resource with the planID to retrieve the drug formulary, which contains references to the MedicationKnowledge resources. Please note, an access token is not required for this API, but you are required to pass the DaVinci Drug Formulary profile as shown below.

URL


Sample Request

curl -X GET \
https://fhir.humana.com/api/List?_profile=http://hl7.org/fhir/us/davinci-drug-formulary/StructureDefinition/usdf-CoveragePlan&identifier=H5216-107-000-2021 \

Calling the List API will return a bundle of List resources that each contain up to 5000 MedicationKnowledge references. Please note, there may be between 30,000-40,000 medications in a given formulary. In the response, look for entry.item.reference to find the medication reference (example: MedicationKnowledge/59f9259a5de5ad1ba9a5340f7e6e4d0e50a2556fbd254054e4a799f96fdcfea5)

Response Snippet – MedicationKnowledge

         "entry": [
          {
            "item": {
              "reference": "MedicationKnowledge/59f9259a5de5ad1ba9a5340f7e6e4d0e50a2556fbd254054e4a799f96fdcfea5"
            }
          },
          {
            "item": {
              "reference": "MedicationKnowledge/5ed6d3d0338e81b8bee0498132a036058c872924c2d0e43b11b8ef1c734ef9d5"
            }
          },
          {
            "item": {
              "reference": "MedicationKnowledge/64f7301b26f2ead88412134ee81ab899fd81ca55c5b8d4273e3f6f3261d1cae2"
            }
          },

To ensure you have retrieved all possible MedicationKnowledge references, paginate where applicable. Follow the links in link.url where link.relation=“next”.

Response Snippet – Pagination Example

         "link": [
    {
        "relation": "next",
        "url": "https://fhir.humana.com/api/List?_profile=http://hl7.org/fhir/us/davinci-drug-formulary/StructureDefinition/usdf-CoveragePlan&identifier=H4461-022-000-2021&_count=8&ct=W3sidG9rZW4iOm51bGwsInJhbmdlIjp7Im1pbiI6IjA1QzFEMCIsIm1heCI6IjA1QzFEMTgwIn19XQ=="
    },

Step 3

Use the MedicationKnowledge resource referenced in the List response to identify the Drug Name, Tier, and other details about a specific medication in relation to the member’s plan.

URL


Sample Request

curl -X GET \
https://fhir.humana.com/api/MedicationKnowledge/59f9259a5de5ad1ba9a5340f7e6e4d0e50a2556fbd254054e4a799f96fdcfea5 \

Sample Response

         {
    "resourceType": "MedicationKnowledge",
    "id": "59f9259a5de5ad1ba9a5340f7e6e4d0e50a2556fbd254054e4a799f96fdcfea5",
    "meta": {
        "versionId": "2",
        "lastUpdated": "2021-06-29T20:49:30.052+00:00"
    },
    "extension": [
        {
            "url": "http://hl7.org/fhir/us/davinci-drug-formulary/StructureDefinition/usdf-DrugTierID-extension",
            "valueCodeableConcept": {
                "coding": [
                    {
                        "system": "https://fhir.humana.com/documentation/glossary/DrugTierID",
                        "code": "2",
                        "display": "Generic"
                    }
                ]
            }
        },
        {
            "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": true
        },
        {
            "url": "http://hl7.org/fhir/us/davinci-drug-formulary/StructureDefinition/usdf-PlanID-extension",
            "valueString": "H5216-107-000-2021"
        }
    ],
    "code": {
        "coding": [
            {
                "system": "https://fhir.humana.com/documentation/glossary/ndc11",
                "code": "00781537701"
            }
        ]
    },
    "status": "active"
}