FHIRfly
Dashboard

Search APIs Overview

FHIRfly Search APIs let you find healthcare data when you don't know the exact code. Use full-text search with filters to discover drugs, providers, lab codes, and more.

Search vs. Lookup

Feature Lookup APIs Search APIs
Use case You have the code You need to find the code
Input Exact code (NDC, NPI, etc.) Text query + optional filters
Results Single record Multiple matching records
Example GET /v1/ndc/60505008100 GET /v1/ndc/search?q=metformin

Available Search Endpoints

API Endpoint Description
NDC GET /v1/ndc/search Search drug products by name, ingredient, strength
NPI GET /v1/npi/search Search healthcare providers by name, specialty, location
RxNorm GET /v1/rxnorm/search Search drug terminology by name, ingredient, term type
LOINC GET /v1/loinc/search Search lab codes by name, component, class
ICD-10 GET /v1/icd10/search Search diagnosis and procedure codes
CVX GET /v1/cvx/search Search vaccine codes
MVX GET /v1/mvx/search Search vaccine manufacturer codes
FDA Labels GET /v1/fda-label/search Search drug labels by name, manufacturer, substance
SNOMED CT GET /v1/snomed/search Search clinical concepts by text, category, semantic tag

Common Features

All search endpoints share these capabilities:

Text Search with Fuzzy Matching

Search queries automatically handle typos and variations:

Node.js
// Finds "lisinopril" even with typo
const results = await client.ndc.search({ q: "lisnopril" });

Filters

Narrow results with type-specific filters:

Node.js
const results = await client.ndc.search({
  q: "metformin",
  dosage_form: "TABLET",
  is_active: true
});

Faceted Results

Search responses include facets showing the distribution of results:

{
  "facets": {
    "dosage_form": {
      "TABLET": 186,
      "CAPSULE": 42,
      "SOLUTION": 15
    },
    "product_type": {
      "HUMAN PRESCRIPTION DRUG": 170,
      "DRUG FOR FURTHER PROCESSING": 16
    }
  },
  "items": [...],
  "total": 186
}

Use facets to build filter UIs or refine searches programmatically.

Pagination

Control result sets with limit and page:

Parameter Default Maximum Description
limit 20 100 Results per page
page 1 100 Page number

Maximum accessible results: 10,000 (100 pages × 100 items). For larger datasets, use filters to narrow your search.

Response Shapes

Control response detail level with the shape parameter:

Shape Description
compact Minimal fields for lists (default for search)
standard Core structured data
full Complete data with provenance

Response Format

All search responses follow this structure:

{
  "items": [
    { /* result 1 */ },
    { /* result 2 */ }
  ],
  "total": 186,
  "has_more": true,
  "page": 1,
  "limit": 20,
  "facets": { /* aggregations */ },
  "meta": {
    "legal": {
      "source_name": "FDA NDC Directory",
      "license": "public_domain",
      "citation": "..."
    }
  }
}

Authentication

Search APIs require the same authentication as lookup APIs:

Node.js
import { Fhirfly } from "@fhirfly-io/terminology";

const client = new Fhirfly({ apiKey: "YOUR_API_KEY" });
const results = await client.ndc.search({ q: "advil" });

Required Scopes

Each search endpoint requires a dedicated search scope:

Endpoint Required Scope
/v1/ndc/search ndc.search
/v1/npi/search npi.search
/v1/rxnorm/search rxnorm.search
/v1/loinc/search loinc.search
/v1/icd10/search icd10.search
/v1/cvx/search cvx.search
/v1/mvx/search mvx.search
/v1/fda-label/search fda-label.search
/v1/snomed/search snomed.search

Search scopes are separate from read scopes because search operations use more compute resources. New credentials include both read and search scopes by default.