NPI Registry lookup — healthcare providers (NPPES API)

One flat row per healthcare provider from the CMS National Plan and Provider Enumeration System (NPPES) NPI Registry, read live through its public API (version 2.1). Look up a list of NPI numbers, or search by taxonomy (specialty), first/last name, organization name, city, state, postal code and NPI type; get name, credential, primary taxonomy with license number and state, other taxonomies, practice and mailing address, phone, enumeration and update dates and status — flattened and cleaned (the registry's -- placeholders become nulls, ZIP+4 is hyphenated).

Honesty note. The NPI Registry is a public directory of enumerated providers with self-reported details. A row means an NPI exists with these details — it is not a credentialing verdict: it does not establish that the provider is licensed, in good standing, or enrolled with any payer. Verify with the state licensing board or the payer.

Data source and status

Publisher	Centers for Medicare & Medicaid Services (CMS), NPPES
API	https://npiregistry.cms.hhs.gov/api/?version=2.1 — plain GET, no key, JSON; documentation at https://npiregistry.cms.hhs.gov/api-page
Bulk file of record	Monthly NPPES data dissemination file: https://download.cms.gov/nppes/NPI_Files.html
Refresh cadence	The registry is updated continuously as providers file changes (weekly incremental files, monthly full file). The Actor reads live on every run; fetched_at is the fetch time and last_update_date is the record's own date
Copyright	Works of the United States Government are not subject to copyright in the U.S. (17 U.S.C. §105). The data are public; please cite CMS/NPPES as the source
CMS limits (measured 2026-09-04)	At most 200 results per request (limit; 201 is silently served as 200) and skip is clamped at 1,000 (skip 1001 and 1400 return the skip-1000 page), so one search returns at most 1,200 providers — narrow the criteria (city, postal code, NPI type) to see more. result_count is the page count, not the total. A search by state alone, or by NPI type alone, is refused by the registry. city/state/postal_code match the practice or the mailing address (a Raleigh search also returns providers practising in Durham or Cary whose mailing address is in Raleigh) — filter on practice_city if you need the practice location only

Identification: requests carry the product-token User-Agent RetrainMap-npi-provider-registry/0.1 and the operator's contact address in the standard From: header. Rate: one request per 500 ms by default (floor 250 ms), retries on 429/5xx.

Input

Field	Type	Meaning
npi_numbers	array of 10-digit strings	Lookup mode: one request per number; search criteria are ignored. Numbers with a wrong check digit stop the run; valid-but-unknown numbers are listed as not_found in the run summary
taxonomy_description	string	Search mode (all criteria AND-ed). E.g. Physical Therapist, Family Medicine; trailing * wildcard after two characters. Matches any of the provider's taxonomies
first_name, last_name	string	Individuals; trailing * wildcard
organization_name	string	Organizations; trailing * wildcard
city, state, postal_code	string	state is a two-letter code; postal_code 5 or 9 digits, trailing * wildcard
enumeration_type	any / NPI-1 / NPI-2	Individual (NPI-1) or organization (NPI-2)
max_records	integer	Default 200 (Console prefill 100). Searches stop at 1,200 regardless
request_interval_ms	integer	Default 500 (floor 250)
contact_email	string	Sent in the From: header

Examples — physical therapists in Raleigh, NC (the default input, ~100 rows):

{ "taxonomy_description": "Physical Therapist", "state": "NC", "city": "Raleigh", "max_records": 100 }

Three known NPIs:

{ "npi_numbers": ["1922739051", "1972760981", "1003000126"] }

Output (dataset row)

npi, enumeration_type (NPI-1/NPI-2), entity (individual/organization), name (organization name, or prefix + first + middle + last + suffix), first_name, last_name, credential, gender, sole_proprietor (individuals), authorized_official, authorized_official_title (organizations), primary_taxonomy_code, primary_taxonomy, primary_license_number, primary_license_state, other_taxonomies (code desc; code desc), taxonomy_count, practice_address_1, practice_address_2, practice_city, practice_state, practice_zip, practice_country, practice_phone, practice_fax, mailing_city, mailing_state, mailing_zip, additional_practice_locations (count of secondary practice locations on file), enumeration_date, last_update_date, certification_date, status (A = active), deactivation_date, fetched_at, source.

A run summary (mode, criteria, request count, not_found NPIs, whether the CMS 1,200 cap or the pay-per-event budget stopped the run) is stored as RUN_SUMMARY in the run's key-value store.

Pricing (pay per event)

Event	Price
run-start — once per run	$0.10
record — per row written	$0.005

The default 100-row search costs $0.60; a full 1,200-row search $6.10; a 500-number lookup $2.60. Rows stop when your run's maximum charge is reached; the run summary says so.

Operator

Steelyard Ventures LLC (RetrainMap) — info@steelyardclinical.com. The Actor writes only to its own dataset and key-value store; it stores no credentials and sends nothing else.