# NPI Registry: US Healthcare Providers (Official NPPES) (`frenchdatalab/npi-registry-healthcare-providers`) Actor

Every US doctor, dentist, nurse practitioner, clinic, pharmacy or hospital from the official NPI Registry (CMS NPPES): specialty, practice address, phone, fax, license. Searches beyond the 1,200-result limit, plus NPI number look-up.

- **URL**: https://apify.com/frenchdatalab/npi-registry-healthcare-providers.md
- **Developed by:** [French Data lab](https://apify.com/frenchdatalab) (community)
- **Categories:** Lead generation, Developer tools, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 providers

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

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

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## NPI Registry: US Healthcare Providers (Official NPPES)

Get **every US doctor, dentist, nurse practitioner, therapist, clinic, pharmacy or hospital** from the official **NPI Registry** (CMS NPPES): name, credential, specialty, practice address, phone, fax, license number and state, authorized official for organizations.

Search by **specialty, state, city, ZIP code or name**, or enrich a list of **NPI numbers**. Official public data, updated daily by CMS.

### What can you do with it?

- 🎯 **Healthcare B2B prospecting**: *"every dentist in Los Angeles"*, *"chiropractors and physical therapists in Austin with a phone number"*, *"retail pharmacies in Manhattan"*.
- 🧾 **Provider data enrichment**: turn a list of NPI numbers into full profiles (specialties, licenses, addresses, phones).
- ✅ **Credentialing and verification**: is this NPI valid and active? Which license number and state?
- 🗺️ **Market mapping**: how many orthodontists per ZIP code in a state?

### Why this Actor?

| | This Actor | Typical NPI tools |
|---|---|---|
| More than 1,200 results per search | ✅ big searches are split by ZIP code automatically: **3,058 dentists in Los Angeles** in one run | ❌ the registry API stops at 1,200 (and repeats the last page) |
| Main specialty filter | ✅ the registry also returns providers who only list your specialty as a secondary one: filtered out by default | ❌ |
| Practice address check | ✅ providers matched only through a mailing address or a foreign address are removed | ❌ |
| Clean contact data | ✅ phone in 2 formats (`213-555-0100` and `+12135550100`), ZIP+4 formatted, names in proper case, credentials normalized (`d.d.s.` → `DDS`) | ⚠️ raw upper-case data |
| NPI check digit verified | ✅ typos reported, not charged | ❌ |
| Organizations | ✅ authorized official name, title and phone, other names (DBA), extra practice locations | ⚠️ |

### Input

| Field | Description | Example |
|---|---|---|
| `taxonomies` | Words of the official specialty name | `["Dentist"]`, `["Family Medicine"]`, `["Chiropractor", "Physical Therapist"]` |
| `states` | 2-letter state codes | `["CA"]` |
| `cities` | City names (with states when given) | `["Los Angeles"]` |
| `postalCodes` | ZIP codes or prefixes | `["10001"]`, `["900*"]` |
| `providerType` | `all`, `individual`, `organization` | `"organization"` |
| `firstName` / `lastName` / `organizationName` | Names, trailing `*` for "starts with" | `"smi*"` |
| `primarySpecialtyOnly` | Keep providers whose main specialty matches (default `true`) | `true` |
| `onlyWithPhone` | Skip providers without a phone number | `false` |
| `npis` | Look up NPI numbers instead of searching | `["1417281627"]` |
| `maxResults` | Maximum providers returned | `5000` |

Useful specialty words: Dentist, Orthodontics, Family Medicine, Internal Medicine, Pediatrics, Cardiovascular Disease, Dermatology, Psychiatry, Psychologist, Counselor, Chiropractor, Physical Therapist, Occupational Therapist, Optometrist, Podiatrist, Nurse Practitioner, Physician Assistant, Pharmacy, Clinic/Center, Hospital, Home Health.

### Output

Real example (`npis: ["1417281627"]`):

```json
{
    "found": true,
    "npi": "1417281627",
    "providerType": "individual",
    "name": "Richard Allen Aaron",
    "firstName": "Richard",
    "lastName": "Aaron",
    "namePrefix": "Dr.",
    "credential": "DDS",
    "gender": "male",
    "soleProprietor": true,
    "primarySpecialty": "Dentist, Endodontics",
    "primaryTaxonomyCode": "1223E0200X",
    "licenseNumber": "032068",
    "licenseState": "NY",
    "address": "3752 77TH ST",
    "city": "Jackson Heights",
    "state": "NY",
    "postalCode": "11372-6630",
    "phone": "718-426-5507",
    "phoneE164": "+17184265507",
    "enumerationDate": "2009-09-22",
    "status": "active",
    "registryUrl": "https://npiregistry.cms.hhs.gov/provider-view/1417281627"
}
```

Other fields: `middleName`, `nameSuffix`, `organizationName`, `organizationSubpart`, `parentOrganization`, `otherNames`, `specialties` (all, with licenses), `address2`, `countryCode`, `fax`, `mailingAddress`, `otherPracticeLocations`, `authorizedOfficialName` / `Title` / `Phone` (organizations), `lastUpdated`, `certificationDate`, `otherIdentifiers` (Medicaid…), `endpoints` (Direct messaging and FHIR addresses).

A `SUMMARY` record gives the counts by state, specialty and provider type.

### Notes

- The specialty search uses the registry's own words: "Chiropractor" works, "Chiropractic" does not. An unknown word stops the run with a clear message.
- Deactivated NPIs are not published by the registry: an NPI that is not found was never issued or has been deactivated.
- In the rare case where a single ZIP code still has more than 1,200 providers for your search, the run log says so.

### Pricing

You only pay for the providers returned: invalid or unknown NPI numbers are free. No subscription.

| Results | Price |
|---|---|
| 1 provider | $0.002 |
| 100 providers | $0.20 |
| 1,000 providers | $2.00 |

A start fee of a fraction of a cent applies per run. Set a **maximum cost per run** and the Actor stops exactly at your budget.

### Use it in your tools

- **No code**: run it from the Apify Console, download the results as Excel, CSV or JSON, and **schedule** it (daily, weekly…).
- **Integrations**: send the results to Google Sheets, Slack, email, webhooks, Make, Zapier or n8n with Apify's integrations.
- **API**: start runs and read the results with the Apify API or the official Python and JavaScript clients.
- **AI agents**: assistants and agents that support MCP can call this Actor as a tool through Apify's MCP server (mcp.apify.com).

### Related Actors

- [ClinicalTrials.gov Search: Trials, Sponsors & Sites](https://apify.com/frenchdatalab/clinical-trials-search): Clinical trials, sponsors and trial sites (ClinicalTrials.gov)
- [Grants.gov Search: US Federal Grant Opportunities](https://apify.com/frenchdatalab/us-federal-grants): US federal grant opportunities (Grants.gov)
- [USAspending Federal Awards: Contract & Grant Winners](https://apify.com/frenchdatalab/usaspending-federal-awards): Who wins US federal contracts and grants (USAspending)

### Source

**National Plan and Provider Enumeration System (NPPES)**, Centers for Medicare & Medicaid Services: public data, disclosable under the Freedom of Information Act, free to download and reuse. This Actor is independent: it is **not affiliated with or endorsed by CMS**.

# Actor input Schema

## `taxonomies` (type: `array`):

Words of the official specialty (taxonomy) description, e.g. "Dentist", "Orthodontics", "Family Medicine", "Internal Medicine", "Chiropractor", "Physical Therapist", "Nurse Practitioner", "Pharmacy", "Optometrist", "Psychologist".

## `states` (type: `array`):

2-letter codes: CA, NY, TX… Whole states are fully covered (the Actor splits big searches by ZIP code to go beyond the registry's 1,200-result limit).

## `cities` (type: `array`):

e.g. "Los Angeles". Combined with the states above when given (recommended: many US cities share a name).

## `postalCodes` (type: `array`):

5-digit ZIP codes or prefixes: "10001", "900\*" (Los Angeles area).

## `providerType` (type: `string`):

Individuals (doctors, dentists, nurses…) or organizations (clinics, group practices, pharmacies, hospitals).

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

Individuals. A trailing \* matches the beginning ("jo\*").

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

Individuals. A trailing \* matches the beginning ("smi\*").

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

Organizations, e.g. "Kaiser\*".

## `primarySpecialtyOnly` (type: `boolean`):

Keep providers whose MAIN specialty matches (the registry also returns providers who only list it as a secondary specialty).

## `onlyWithPhone` (type: `boolean`):

Skip providers whose practice address has no phone number.

## `npis` (type: `array`):

Enrich a list of 10-digit NPI numbers instead of searching. Invalid or unknown numbers are listed with found = false and are not charged.

## `maxResults` (type: `integer`):

Maximum number of providers returned (charged).

## Actor input object example

```json
{
  "taxonomies": [
    "Dentist"
  ],
  "states": [
    "CA"
  ],
  "providerType": "all",
  "primarySpecialtyOnly": true,
  "onlyWithPhone": false,
  "maxResults": 50
}
```

# Actor output Schema

## `providers` (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 = {
    "taxonomies": [
        "Dentist"
    ],
    "states": [
        "CA"
    ],
    "maxResults": 50
};

// Run the Actor and wait for it to finish
const run = await client.actor("frenchdatalab/npi-registry-healthcare-providers").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 = {
    "taxonomies": ["Dentist"],
    "states": ["CA"],
    "maxResults": 50,
}

# Run the Actor and wait for it to finish
run = client.actor("frenchdatalab/npi-registry-healthcare-providers").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 '{
  "taxonomies": [
    "Dentist"
  ],
  "states": [
    "CA"
  ],
  "maxResults": 50
}' |
apify call frenchdatalab/npi-registry-healthcare-providers --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,frenchdatalab/npi-registry-healthcare-providers"
        }
    }
}
```

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/SzRi8YKFFXME8GjuI/builds/0xRvJ3nPX5y4hmGgT/openapi.json