# Healthcare Organizations Finder (NPI Registry) (`great_stuff/healthcare-organizations-npi`) Actor

US healthcare organizations (NPI type 2) from the official CMS NPI Registry—specialty, address, phone and enumeration date.

- **URL**: https://apify.com/great_stuff/healthcare-organizations-npi.md
- **Developed by:** [Kamal Katul](https://apify.com/great_stuff) (community)
- **Categories:** Lead generation, Business
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 organization records

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

## Healthcare Organizations Finder (NPI Registry)

Find US healthcare organizations such as dental practices, clinics, home health agencies, hospices, pharmacies and labs. The data comes from the official **CMS NPPES NPI Registry**. Each record has the organization's NPI, specialty (taxonomy), state license number, practice address, phone and fax, and the date its NPI was issued.

### Use cases

- **Healthcare B2B sales and marketing:** build territory lists of dental offices, home health agencies or pharmacies in a city or ZIP area.
- **New-practice prospecting:** use `enumeratedAfter` to find organizations that got their NPI recently.
- **Market research and network adequacy:** count providers by specialty and area.
- **Data hygiene:** check NPIs, specialties and addresses against the official registry.

### Data source

| Source | What it is | Access |
|---|---|---|
| [NPPES NPI Registry API](https://npiregistry.cms.hhs.gov/api-page) (CMS, U.S. Dept. of Health & Human Services) | Official registry of National Provider Identifiers | Public, no API key |

This Actor only searches **organizations** (NPI type 2). It does not return individual practitioners.

### How to use

1. Enter one or more **specialties** using registry taxonomy wording, such as `Dentist`, `Home Health`, `Pharmacy`, `Physical Therapist`, `Clinic/Center` or `Hospice Care, Community Based`.
2. Narrow the location with **states plus cities**, or with **ZIP codes or prefixes** (`787` covers the Austin area).
3. Optionally set **NPI issued on or after** to get only newer organizations.
4. Run it, then download the results as CSV, Excel or JSON.

### Input

| Field | Description | Default |
|---|---|---|
| `taxonomies` | Specialty descriptions. One search runs per specialty and location. | `["Dentist"]` (prefill) |
| `organizationName` | Name search; end it with `*` for "starts with". | – |
| `states` | 2-letter codes. | `["TX"]` (prefill) |
| `cities` | City names. Needs a state. | `["AUSTIN"]` (prefill) |
| `zipCodes` | Full ZIP codes or 2–4 digit prefixes. Use these or cities, not both. | – |
| `addressPurpose` | Which address the location filter matches: PRIMARY practice location, any LOCATION, MAILING, or ANY. | `PRIMARY` |
| `strictTaxonomyMatch` | The registry also returns related specialties. With this on, an organization is kept only if one of its taxonomies matches your exact phrase, so "Home Health" drops "Home Health Aide"-only agencies. | `true` |
| `enumeratedAfter` | Keep only NPIs issued on or after this date (YYYY-MM-DD). | – |
| `excludeSubparts` | Drop subparts, i.e. departments or branches that have their own NPI. | `false` |
| `includeAuthorizedOfficial` | Add the authorized official's name, title and phone as published in the registry. | `false` |
| `maxResults` | Stop after this many organizations. | 100 |

Example:

```json
{"taxonomies": ["Home Health", "Hospice Care, Community Based"], "states": ["TX"], "cities": ["AUSTIN", "ROUND ROCK"], "enumeratedAfter": "2023-01-01", "maxResults": 100}
```

### Output

Two sample records (names, numbers and addresses replaced with placeholders; the authorized official is off by default):

```json
{
  "npi": "1000000001",
  "organizationName": "EXAMPLE DENTAL CARE P.A.",
  "otherNames": [
    "EXAMPLE DENTAL GROUP"
  ],
  "primaryTaxonomy": "Dentist, General Practice",
  "primaryTaxonomyCode": "1223G0001X",
  "taxonomyGroup": "193400000X - Single Specialty Group",
  "licenseNumber": "00000",
  "licenseState": "TX",
  "allTaxonomies": [
    "Dentist, General Practice"
  ],
  "address": "100 EXAMPLE ST STE 101",
  "address2": null,
  "city": "AUSTIN",
  "state": "TX",
  "zip": "78701",
  "phone": "512-555-0100",
  "fax": "512-555-0101",
  "mailingAddress": "100 EXAMPLE ST STE 101",
  "mailingCity": "AUSTIN",
  "mailingState": "TX",
  "mailingZip": "78701",
  "additionalLocations": [],
  "enumerationDate": "2006-11-16",
  "lastUpdated": "2020-08-22",
  "status": "active",
  "isSubpart": false,
  "parentOrganizationName": null,
  "authorizedOfficialName": null,
  "authorizedOfficialTitle": null,
  "authorizedOfficialPhone": null,
  "registryUrl": "https://npiregistry.cms.hhs.gov/provider-view/1000000001",
  "scrapedAt": "2026-10-28T13:44:30.912Z"
}
```

```json
{
  "npi": "1000000002",
  "organizationName": "EXAMPLE CARE SERVICES",
  "otherNames": [],
  "primaryTaxonomy": "Residential Treatment Facility, Intellectual and/or Developmental Disabilities",
  "primaryTaxonomyCode": "320600000X",
  "taxonomyGroup": null,
  "licenseNumber": null,
  "licenseState": null,
  "allTaxonomies": [
    "Home Health",
    "Nursing Care",
    "Residential Treatment Facility, Intellectual and/or Developmental Disabilities",
    "Community Based Residential Treatment Facility, Intellectual and/or Developmental Disabilities",
    "Private Vehicle",
    "Respite Care, Respite Care, Intellectual and/or Developmental Disabilities, Child"
  ],
  "address": "200 EXAMPLE AVE",
  "address2": null,
  "city": "AUSTIN",
  "state": "TX",
  "zip": "78702",
  "phone": "512-555-0102",
  "fax": "512-555-0103",
  "mailingAddress": "200 EXAMPLE AVE",
  "mailingCity": "AUSTIN",
  "mailingState": "TX",
  "mailingZip": "78702",
  "additionalLocations": [],
  "enumerationDate": "2026-10-27",
  "lastUpdated": "2026-10-27",
  "status": "active",
  "isSubpart": false,
  "parentOrganizationName": null,
  "authorizedOfficialName": null,
  "authorizedOfficialTitle": null,
  "authorizedOfficialPhone": null,
  "registryUrl": "https://npiregistry.cms.hhs.gov/provider-view/1000000002",
  "scrapedAt": "2026-10-28T13:44:34.665Z"
}
```

### Pricing

**$0.002 per organization** saved to the dataset (pay per event). Apify platform usage is billed as usual. The run stops when it reaches your spending limit.

### Limits and tips

- The registry returns at most **1,200 records per search** (200 per page, up to 1,000 skipped). If a search hits that limit, the log warns you. Split the area into ZIP prefixes or cities to get the rest.
- Searches run in order: the first specialty and location fill up before the next one starts. For a balanced list, run separate searches or raise `maxResults`.
- The registry returns results alphabetically, not by date. `enumeratedAfter` is a filter on top of the search.
- To stay polite to the public API, the Actor sends at most 1 request per second and at most 300 requests per run. CMS has rate-limited the Registry API since 2024. If it answers HTTP 429, the run stops and keeps what it already saved.
- Only active NPIs are returned.
- For a full nationwide copy, CMS publishes the free monthly [NPPES Data Dissemination files](https://download.cms.gov/nppes/NPI_Files.html). Use those instead of this Actor.

### FAQ

**What is the NPI Registry?**
The official CMS register of National Provider Identifiers. This Actor returns organizations (NPI-2) only, not individual practitioners.

**Why did my search stop at 1,200 records?**
The NPI API returns at most 1,200 records per search. Split large searches by city or ZIP code.

**What taxonomy names can I use?**
Plain descriptions such as "Dentist", "Pharmacy", "Home Health" or "Physical Therapist". An unknown description stops the run with a clear message.

**Will I pay for the same organization twice?**
No. Each NPI is saved and charged at most once per run, even if several taxonomies match it.

### Privacy and legal

- NPPES data is public and disclosable under FOIA. CMS publishes it under the [NPPES Data Dissemination Notice](https://www.cms.gov/medicare/regulations-guidance/administrative-simplification/data-dissemination). This Actor reads only the public Registry API and needs no login.
- Records describe organizations. The authorized official is a person acting in a business role, so it is **opt-in** and you are responsible for using it lawfully: for example, CAN-SPAM, TCPA and do-not-call rules, and GDPR or state privacy laws where they apply.
- An NPI listing does not verify licensure or credentials. Check with the state licensing board when that matters.
- This Actor is not affiliated with or endorsed by CMS or HHS.

# Actor input Schema

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

NPI taxonomy descriptions, e.g. "Dentist", "Home Health", "Physical Therapist", "Pharmacy", "Clinic/Center", "Hospice Care, Community Based". One search runs per specialty and location.

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

Optional name search. End with \* for "starts with", e.g. "smile\*". At least 2 characters.

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

2-letter state codes, e.g. TX, CA.

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

City names (needs a state). Use either cities or ZIP codes.

## `zipCodes` (type: `array`):

Full ZIPs (78701) or 2-4 digit prefixes (787) for a whole area. Use either cities or ZIP codes.

## `addressPurpose` (type: `string`):

PRIMARY = main practice location (recommended). LOCATION = any practice location. MAILING = mailing address. ANY = any address.

## `strictTaxonomyMatch` (type: `boolean`):

The registry also returns related specialties ("Home Health" includes "In Home Supportive Care"). Keep only organizations with a taxonomy that contains your exact phrase.

## `enumeratedAfter` (type: `string`):

Optional YYYY-MM-DD. Keep only organizations that received their NPI on or after this date, e.g. to find new practices.

## `excludeSubparts` (type: `boolean`):

Drop organizational subparts (departments or branches with their own NPI).

## `includeAuthorizedOfficial` (type: `boolean`):

Add the organization's authorized official (name, title, phone) as published in the registry. Off by default; turn on only if you have a legitimate business purpose.

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

Stop after this many organizations. One search returns at most 1,200 records; split large areas by ZIP code.

## Actor input object example

```json
{
  "taxonomies": [
    "Dentist"
  ],
  "organizationName": "",
  "states": [
    "TX"
  ],
  "cities": [
    "AUSTIN"
  ],
  "zipCodes": [],
  "addressPurpose": "PRIMARY",
  "strictTaxonomyMatch": true,
  "enumeratedAfter": "",
  "excludeSubparts": false,
  "includeAuthorizedOfficial": false,
  "maxResults": 25
}
```

# Actor output Schema

## `items` (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": [
        "TX"
    ],
    "cities": [
        "AUSTIN"
    ],
    "maxResults": 25
};

// Run the Actor and wait for it to finish
const run = await client.actor("great_stuff/healthcare-organizations-npi").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": ["TX"],
    "cities": ["AUSTIN"],
    "maxResults": 25,
}

# Run the Actor and wait for it to finish
run = client.actor("great_stuff/healthcare-organizations-npi").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": [
    "TX"
  ],
  "cities": [
    "AUSTIN"
  ],
  "maxResults": 25
}' |
apify call great_stuff/healthcare-organizations-npi --silent --output-dataset

```

## MCP server setup

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

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/mbZv3hCGAjNLtywcn/builds/fuvoKH5uvEWWCLq5h/openapi.json