NPPES NPI Registry Provider Search

Search the official US NPPES NPI Registry and export clean healthcare provider records for verification, credentialing, directory maintenance, and data enrichment. Look up exact NPI numbers or find individuals and organizations by name, specialty, and location.

Each result preserves the official nested addresses, taxonomies, licenses, identifiers, and endpoints while also exposing normalized identity and status fields.

What does this Actor do?

• Looks up one or many exact 10-digit NPI numbers.
• Searches individual providers by first and last name.
• Searches clinics, hospitals, practices, and other organizations.
• Filters searches by taxonomy or specialty, city, state, ZIP, country, and NPI type.
• Runs multiple search objects in one task.
• Deduplicates results by NPI across all searches.
• Exports one typed dataset row per provider.
• Records the exact source request and retrieval timestamp.

The Actor calls the official anonymous NPPES API directly. It does not require an NPPES login, browser, proxy, or CMS account.

Who is it for?

• Credentialing teams verifying NPI status, specialty, and published licenses.
• Healthcare operations teams maintaining provider directories.
• Billing teams matching internal provider records to official NPIs.
• Data engineers enriching healthcare datasets with source provenance.
• Compliance analysts reviewing provider identity and source update dates.
• Market researchers mapping providers by specialty and geography.

NPPES is an identity registry, not a complete license-disciplinary database. Use state licensing boards for authoritative license standing and sanctions.

Why use this NPPES lookup?

The raw registry response is deeply nested. This Actor turns it into a stable dataset contract while retaining the source detail:

1. Normalized provider display name and individual/organization type.
2. Separate practice and mailing address objects.
3. A primary taxonomy plus all taxonomy records.
4. A dedicated license list derived from taxonomies.
5. Additional identifiers and digital endpoints.
6. Source update date, fetch time, official detail URL, and exact API URL.

Batch input, pagination, limits, retries, and NPI deduplication are handled automatically.

What data can I export?

Field	Meaning
npi	Ten-digit National Provider Identifier.
providerName	Normalized person or organization display name.
providerType	individual, organization, or unknown.
enumerationType	Official NPI-1 or NPI-2 value.
status	Status code published by NPPES.
enumerationDate	Date on which the NPI was enumerated.
lastUpdatedDate	Registry record update date.
certificationDate	Certification date when published.
practiceAddress	Normalized location address and phone/fax.
mailingAddress	Normalized mailing address and phone/fax.
addresses	Complete address list from NPPES.
primaryTaxonomy	Primary specialty/taxonomy and license.
taxonomies	Complete taxonomy list.
licenses	License number, state, and taxonomy code tuples.
identifiers	Additional public identifiers.
endpoints	Published provider digital endpoints.
otherNames	Other names supplied by the source.
practiceLocations	Additional practice locations when available.
sourceUrl	Official NPPES provider detail URL.
sourceApiUrl	Exact API request that produced the row.
fetchedAt	UTC retrieval timestamp.

Optional source values are returned as null or empty arrays rather than invented values.

How to run an NPI provider search

1. Open the Actor in Apify Console.
2. For verification, add one or more values to NPI numbers.
3. For discovery, enter a last name, organization name, or taxonomy description.
4. Add city, state, ZIP, country, or provider type to narrow the search.
5. Set Maximum providers to control output and spend.
6. Click Start and open the default dataset.
7. Export results as JSON, CSV, Excel, XML, or through the dataset API.

Exact lookups and searches can be combined in the same run.

Input parameters

Input	Type	Description
npiNumbers	string[]	Exact 10-digit NPIs to verify.
searches	object[]	Batch provider searches.
firstName	string	Individual first name; requires lastName.
lastName	string	Individual last name.
organizationName	string	Organization or facility name.
taxonomyDescription	string	Specialty text such as Cardiology.
city	string	Location city.
state	string	Two-letter state code.
postalCode	string	ZIP/postal code.
countryCode	string	Two-letter country code; defaults to US.
enumerationType	string	NPI-1 individuals or NPI-2 organizations.
maxItems	integer	Total unique rows to save, from 1 to 10,000.

A location filter cannot be used by itself because NPPES requires a provider name, organization, or taxonomy search term. The Actor validates this before making requests.

Input examples

Exact NPI verification

{
  "npiNumbers": ["1003000126"],
  "maxItems": 1
}

Doctor NPI search by specialty and city

{
  "taxonomyDescription": "Cardiology",
  "city": "Boston",
  "state": "MA",
  "enumerationType": "NPI-1",
  "maxItems": 10
}

Batch credentialing enrichment

{
  "searches": [
    { "organizationName": "Mayo Clinic", "state": "MN", "enumerationType": "NPI-2" },
    { "lastName": "Smith", "city": "Austin", "state": "TX", "enumerationType": "NPI-1" }
  ],
  "maxItems": 20
}

Output example

A current exact lookup returns a record shaped like this (shortened for readability):

{
  "npi": "1003000126",
  "enumerationType": "NPI-1",
  "providerType": "individual",
  "status": "A",
  "providerName": "ARDALAN ENKESHAFI M.D.",
  "lastUpdatedDate": "2025-05-28",
  "practiceAddress": {
    "purpose": "LOCATION",
    "city": "BETHESDA",
    "state": "MD",
    "postalCode": "208171841"
  },
  "primaryTaxonomy": {
    "code": "208M00000X",
    "description": "Hospitalist",
    "primary": true,
    "state": "DC",
    "licenseNumber": "MD600003480"
  },
  "sourceUrl": "https://npiregistry.cms.hhs.gov/provider-view/1003000126"
}

How much does it cost to search NPPES providers?

This Actor uses pay-per-event pricing: $0.001 per run start plus one Item extracted event per unique saved NPI. At the BRONZE tier, each provider is $0.00144; higher-volume tiers decrease to $0.0004032 per provider.

For example, a 10-provider BRONZE run emits one $0.001 start event and ten $0.00144 provider events. A 100-provider run emits the same one start event plus 100 provider events. Your active Apify tier may be lower than BRONZE.

For predictable spend, start with maxItems: 10, inspect the records, then increase the limit. Duplicate NPIs and rejected source rows are not saved or charged as provider records.

Pagination, limits, and reliability

The Actor requests up to 200 records per official API page and stops at maxItems, source exhaustion, or the NPPES pagination boundary. Very broad searches may exceed the source's skip window; split them by state, city, specialty, or organization for complete targeted exports.

Transient timeout, rate-limit, and server errors receive bounded retries. Invalid input and deterministic source errors fail the run instead of returning a misleading partial success.

No residential proxy fallback is enabled. If the official API is unavailable persistently, the run fails clearly.

Data quality and limitations

• NPPES data is submitted and maintained by providers and organizations.
• A status code does not replace primary-source state license verification.
• Phone, fax, identifiers, endpoints, and licenses can be absent.
• Addresses may be mailing, practice, or additional locations.
• Taxonomy descriptions indicate classification, not necessarily board certification.
• The Actor returns current API records; it does not reconstruct history or detect changes by itself.
• Scheduling repeated runs and comparing datasets is supported by Apify workflows, but this Actor does not emit alerts.

Integration workflows

Provider master-data enrichment

Join dataset rows to an internal provider table on npi. Keep sourceLastUpdatedAt and fetchedAt for provenance.

Credentialing precheck

Use status, taxonomies, and licenses to route records for further primary-source checks. Do not treat NPPES as proof of an active state license.

Directory maintenance

Schedule a Task, export practice addresses and specialties, and compare the dataset with a prior run in your own pipeline.

Spreadsheet export

Open the dataset and choose CSV or Excel. Nested fields remain available in JSON exports for full fidelity.

Run through the Apify API

cURL

curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~npi-registry-provider-search/runs?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"npiNumbers":["1003000126"],"maxItems":1}'

JavaScript

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/npi-registry-provider-search').call({
  taxonomyDescription: 'Cardiology',
  city: 'Boston',
  state: 'MA',
  maxItems: 10,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);

Python

from apify_client import ApifyClient

client = ApifyClient(token="YOUR_APIFY_TOKEN")
run = client.actor("automation-lab/npi-registry-provider-search").call(run_input={
    "npiNumbers": ["1003000126"],
    "maxItems": 1,
})
items = client.dataset(run["defaultDatasetId"]).list_items().items
print(items)

Use with Apify MCP

Claude Code

Add the Actor to Claude Code:

claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/npi-registry-provider-search"

Claude Desktop, Cursor, and VS Code

Use this equivalent desktop/editor configuration:

{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/npi-registry-provider-search"
    }
  }
}

Example prompts:

• "Verify NPI 1003000126 and summarize its current NPPES status and primary specialty."
• "Find up to 20 NPI-1 cardiology providers in Boston and return their practice addresses."
• "Enrich this list of NPIs with names, taxonomies, licenses, and source update dates."

Legality and responsible use

NPPES is a public US government provider registry. Use the data for lawful healthcare operations, research, verification, and enrichment. Follow applicable privacy, marketing, anti-spam, and healthcare rules. Do not infer sensitive attributes or use incomplete registry fields to make automated adverse decisions.

This Actor is independent and is not affiliated with or endorsed by CMS or NPPES.

FAQ

Do I need an NPPES login?

No. The Actor uses the official anonymous public API and cannot apply for or edit an NPI.

Can I look up multiple NPIs at once?

Yes. Add them to npiNumbers; the Actor deduplicates repeated records.

Why did my search fail with only a state?

NPPES requires a name, organization, or taxonomy term. Add one of those and use the state as a narrowing filter.

Why are some license or phone fields empty?

Those fields are optional in source records. The Actor preserves missing values rather than guessing.

Does this verify a medical license?

No. It exports license references published in NPPES. Verify standing and discipline with the relevant state licensing authority.

How do I retrieve more complete results?

Use targeted batches by specialty and geography. This avoids the official API's broad-search pagination boundary.

Related automation-lab Actors

• CMS Medicare Provider Scraper for Medicare provider datasets.
• CMS Open Payments Data for Sunshine Act payment research.
• ClinicalTrials.gov Study Scraper for clinical study records.

Support

If a run fails, share its Apify run URL and sanitized input. Include the expected NPI or search filters and whether the source website currently returns the record.