NPI Registry Provider Search & Change Monitor

Search the public CMS NPPES NPI Registry API v2.1 and track changes to provider names, status, update dates, primary taxonomy, practice addresses, and taxonomies. Supports individual and organization providers. No API key or login is required.

Input examples

A small targeted search, including previously returned providers.

{
  "searches": [{ "last_name": "Smith", "state": "CA", "limit": 5 }],
  "maxPerSearch": 5,
  "maxItems": 5,
  "onlyNew": false
}

Direct lookups with change monitoring.

{
  "npis": ["1234567893"],
  "onlyNew": true,
  "stateStoreName": "npi-registry-monitor-state"
}

Field	Default	Meaning
searches	[]	JSON array of CMS search objects.
npis	[]	List of ten-digit NPI strings.
maxPerSearch	200	Maximum records fetched per search, up to 1,200.
maxItems	500	Maximum provider records pushed per run, up to 10,000.
onlyNew	true	Emit only new or changed providers.
stateStoreName	npi-registry-monitor-state	Named KV store for change history.

Search fields are number, enumeration_type (NPI-1 or NPI-2), taxonomy_description, first_name, last_name, organization_name, city, state, postal_code, country_code, limit (1–200), and skip (0–1000). Supply at least one search or direct NPI. State alone is not a valid CMS search criterion. This Actor also requires a number, name, organization, taxonomy, city, or postal code to keep searches targeted. Pagination begins at skip, stops on a short page, and respects the API's skip ceiling.

Output sample

This fictional record shows the output shape. Missing source values are returned as null.

{
  "npi": "1234567893",
  "enumerationType": "NPI-1",
  "name": "JANE SMITH MD",
  "firstName": "JANE",
  "lastName": "SMITH",
  "credential": "MD",
  "organizationName": "",
  "gender": "F",
  "soleProprietor": "NO",
  "status": "A",
  "enumerationDate": "2010-01-01",
  "lastUpdated": "2026-01-01",
  "primaryTaxonomyCode": "207Q00000X",
  "primaryTaxonomyDesc": "Family Medicine",
  "taxonomies": [{ "code": "207Q00000X", "desc": "Family Medicine", "primary": true, "state": "CA", "license": "EXAMPLE" }],
  "practiceAddress": { "line1": "100 EXAMPLE ST", "line2": "", "city": "SACRAMENTO", "state": "CA", "postalCode": "95814", "phone": "9165550100" },
  "mailingAddress": { "line1": "PO BOX 100", "line2": "", "city": "SACRAMENTO", "state": "CA", "postalCode": "95814", "phone": "" },
  "npiUrl": "https://npiregistry.cms.hhs.gov/provider-view/1234567893",
  "matchedSearch": 0,
  "changeType": "new",
  "changedFields": [],
  "checkedAt": "2026-10-20T00:00:00.000Z"
}

matchedSearch is a zero-based index. Direct lookups follow the search array. Duplicate NPIs appear once per run. Error records contain error, checkedAt, and a search index when available. CMS can return Errors with HTTP 200; these become error records too. The default KV store contains RUN_SUMMARY with fetched, eligible, and pushed counts and charge-limit status.

Change history

The named store's PROVIDERS record maps each NPI to a SHA-256 fingerprint and meaningful field snapshot. Stable JSON covers name, status, lastUpdated, primaryTaxonomyCode, practiceAddress, and taxonomies. Each provider has changeType equal to new, changed, or unchanged. changedFields lists changed top-level fingerprint fields; new records have an empty list.

History is saved only after a successful provider push. onlyNew: false also emits unchanged providers. Dataset pushes and state writes are separate operations, so a crash between them can cause a duplicate on retry. Avoid overlapping runs sharing a state store. Use separate store names for independent histories.

Pricing

The provider event costs $0.0015 per emitted provider, or $1.50 per 1,000 providers. There is no run fee. Errors and skipped providers are not charged. Local runs do not incur event charges. Store pricing must match this event before publication.

Limits and source terms

• At most 200 records per request and 1,200 per search over six pages. The maximum skip is 1,000.
• Requests start at least 1,000 ms apart per host. Each run allows at most 60 HTTP attempts, including retries.
• HTTP 429 and 5xx responses use bounded exponential backoff and Retry-After. Requests time out after 30 seconds.
• Runs stop at maxItems or the remaining event charge limit. Search results do not guarantee complete coverage.
• CMS imposes hourly query limits. Bulk users must use the free NPPES downloadable file.
• CMS exposes FOIA-disclosable public data. NPI issuance does not ensure or validate licensing or credentials.

The source is the CMS NPI Registry API. TERMS.md records the supplied terms check and the binding bulk-use restriction. This Actor is unofficial, not affiliated with or endorsed by CMS or NPPES. It uses public documented APIs only, no logos, and no login.

Local development

Use Node 20 or newer. Run npm test. Tests stub fetch and use local storage. npm start uses storage/key_value_stores/default/INPUT.json and normally calls CMS. In a sandbox without network, preload a fetch stub when running it. Tests also launch the real Actor process with stubbed CMS responses and inspect its dataset and state.

To run with the bundled CMS response and inspect local output without network access, use the sample input.

NODE_OPTIONS='--import=./test/fixtures/preload.mjs' npm start