NPI Provider Lookup

Look up US healthcare providers and organizations from the CMS NPPES NPI registry. Pass an NPI number, a name, a taxonomy, or a city and state, and get back clean normalized records instead of the raw nested registry JSON.

It runs as a standby API (instant HTTP responses) and also as a normal batch actor that writes to a dataset.

flowchart LR
  A["Request<br/>NPI / name / taxonomy / state"] --> B{mode}
  B -->|provider| C["NPPES by NPI number"]
  B -->|search| D["NPPES individual search"]
  B -->|org| E["NPPES organization search"]
  C --> F["Flatten<br/>taxonomy + address + contact"]
  D --> F
  E --> F
  F --> G[("Dataset<br/>normalized providers")]

What it does

• Resolves a single provider by 10-digit NPI number.
• Searches individual providers by last name, first name, taxonomy, city, and state.
• Searches organizations (NPI-2) by name and location.
• Flattens the registry payload into one row per provider with primary taxonomy, license, practice address, and phone.

Data comes straight from the public CMS NPPES registry API. No key, no proxy, no browser.

Endpoints (standby mode)

Method	Path	Query params	Returns
GET	/provider	npi	single normalized provider
GET	/search	last_name, first_name, state, taxonomy, city, limit	individual providers
GET	/org	name, state, city, taxonomy, limit	organizations
GET	/ or /health	none	service info

Pricing (pay per event)

Event	Price (USD)	When
actor-start	$0.25	once per paid batch run
provider-record	$0.01	per normalized provider returned
enriched-provider	$0.02	per provider that has full taxonomy + address + contact

Health probe values like test, ping, example, or a placeholder NPI such as 1234567890 return a mock and are never charged.

Example requests

Single provider by NPI:

$curl "https://<your-standby-url>/provider?npi=1104130236"

Search individuals:

$curl "https://<your-standby-url>/search?last_name=smith&state=CA&taxonomy=Family%20Medicine&limit=10"

Search organizations:

$curl "https://<your-standby-url>/org?name=hospital&state=NY&limit=10"

Batch run (input JSON):

{ "mode": "search", "last_name": "smith", "state": "CA", "limit": 25 }

Output schema

Each provider row:

{
  "npi": "1104130236",
  "type": "individual",
  "first_name": "SHELLEY",
  "last_name": "AKEY",
  "organization_name": null,
  "credential": "RN, NNP",
  "status": "A",
  "primary_taxonomy": "Nurse Practitioner, Neonatal",
  "taxonomy_code": "363LN0000X",
  "license": "AP3827",
  "enumeration_date": "2010-07-30",
  "last_updated": "2025-03-03",
  "practice_address": {
    "address_1": "1919 E THOMAS RD",
    "city": "PHOENIX",
    "state": "AZ",
    "postal_code": "850167710"
  },
  "phone": "602-933-6345",
  "fax": null,
  "fetched_at": "2026-06-10T00:00:00.000Z"
}

For organizations, type is organization, organization_name is populated, and first_name / last_name are null.

Flow

flowchart TD
  A[Request] --> B{Path}
  B -->|/provider| C[fetchProviderByNpi]
  B -->|/search| D[searchProviders NPI-1]
  B -->|/org| E[searchOrganizations NPI-2]
  C --> F[CMS NPPES API]
  D --> F
  E --> F
  F --> G[normalizeProvider]
  G --> H{Full taxonomy + address + phone?}
  H -->|yes| I[charge provider-record + enriched-provider]
  H -->|no| J[charge provider-record]
  I --> K[JSON response / dataset]
  J --> K

Privacy note

This actor reads only the CMS NPPES NPI registry, which is a public provider directory published by the Centers for Medicare and Medicaid Services. It contains business and licensing details about healthcare providers and organizations. There is no patient data, no PHI, and no treatment information involved.