NPI Registry - US Healthcare Provider Lookup

Every US healthcare provider who bills Medicare or Medicaid has a National Provider Identifier - a permanent 10-digit number issued by CMS and never reused. The NPPES registry behind it is public open data: ~9 million providers (independent trackers put the register at roughly 9.4 million NPI records in mid-2026 - about 7.4 million individuals and 2 million organizations), no login and no key.

This actor turns that registry into a charged-per-record lookup: filter providers precisely, pull one provider's complete record by NPI, or roll the matches up by specialty, state or type.

Built for: credentialing and enrollment checks, provider-directory builds, sales and territory lists ("every cardiologist in this ZIP"), and payer or health-tech pipelines that need to resolve an NPI to a real, current address and specialty.

Low cost

From $0.0001 per record. Pay-per-event: charged per provider record delivered, nothing for the query.

A lookup registry, not a download

Nine million providers cannot be pulled wholesale - and no tool can, including this one. The registry answers a query, one page of 200 providers at a time, and it refuses a query with nothing to search on. There is no "give me everything" switch. What this actor sells is the opposite discipline: say precisely who you want, and get exactly them, with a full 10-digit-anchored verification path for the single provider in front of you. Every provider you receive is metered at $0.0001, so cost tracks the list you actually need.

What one provider record holds

A record is one provider - an individual (type 1) or an organization (type 2). It is not one location: the same provider carries its own set of addresses, specialties, licenses, identifiers and endpoints. Across a 400-provider sample the flattened schema spans 92 distinct field paths, and a single provider populates 30 to 64 of them (median 35).

Block	What it gives you
Identity	npi, enumerationType (NPI-1 individual / NPI-2 organization), status
Individual	firstName, middleName, lastName, namePrefix, nameSuffix, credential, gender, soleProprietor
Organization	organizationName, organizationalSubpart, plus the authorized official - name, credential, title and phone
Dates	enumerationDate, lastUpdated, certificationDate
Addresses	both a LOCATION and a MAILING address, each fully split into street, city, state, ZIP, country, phone and fax
Specialty	the primary taxonomy (code, description, group, license number, licensing state) plus every other taxonomy the provider holds
Practice sites	every additional practice location, joined into one field
Identifiers	the provider's other numbers - Medicaid, Medicare, license ids
Other names	former names and DBAs, with the name type
Endpoints	the provider's registered endpoints where it has any - Direct messaging, FHIR, CONNECT SOAP and others, with type, use and affiliation

Providers are deep in a way a bare name list is not. In that same 400-provider sample the busiest single record carried 7 taxonomies; separate providers carried 5 identifiers, 3 registered endpoints, and - an extreme but real case - 110 practice locations on one NPI. The record is flattened to one row (below), so you get all of it in a single line of output.

Modes

• rows (default) - the providers matching your filters, paged 200 at a time.
• profile - one provider's complete record, given its 10-digit npi. The verify path: hand it an NPI, get back everything the registry holds on it.
• aggregate - a rollup by one dimension (type, status, gender, sole-proprietor, state, country, taxonomy code or taxonomy group) over the providers matching your filters.

The filtering rules that actually matter

The registry is strict in ways that surprise people, so they are handled for you rather than thrown back raw:

• You must search on something. An NPI, a first or last name, an organization name, a taxonomy, a city, a ZIP, or a foreign country. Without one the registry refuses the query.
• state is not enough on its own - and neither is enumerationType. Neither can stand alone, and they do not rescue each other: state=TX plus enumerationType=NPI-1 is still refused. Pair them with a city, ZIP, name, taxonomy or NPI.
• Individuals and organizations cannot be mixed in one query. firstName / lastName describe a person; organizationName describes an organization. Mixing them is an error, not a union.
• Taxonomy is a text search, not a code list. There are ~800 taxonomy codes, so search by description - Cardiology, Internal Medicine, Nurse Practitioner - and wildcards work: *cardio*. A description that matches nothing is reported instead of silently returning zero.
• Names and cities match whole words, not prefixes. MAYO CLINIC finds the organization; MAYO on its own finds nothing, and Dall does not find Dallas. For a partial match, add wildcards - *clinic*, *smith*.
• A ZIP matches from the front. The registry stores ZIPs undashed, as 5 digits on some records and 9 on others, so a 5-digit code finds every provider whose stored ZIP starts with it (both forms), and a full 9-digit code matches those stored at full length. A 78701-4211 form is accepted here and normalized. The value can sit on the LOCATION, the MAILING address, or a listed practice location - a query returns a provider if any of its addresses matches.

A query the registry would refuse is turned into a clear message saying what is allowed, before anything is charged. A typo in a state code, a ZIP, a gender or an NPI is caught the same way - the registry itself answers several of those with a silent "no results", which would look like an empty provider list rather than a mistake.

How the record is flattened

The source nests deeply (addresses, taxonomies, identifiers, other names, endpoints are arrays). Each is flattened to one row so nothing is lost and nothing collides:

• Both addresses are lifted to named columns: location* and mailing*.
• The primary taxonomy is lifted to primaryTaxonomyCode / Desc / Group / State / License.
• The full arrays are kept as joined strings beside a count - taxonomyCount + taxonomies, identifierCount + identifiers, and the same for practice locations, other names and endpoints. Within one entry the parts are joined by |, and entries are separated by ;;. So "207R00000X | Internal Medicine | True | MD | D0000290 ;; ..." is one taxonomy per ;; segment.
• Every field is prefixed deliberately (no flattened source field can overwrite an envelope key), the key set is identical in every mode, and a missing value is an empty string rather than a dropped key.

Examples

One provider, everything on it - mode=profile, npi=1003000126:

NPI 1003000126 / NPI-1 / Active / ARDALAN ENKESHAFI
  LOCATION  6410 ROCKLEDGE DR STE 304, BETHESDA MD 208171841
  taxonomy  4 codes, primary 208M00000X | Hospitalist | DC | MD600003480

Every organization in a city - city=Austin, enumerationType=NPI-2.

A specialty in a ZIP - taxonomyDescription=Cardiology, postalCode=77030.

Who is registered under a name - lastName=Smith, state=TX.

How a city's providers break down - mode=aggregate, groupBy=primaryTaxonomyGroup.

Inputs

Input	What it does
mode	rows (default) / profile / aggregate
npi	10-digit NPI - the profile key, or an exact filter
enumerationType	NPI-1 individual / NPI-2 organization
firstName / lastName / useFirstNameAlias	individual providers (nickname-aware)
organizationName	organization providers
taxonomyDescription	specialty text search, wildcards allowed
city / state / postalCode / countryCode	location
groupBy	the aggregate dimension
maxResults	cap records (default 200; 0 = up to 2000 per run)

Default run = the 200 providers in Austin, TX - a query that reliably fills a page, so the daily auto-test stays fast. Change city / state to search anywhere.

Source

US NPPES National Provider Identifier registry - the Centers for Medicare & Medicaid Services' own public API. No key, no registration. The registry surface answers active providers: every one of 1,000 sampled records carried status A, and deactivated NPIs are not reachable through this endpoint - so this actor's reachable set is the active registry, not all 9.4 million records ever issued. Records are the government's own published fields, and an NPI is an identifier, not a credential or a license.

Each run is integrity-checked against the registry's known shape - a permanent reference NPI must still resolve, and the fields every provider carries must still be populated - so a degraded source fails loudly instead of returning empty or malformed records.

Related actors

• FMCSA Motor Carrier - the DOT-number registry for the trucking industry, the same "verify one number, or filter precisely" shape.
• CO Business Entities - the Colorado corporate register with full filing history.