DDI Reference API

Drug-drug interaction reference data from FDA-approved labeling with RxNorm enrichment.

Overview

The DDI Reference API provides FDA-approved drug interaction text (warnings, contraindications, pharmacokinetic interactions) enriched with RxNorm drug classification data. Given one or more drug identifiers (RxCUI, NDC, or FDA set_id), it returns the interaction sections from the drug's FDA label along with structured drug metadata including ingredients, drug classes, and DailyMed links.

This is Tier 1 reference data: authoritative FDA text surfaced with attribution. It does not include structured DDI pair databases or severity ratings.

Endpoints

Method	Path	Description
GET	`/v1/ddi/reference/:identifier`	Single drug interaction reference
POST	`/v1/ddi/reference`	Batch lookup (up to 25 drugs)

Single Drug Lookup

Look up FDA interaction text and drug metadata for a single drug:

Look up interaction data for ramipril (RxCUI 261962)

Request

Node.js

const response = await fetch(
  "https://api.fhirfly.io/v1/ddi/reference/261962",
  {
    method: "GET",
    headers: {
    "x-api-key": "YOUR_API_KEY",
  }
  }
);

const data = await response.json();
console.log(data);

Response

JSON

{
  "data": {
    "input": "261962",
    "status": "ok",
    "drug": {
      "rxcui": "261962",
      "name": "ramipril 10 MG Oral Capsule",
      "generic_name": [
        "RAMIPRIL"
      ],
      "brand_names": [],
      "substance_name": [
        "Ramipril"
      ],
      "pharm_class_epc": [
        "Angiotensin Converting Enzyme Inhibitor [EPC]"
      ],
      "drug_classes": [
        {
          "class_id": "N0000000181",
          "class_name": "Angiotensin-converting Enzyme Inhibitors [MoA]",
          "class_type": "MoA",
          "source": "med-rt"
        },
        {
          "class_id": "N0000178477",
          "class_name": "Decreased Blood Pressure [PE]",
          "class_type": "PE",
          "source": "med-rt"
        }
      ],
      "ingredients": []
    },
    "label": {
      "spl_id": "0bfa08c7-2c74-4436-aa35-8cd37a21bd75",
      "set_id": "e8d9a115-71a7-4580-abbd-865e98b5d3f6",
      "dailymed_url": "https://dailymed.nlm.nih.gov/dailymed/drugInfo.cfm?setid=e8d9a115-71a7-4580-abbd-865e98b5d3f6",
      "sections": {
        "drug_interactions": [
          "7 DRUG INTERACTIONS..."
        ]
      }
    }
  },
  "meta": {
    "legal": {
      "license": "public_domain",
      "attribution_required": false,
      "disclaimer": "Drug interaction data is sourced from FDA-approved labeling and NLM RxNorm. This is reference information only...",
      "sources": [
        {
          "name": "FDA openFDA Drug Labels",
          "url": "https://open.fda.gov/apis/drug/label/"
        },
        {
          "name": "NLM RxNorm",
          "url": "https://www.nlm.nih.gov/research/umls/rxnorm/"
        }
      ]
    }
  }
}

Optional Sections

By default, the API returns drug_interactions and warnings sections. You can request additional sections via the sections query parameter:

GET /v1/ddi/reference/261962?sections=contraindications,boxed_warning

Section	Description
`drug_interactions`	Always included. FDA-required drug interaction text.
`warnings`	Always included. Warnings and precautions.
`contraindications`	Optional. Conditions where the drug should not be used.
`boxed_warning`	Optional. FDA black box warnings.
`pharmacokinetics`	Optional. Drug metabolism and CYP enzyme interactions.

Batch Lookup

Look up interaction data for multiple drugs in a single request (max 25):

Batch lookup for ramipril and amlodipine

Request

Node.js

const response = await fetch(
  "https://api.fhirfly.io/v1/ddi/reference",
  {
    method: "POST",
    headers: {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
    body: JSON.stringify({
    "drugs": [
      "261962",
      "197361"
    ]
  })
  }
);

const data = await response.json();
console.log(data);

Response

JSON

{
  "count": 2,
  "drugs": [
    {
      "input": "261962",
      "status": "ok",
      "drug": {
        "rxcui": "261962",
        "name": "ramipril 10 MG Oral Capsule",
        "generic_name": [
          "RAMIPRIL"
        ],
        "substance_name": [
          "Ramipril"
        ],
        "drug_classes": [
          {
            "class_id": "N0000000181",
            "class_name": "Angiotensin-converting Enzyme Inhibitors [MoA]",
            "class_type": "MoA",
            "source": "med-rt"
          }
        ]
      },
      "label": {
        "spl_id": "0bfa08c7-2c74-4436-aa35-8cd37a21bd75",
        "set_id": "e8d9a115-71a7-4580-abbd-865e98b5d3f6",
        "dailymed_url": "https://dailymed.nlm.nih.gov/dailymed/drugInfo.cfm?setid=e8d9a115-71a7-4580-abbd-865e98b5d3f6",
        "sections": {
          "drug_interactions": [
            "7 DRUG INTERACTIONS..."
          ]
        }
      }
    },
    {
      "input": "197361",
      "status": "ok",
      "drug": {
        "rxcui": "197361",
        "name": "amlodipine 5 MG Oral Tablet",
        "generic_name": [
          "AMLODIPINE BESYLATE"
        ],
        "substance_name": [
          "Amlodipine Besylate"
        ],
        "drug_classes": [
          {
            "class_id": "N0000000069",
            "class_name": "Calcium Channel Antagonists [MoA]",
            "class_type": "MoA",
            "source": "med-rt"
          }
        ]
      },
      "label": {
        "spl_id": "da6d6dd4-5c23-4852-9e77-ee0553de4044",
        "set_id": "a74239bf-4684-424c-ba4e-6087e363265b",
        "dailymed_url": "https://dailymed.nlm.nih.gov/dailymed/drugInfo.cfm?setid=a74239bf-4684-424c-ba4e-6087e363265b",
        "sections": {
          "drug_interactions": [
            "7 DRUG INTERACTIONS..."
          ]
        }
      }
    }
  ],
  "meta": {
    "legal": {
      "license": "public_domain",
      "attribution_required": false,
      "disclaimer": "Drug interaction data is sourced from FDA-approved labeling and NLM RxNorm...",
      "sources": [
        {
          "name": "FDA openFDA Drug Labels",
          "url": "https://open.fda.gov/apis/drug/label/"
        },
        {
          "name": "NLM RxNorm",
          "url": "https://www.nlm.nih.gov/research/umls/rxnorm/"
        }
      ]
    }
  }
}

Per-Drug Status

Each drug in a batch response includes a status field:

Status	Description
`ok`	Drug found with FDA label and interaction data
`not_found`	No FDA label found for this identifier
`invalid`	The identifier format was not recognized

Use Cases

AI-Powered Drug Interaction Screening

Send a patient's medication list to the DDI Reference API, then use the FDA interaction text with an LLM to identify potential drug-drug interactions with authoritative source text and DailyMed links.

Clinical Decision Support

Surface FDA-approved interaction warnings at the point of prescribing. The drug_interactions section contains the full FDA-mandated interaction text with specific clinical guidance.

Pharmacy Workflow

When dispensing, look up the interaction profiles of all medications in a patient's regimen. Drug class data (MoA, PE, EPC) helps identify mechanism-based interaction risks.

Notes

No shapes: The DDI Reference API returns a fixed response structure. There is no shape query parameter.
Identifiers: Accepts RxCUI (preferred), NDC, or FDA set_id. RxCUI provides the best match rate.
Batch limit: Maximum 25 drugs per POST request. Exceeding this returns 413.
Data sources: FDA label text comes from DailyMed SPL data; drug metadata comes from RxNorm.
Not a DDI database: This API surfaces reference text from individual drug labels. It does not provide structured DDI pair lookups or severity classifications.

Required Scopes

ddi.read - Single and batch drug interaction reference lookups