Response Shapes

FHIRfly APIs support three response shapes to optimize for different use cases.

Overview

Use the shape query parameter to control the amount of data returned:

GET /v1/ndc/0069-0151-01?shape=compact
GET /v1/ndc/0069-0151-01?shape=standard
GET /v1/ndc/0069-0151-01?shape=full

Shape Comparison

Shape	Use Case	Data Included
compact	Lists, autocomplete	Code, display name, status
standard	Most integrations	Core structured data
full	AI agents, auditing	Everything + provenance

Compact Shape

Minimal data for lists and autocomplete scenarios. Optimized for bandwidth.

Node.js

const result = await client.ndc.lookup("0069-0151-01", { shape: "compact" });
console.log(result.data);

{
  "data": {
    "ndc": "0069-0151-01",
    "type": "package",
    "name": "Lipitor",
    "generic": "Atorvastatin Calcium",
    "labeler": "Pfizer Laboratories Div Pfizer Inc",
    "active": true
  },
  "meta": {
    "legal": {
      "license": "public_domain"
    }
  }
}

Standard Shape (Default)

Core structured data for most integration scenarios.

Node.js

const result = await client.ndc.lookup("0069-0151-01");
// shape defaults to "standard"
console.log(result.data);

{
  "data": {
    "ndc": "0069-0151-01",
    "type": "package",
    "brand_name": "Lipitor",
    "generic_name": "Atorvastatin Calcium",
    "labeler_name": "Pfizer Laboratories Div Pfizer Inc",
    "dosage_form": "TABLET, FILM COATED",
    "route": ["ORAL"],
    "strength": "ATORVASTATIN CALCIUM 10 mg/1",
    "is_active": true,
    "ndc11_hyph": "0069-0151-01",
    "product_ndc": "0069-0151"
  },
  "meta": {
    "legal": {
      "license": "public_domain",
      "citation": "FDA NDC Directory"
    }
  }
}

Full Shape

Complete data with provenance information. Designed for AI agents that need source attribution.

Node.js

const result = await client.ndc.lookup("0069-0151-01", { shape: "full" });
console.log(result.data);
console.log(result.meta.source); // provenance info

{
  "data": {
    "ndc": "0069-0151-01",
    "type": "package",
    "brand_name": "Lipitor",
    "generic_name": "Atorvastatin Calcium",
    "labeler_name": "Pfizer Laboratories Div Pfizer Inc",
    "dosage_form": "TABLET, FILM COATED",
    "route": ["ORAL"],
    "strength": "ATORVASTATIN CALCIUM 10 mg/1",
    "is_active": true,
    "marketing_category": "NDA",
    "dea_schedule": null,
    "active_ingredients": [ /* ... */ ],
    "pharm_class": [ /* ... */ ]
  },
  "meta": {
    "source": {
      "name": "FDA NDC Directory",
      "url": "https://www.fda.gov/drugs/drug-approvals-and-databases/national-drug-code-directory",
      "version": "2026-01-01",
      "fhirfly_updated_at": "2026-01-02T03:00:00Z",
      "fhirfly_etl_version": "1.0.0"
    },
    "legal": {
      "license": "public_domain",
      "citation": "U.S. Food and Drug Administration. National Drug Code Directory.",
      "attribution_required": false,
      "commercial_use": true
    }
  }
}

Batch Responses

Response shapes also apply to batch requests. Pass the shape query parameter on the batch endpoint:

POST /v1/ndc/_batch?shape=full

Batch — Compact

{
  "count": 2,
  "results": [
    {
      "input": "0069-0151-01",
      "ndc": "0069-0151-01",
      "status": "ok",
      "data": {
        "ndc": "0069-0151-01",
        "name": "Lipitor",
        "active": true
      }
    },
    {
      "input": "60505-0081-00",
      "ndc": "60505-0081-00",
      "status": "ok",
      "data": {
        "ndc": "60505-0081-00",
        "name": "Sotalol Hydrochloride",
        "active": true
      }
    }
  ],
  "meta": {
    "legal": {
      "license": "public_domain"
    }
  }
}

Batch — Standard (Default)

{
  "count": 2,
  "results": [
    {
      "input": "0069-0151-01",
      "ndc": "0069-0151-01",
      "status": "ok",
      "data": {
        "ndc": "0069-0151-01",
        "brand_name": "Lipitor",
        "generic_name": "Atorvastatin Calcium",
        "labeler_name": "Pfizer Laboratories Div Pfizer Inc",
        "dosage_form": "TABLET, FILM COATED",
        "route": ["ORAL"],
        "is_active": true
      }
    }
  ],
  "meta": {
    "legal": {
      "license": "public_domain",
      "citation": "FDA NDC Directory"
    }
  }
}

Batch — Full

The full shape includes meta.source with provenance information alongside meta.legal:

{
  "count": 2,
  "results": [
    {
      "input": "0069-0151-01",
      "ndc": "0069-0151-01",
      "status": "ok",
      "data": {
        "ndc": "0069-0151-01",
        "brand_name": "Lipitor",
        "generic_name": "Atorvastatin Calcium",
        "labeler_name": "Pfizer Laboratories Div Pfizer Inc",
        "dosage_form": "TABLET, FILM COATED",
        "route": ["ORAL"],
        "is_active": true,
        "marketing_category": "NDA",
        "dea_schedule": null
      }
    }
  ],
  "meta": {
    "source": {
      "name": "FDA NDC Directory",
      "url": "https://www.fda.gov/drugs/drug-approvals-and-databases/national-drug-code-directory",
      "version": "2026-01-01",
      "fhirfly_updated_at": "2026-01-02T03:00:00Z",
      "fhirfly_etl_version": "1.0.0"
    },
    "legal": {
      "license": "public_domain",
      "citation": "U.S. Food and Drug Administration. National Drug Code Directory.",
      "attribution_required": false,
      "commercial_use": true
    }
  }
}

The meta.source field is only present when shape=full is used. It provides:

name — The canonical name of the data source
url — Link to the authoritative source
version — Version or release identifier of the source data
fhirfly_updated_at — When FHIRfly last ingested this data
fhirfly_etl_version — ETL pipeline version used for ingestion

Display Modifier

Add human-readable formatted fields with include=display:

GET /v1/ndc/0069-0151-01?include=display

This adds a display field to each object with a pre-formatted human-readable string.

MCP Default Shape

When accessing FHIRfly through MCP (Model Context Protocol), the default shape is full to provide AI assistants with complete provenance information for accurate citations.

Choosing a Shape

Scenario	Recommended Shape
Autocomplete dropdown	`compact`
Form field validation	`compact`
Patient record display	`standard`
EHR integration	`standard`
AI agent / LLM	`full`
Compliance audit	`full`
Research / analysis	`full`