NPI Registry API: How to Look Up Any US Healthcare Provider

What the NPI Registry contains

Every healthcare provider in the United States has a National Provider Identifier (NPI). The NPI Registry (NPPES) is the public lookup system for all 7.8 million+ active NPI records.

It covers:

• Individual providers (doctors, nurses, therapists, pharmacists)
• Organizational providers (hospitals, clinics, labs, pharmacies)
• Name, address, phone, specialty/taxonomy
• License information by state

The data is self-reported by providers and updated continuously.

API basics

The NPPES API is free, requires no authentication, and returns JSON:

# Search by NPI number
curl "https://npiregistry.cms.hhs.gov/api/?version=2.1&number=1234567890"

# Search by name
curl "https://npiregistry.cms.hhs.gov/api/?version=2.1&first_name=John&last_name=Smith&state=CA"

# Search by organization name
curl "https://npiregistry.cms.hhs.gov/api/?version=2.1&organization_name=Mayo+Clinic"

Available search parameters

Parameter	Description	Example
number	NPI number (exact match)	1234567890
first_name	Provider first name	John
last_name	Provider last name	Smith
organization_name	Organization name	Kaiser
taxonomy_description	Specialty description	Cardiology
city	Practice city	Boston
state	Two-letter state code	MA
postal_code	ZIP code (5-digit or 9-digit)	02115
country_code	Country	US
limit	Results per page (max 200)	50
skip	Pagination offset	200

Parameters combine with AND logic. More specific queries return faster results.

Understanding the response

A typical individual provider response:

{
  "result_count": 1,
  "results": [{
    "number": 1234567890,
    "basic": {
      "first_name": "JANE",
      "last_name": "DOE",
      "credential": "MD",
      "gender": "F",
      "enumeration_date": "2005-06-15",
      "last_updated": "2024-03-22",
      "status": "A"
    },
    "addresses": [{
      "address_purpose": "LOCATION",
      "address_1": "123 Medical Center Dr",
      "city": "BOSTON",
      "state": "MA",
      "postal_code": "021151234",
      "telephone_number": "617-555-0100"
    }],
    "taxonomies": [{
      "code": "207RC0000X",
      "desc": "Internal Medicine, Cardiovascular Disease",
      "primary": true,
      "state": "MA",
      "license": "12345"
    }]
  }]
}

Key sections:

• basic - Name, credentials, enumeration date, status
• addresses - Practice location(s) and mailing address
• taxonomies - Specialties with taxonomy codes and state licenses

Taxonomy codes: understanding specialties

The taxonomy system uses NUCC (National Uniform Claim Committee) codes. These are hierarchical:

207R00000X = Internal Medicine (general)
207RC0000X = Internal Medicine, Cardiovascular Disease
207RG0100X = Internal Medicine, Gastroenterology
207RI0200X = Internal Medicine, Infectious Disease

The first 3 characters identify the broad provider type. Characters 4-7 identify the specialization. Common top-level types:

Code prefix	Provider type
207	Physician (Allopathic)
208	Physician (Osteopathic)
363	Nurse Practitioner
261Q	Clinic/Center
282N	Hospital
332B	Pharmacy
103T	Psychologist

Rate limits and performance

The API has unofficial rate limits around 1,200 requests per 5-minute window. Exceeding this returns HTTP 429 responses.

Tips for production use:

• Cache results aggressively (provider data changes infrequently)
• Use the bulk download file for initial database population
• Use the API for real-time verification and incremental updates
• Add exponential backoff for 429 responses

Bulk download: the practical approach

For building a provider directory or running batch analysis, the bulk download is more practical than millions of API calls:

• Full file: ~8 GB compressed, 7.8M+ records
• Updated monthly (first of each month)
• Format: Pipe-delimited CSV
• Download: https://download.cms.gov/nppes/NPI_Files.html

The bulk file contains every field available through the API, plus historical data on deactivated NPIs.

Common use cases

Provider directory: Build a searchable database of providers by specialty and location. The NPI Registry gives you the core identity data; augment with CMS quality scores and insurance network data.

Claims processing: Verify NPI numbers on incoming claims. An invalid or deactivated NPI means the claim needs manual review.

Referral networks: Map which providers practice at which locations. The address data combined with taxonomy codes reveals referral patterns.

Credentialing: Verify provider credentials, license state, and enumeration date for healthcare organization onboarding.

Fraud detection: Deactivated NPIs still appearing on claims, providers billing for services outside their taxonomy, or addresses that do not match known practice locations.

Data quality warnings

Provider data in NPPES has known quality issues:

• Stale addresses: Providers move practices but do not update their NPI record. Approximately 15-20% of addresses may be outdated.
• Missing specialties: Some providers never update their taxonomy beyond the initial generic entry.
• Deceased providers: NPI deactivation after provider death can lag by months.
• Duplicate organizations: Health systems may have multiple NPI records for the same physical location under different legal entities.

Cross-reference with state licensing boards and CMS enrollment data for higher accuracy.

FAQ

Is the NPI Registry API free? Completely free, no registration or API key needed.

How current is the data? The API reflects near-real-time data. When a provider updates their record, it appears within days. The bulk download file refreshes monthly.

Can I look up a provider's patients or prescribing history? No. The NPI Registry only contains provider identity information. Prescribing data is in CMS Part D files. Patient data is never publicly available.

What does a deactivated NPI mean? The provider is no longer eligible to bill Medicare/Medicaid, has died, or the NPI was assigned in error. Deactivated NPIs still appear in the registry with status "D".

How do I find all providers at a specific hospital? Search by the hospital's address or organization name. Individual providers listing that address as their practice location will appear in separate queries filtered by that address.