# NPPES NPI Registry Provider Search (`automation-lab/npi-registry-provider-search`) Actor

Search official NPPES records by NPI, provider name, organization, specialty, and location. Export normalized identity, status, addresses, taxonomies, licenses, identifiers, endpoints, and source timestamps.

- **URL**: https://apify.com/automation-lab/npi-registry-provider-search.md
- **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community)
- **Categories:** Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.86 / 1,000 item extracteds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## 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

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

#### Doctor NPI search by specialty and city

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

#### Batch credentialing enrichment

```json
{
  "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):

```json
{
  "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

```bash
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

```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

```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:

```bash
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:

```json
{
  "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](https://apify.com/automation-lab/cms-medicare-provider-scraper) for Medicare provider datasets.
- [CMS Open Payments Data](https://apify.com/automation-lab/cms-open-payments-data) for Sunshine Act payment research.
- [ClinicalTrials.gov Study Scraper](https://apify.com/automation-lab/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.

# Actor input Schema

## `npiNumbers` (type: `array`):

Exact 10-digit National Provider Identifier values to verify. May be combined with searches.

## `searches` (type: `array`):

Optional list of provider search objects. Each needs a name, organizationName, or taxonomyDescription; location fields narrow the results.

## `firstName` (type: `string`):

Individual provider first name. Requires lastName.

## `lastName` (type: `string`):

Individual provider last name. Wildcards supported by NPPES may be used.

## `organizationName` (type: `string`):

Clinic, hospital, practice, facility, or other organization name.

## `taxonomyDescription` (type: `string`):

Provider specialty or taxonomy description, such as Cardiology or Family Medicine.

## `city` (type: `string`):

Practice location city used to narrow a provider search.

## `state` (type: `string`):

Two-letter US state code used to narrow a search.

## `postalCode` (type: `string`):

ZIP or postal code used to narrow a search.

## `countryCode` (type: `string`):

Two-letter country code. Most NPPES searches use US.

## `enumerationType` (type: `string`):

Limit results to individuals (NPI-1) or organizations (NPI-2).

## `maxItems` (type: `integer`):

Maximum unique provider records saved across all lookups and searches.

## Actor input object example

```json
{
  "npiNumbers": [
    "1003000126"
  ],
  "searches": [
    {
      "taxonomyDescription": "Cardiology",
      "city": "Boston",
      "state": "MA",
      "enumerationType": "NPI-1"
    }
  ],
  "countryCode": "US",
  "maxItems": 20
}
```

# Actor output Schema

## `overview` (type: `string`):

Default dataset containing one normalized row per unique NPI provider record.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "npiNumbers": [
        "1003000126"
    ],
    "searches": [
        {
            "taxonomyDescription": "Cardiology",
            "city": "Boston",
            "state": "MA",
            "enumerationType": "NPI-1"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/npi-registry-provider-search").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "npiNumbers": ["1003000126"],
    "searches": [{
            "taxonomyDescription": "Cardiology",
            "city": "Boston",
            "state": "MA",
            "enumerationType": "NPI-1",
        }],
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/npi-registry-provider-search").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "npiNumbers": [
    "1003000126"
  ],
  "searches": [
    {
      "taxonomyDescription": "Cardiology",
      "city": "Boston",
      "state": "MA",
      "enumerationType": "NPI-1"
    }
  ]
}' |
apify call automation-lab/npi-registry-provider-search --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,automation-lab/npi-registry-provider-search"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/90vGiJ0Rref7wmXE4/builds/aIcP0mM8j61AsVri1/openapi.json