NPI Search API

Search the CMS National Provider Identifier (NPI) registry for healthcare providers and organizations.

Endpoint

GET /v1/npi/search

Quick Start

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

const client = new Fhirfly({ apiKey: "YOUR_API_KEY" });

// Search for cardiologists in California
const results = await client.npi.search({
  q: "cardiology",
  state: "CA"
});

console.log(`Found ${results.total} providers`);
for (const item of results.items) {
  console.log(`${item.npi}: ${item.name} (${item.location})`);
}

Parameters

Text Search

At least one text search parameter is required.

Filters

Pagination & Response

Example Response

{
  "facets": {
    "entity_type": {
      "organization": 223
    },
    "state": {
      "CA": 223
    }
  },
  "has_more": true,
  "items": [
    {
      "active": true,
      "location": "ORANGE, CA",
      "name": "PSF Cardiology",
      "npi": "1447440417",
      "specialty": "Specialist",
      "type": "organization"
    },
    {
      "active": true,
      "location": "ORANGE, CA",
      "name": "Providence - Cardiology",
      "npi": "1043401870",
      "specialty": "Pediatric Cardiology Physician",
      "type": "organization"
    }
  ],
  "limit": 2,
  "meta": {
    "legal": {
      "attribution_required": false,
      "citation": "CMS NPPES. Accessed 2026-01-28 via FHIRfly.",
      "license": "public_domain",
      "source_name": "CMS NPPES"
    }
  },
  "page": 1,
  "total": 223,
  "total_capped": false
}

Use Cases

Find Providers by Specialty and Location

const results = await client.npi.search({
  specialty: "orthopedic",
  state: "TX",
  city: "Houston",
  entity_type: "individual"
});

Find Healthcare Organizations

const results = await client.npi.search({
  q: "hospital",
  entity_type: "organization",
  state: "NY"
});

Find Provider by Name

// Fuzzy matching handles variations
const results = await client.npi.search({
  first_name: "john",
  last_name: "smith",
  state: "CA"
});

Search by Taxonomy Code

// Find all cardiologists (taxonomy 207RC0000X)
const results = await client.npi.search({
  q: "cardiology",  // Text search required
  taxonomy: "207RC0000X"
});

Facets

NPI search returns these facets:

Important Notes

Text Search Required

NPI search requires at least one text search parameter (q, name, first_name, last_name, organization, or specialty). Filter-only queries (e.g., just state=TX) are not supported due to the large dataset size (9.3M+ providers).

Fuzzy Matching

Text search includes fuzzy matching to handle typos and name variations. For example, searching for "Jhonson" will find "Johnson".

Valid Values

Entity Types

• individual — Individual healthcare providers
• organization — Healthcare organizations, facilities, groups

Sort Options

• relevance — Best match first (default)
• name — Alphabetical by name
• location — Grouped by location

Required Scope

npi.search

See Also

• NPI Lookup API — Look up a specific NPI
• Search APIs Overview — Common search features