# NPPES US Healthcare Provider & NPI Registry (`dromb/nppes-us`) Actor

Search and verify individual healthcare providers and organizations in the official CMS NPI Registry.

- **URL**: https://apify.com/dromb/nppes-us.md
- **Developed by:** [Dmitriy Gyrbu](https://apify.com/dromb) (community)
- **Categories:** Automation, Developer tools, Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.20 / 1,000 results

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

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#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 US Healthcare Provider & NPI Registry

Search and verify public US healthcare provider records through the official CMS NPI Registry API. Use this Actor for provider-directory enrichment, NPI validation, organization research, specialty discovery, credential checks, healthcare analytics, and CRM data quality.

This Actor is unofficial and is not affiliated with CMS, HHS, or NPPES. Registry data is directory information, not a provider recommendation or medical advice.

### Operations

- `probe`: bounded availability check; writes no dataset rows.
- `search`: find individual or organization providers using one or more official CMS filters.
- `item`: retrieve one provider by exact 10-digit NPI.

### Search filters

- Individual: `first_name`, `last_name`, and `entity_type: I`.
- Organization: `organization_name` and `entity_type: O`.
- Location: `city`, two-letter `state`, or `zip_code`.
- Specialty: `taxonomy_description`, for example `Family Medicine` or `Cardiology`.
- Identifier: exact `npi`.

CMS NPI Registry search accepts taxonomy descriptions, not exact taxonomy codes. `taxonomy_code` is retained as a deprecated input so old integrations receive an actionable `invalid_input` response instead of misleading results. Inspect `taxonomy_primary_code` and `taxonomies` in returned providers.

### Examples

Individual provider search:

```json
{"operation":"search","first_name":"Michael","city":"NEW YORK","entity_type":"I","limit":5}
```

Organization search:

```json
{"operation":"search","organization_name":"Mayo Clinic","entity_type":"O","state":"MN","limit":5}
```

Specialty discovery:

```json
{"operation":"search","taxonomy_description":"Family Medicine","state":"CA","entity_type":"I","limit":10}
```

Exact NPI lookup:

```json
{"operation":"item","npi":"1003979261"}
```

### Output semantics

Each dataset row has `source: cms_npi_registry` and a `record_type` of `individual_provider` or `organization_provider`. Practice (`LOCATION`) and mailing (`MAILING`) addresses remain separate. Primary taxonomy is exposed as `taxonomy_primary_code`; all official taxonomies and licenses remain in `taxonomies`.

Run status, totals, processed rows, and structured errors are stored under `OUTPUT`. Missing filters, malformed NPIs, unsupported operations, and deprecated taxonomy-code searches do not silently become a different query.

### Limits and cost

The CMS API allows at most 200 results per request. `page` is 1-based. No proxy or browser is required. The default console action is a lightweight `probe`; ready-to-run Saved Tasks provide useful examples without contaminating other inputs with schema defaults.

# Actor input Schema

## `operation` (type: `string`):

Operation to perform: 'probe' to check API status, 'search' to find providers, or 'item' to get a specific provider by NPI.

## `npi` (type: `string`):

Exact 10-digit NPI (required for 'item' operation).

## `first_name` (type: `string`):

Exact first name (for 'search' operation).

## `last_name` (type: `string`):

Exact last name (for 'search' operation).

## `organization_name` (type: `string`):

Exact organization name (for 'search' operation).

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

Exact city (for 'search' operation).

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

Exact 2-letter state code (for 'search' operation).

## `zip_code` (type: `string`):

Exact 5-digit ZIP code (for 'search' operation).

## `entity_type` (type: `string`):

Entity type: 'I' (Individual) or 'O' (Organization).

## `taxonomy_code` (type: `string`):

Deprecated: CMS search does not accept exact taxonomy codes. Use Taxonomy Description.

## `taxonomy_description` (type: `string`):

CMS taxonomy/specialty description, for example Family Medicine or Cardiology.

## `page` (type: `integer`):

Page number for pagination.

## `limit` (type: `integer`):

Results per page.

## Actor input object example

```json
{
  "operation": "probe",
  "page": 1,
  "limit": 2
}
```

# Actor output Schema

## `dataset` (type: `string`):

No description

## `summary` (type: `string`):

No description

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("dromb/nppes-us").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("dromb/nppes-us").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{}' |
apify call dromb/nppes-us --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=dromb/nppes-us",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/90QC5moE5EbdcdihE/builds/0YxHjsqdxJk3hA9kk/openapi.json