FHIRfly
Dashboard

NPI Search API

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

Endpoint

GET /v1/npi/search

Quick Start

Node.js
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.

Parameter Description Example
q General text search q=mayo clinic
name Search provider/org name name=smith
first_name Individual first name first_name=john
last_name Individual last name last_name=smith
organization Organization name organization=hospital
specialty Search specialty/taxonomy specialty=cardiology

Filters

Parameter Type Description Example
taxonomy string Healthcare taxonomy code 207RC0000X
state string 2-letter state code CA, TX
city string City name Los Angeles
postal_code string ZIP code 90210
phone string Phone number 5551234567
entity_type enum individual or organization organization
active boolean Active NPI status true

Pagination & Response

Parameter Default Max Description
limit 20 100 Results per page
page 1 100 Page number
shape compact — compact, standard, full
sort relevance — relevance, name, location

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

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

Find Healthcare Organizations

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

Find Provider by Name

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

Search by Taxonomy Code

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

Facets

NPI search returns these facets:

Facet Description
entity_type Distribution by individual vs organization
state Distribution by state

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