# NPI Registry API: US Healthcare Organizations (`wooden_scanner_c1n/us-healthcare-organizations-npi`) Actor

Find US hospitals, clinics, pharmacies, labs and other healthcare organisations in the official CMS NPI Registry. Search by name, state, city, ZIP or taxonomy, or look up NPIs. Organisations only (NPI-2), clean B2B fields, no personal data. Built for lead gen and AI agents.

- **URL**: https://apify.com/wooden_scanner_c1n/us-healthcare-organizations-npi.md
- **Developed by:** [Sean](https://apify.com/wooden_scanner_c1n) (community)
- **Categories:** Lead generation, AI, Developer tools
- **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 organisation 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

## NPI Registry API: US Healthcare Organizations

Find **US healthcare organisations** (hospitals, clinics, pharmacies, labs, home health agencies, nursing facilities, surgery centres, DME suppliers and more) in the official **CMS NPI Registry (NPPES)**, and get clean, flat B2B records you can drop straight into a CRM, spreadsheet or AI agent.

- **Organisations only.** Every record is a Type 2 NPI (NPI-2). Individual clinicians (NPI-1) are never returned.
- **No personal data.** The authorised official's name and direct phone, and endpoint e-mail addresses, are removed. You get the organisation's business address and business phone only.
- **Past the 1,200 ceiling.** The NPI Registry API stops at 1,200 matches per search. This Actor pages through each search and, when you ask for more, splits big searches by ZIP-code prefix automatically.
- **Agent-ready.** Flat field names, one record per organisation, de-duplicated by NPI, with source and licence on every record. Works as a tool for AI agents through the [Apify MCP server](https://mcp.apify.com).

### Who it is for

- **Sales and lead generation** for medical devices, pharma, health IT, billing, staffing and B2B services: build lists of pharmacies in Texas, hospitals in Ohio or labs in a ZIP range.
- **Data and RevOps teams** enriching or verifying an account list against NPI numbers.
- **Credentialing, payer and network teams** checking organisation NPIs, taxonomies and practice addresses.
- **AI agents** that need to look up a healthcare organisation by name, place or NPI.

### How to use it

Fill in one or more filters. Filters of different kinds are combined (AND); several values in one filter each run as a separate search (OR), and results are de-duplicated.

| Input | What it does |
|---|---|
| `organizationNames` | Legal name, DBA, former or other name. Matches "starts with" by default (`mayo` finds MAYO CLINIC). |
| `states` | Two-letter codes, e.g. `CA`. Cannot be the only filter (an NPI Registry rule). |
| `cities` | e.g. `Boston`. Best with a state. |
| `postalCodes` | 5 or 9 digit ZIPs, or a prefix like `021*`. |
| `taxonomyDescriptions` | NUCC taxonomy text, e.g. `General Acute Care Hospital`, `Pharmacy`, `Clinic/Center`, `Home Health`, `Skilled Nursing Facility`, `Ambulatory Surgical`, `Clinical Medical Laboratory`. |
| `npiNumbers` | Look up specific 10-digit NPIs. Individual NPIs are skipped. |
| `maxItems` | Maximum records to return (default 100, up to 10,000). |
| `addressPurpose` | Match state/city/ZIP against any address (default), practice locations, primary location, secondary locations, or mailing address. |
| `autoSplit` | Split searches with more than 1,200 matches by ZIP prefix (default on). |
| `includeDeactivated` | Return deactivated NPIs too (NPI and status only). Default off. |

#### Example input

```json
{
  "taxonomyDescriptions": ["Pharmacy"],
  "states": ["TX"],
  "cities": ["Austin"],
  "maxItems": 200
}
```

```json
{
  "npiNumbers": ["1881018208", "1255498432"]
}
```

### Output

One record per organisation:

```json
{
  "npi": "1881018208",
  "organizationName": "MAYO CLINIC",
  "otherNames": [],
  "isSubpart": false,
  "parentOrganizationName": null,
  "status": "Active",
  "primaryTaxonomyCode": "261QM1300X",
  "primaryTaxonomyDescription": "Clinic/Center, Multi-Specialty",
  "taxonomies": [{"code": "261QM1300X", "description": "Clinic/Center, Multi-Specialty", "primary": true, "state": null, "licenseNumber": null, "taxonomyGroup": null}],
  "practiceAddress": {"line1": "200 1ST ST SW", "line2": null, "city": "ROCHESTER", "state": "MN", "postalCode": "55905-0001", "countryCode": "US", "phone": "507-284-2511", "fax": null},
  "practiceAddressText": "200 1ST ST SW, ROCHESTER, MN 55905-0001",
  "practiceCity": "ROCHESTER",
  "practiceState": "MN",
  "practicePostalCode": "55905-0001",
  "practicePhone": "507-284-2511",
  "practiceFax": null,
  "mailingAddress": {"line1": "200 1ST ST SW", "city": "ROCHESTER", "state": "MN", "postalCode": "55905-0001", "countryCode": "US", "phone": "507-284-2511"},
  "mailingAddressText": "200 1ST ST SW, ROCHESTER, MN 55905-0001",
  "mailingPhone": "507-284-2511",
  "otherPracticeLocations": [],
  "otherIdentifiers": [],
  "enumerationDate": "2014-02-05",
  "lastUpdated": "2021-04-12",
  "certificationDate": "2021-04-12",
  "registryUrl": "https://npiregistry.cms.hhs.gov/provider-view/1881018208",
  "source": "CMS NPPES NPI Registry (npiregistry.cms.hhs.gov), Read API v2.1",
  "licence": "US Government work, public domain (17 U.S.C. 105). ...",
  "retrievedAt": "2026-11-03T20:25:00Z",
  "searchCriteria": {"organization_name": "mayo clinic*", "state": "MN"}
}
```

Download as JSON, CSV, Excel or via the API. The **Organisations** table view shows the key columns.

### Pricing

Pay per event:

- **$0.005** per run (Actor start)
- **$0.002** per organisation record returned

So 1,000 organisations cost about $2. Set a maximum cost per run in Apify and the Actor stops cleanly when it is reached.

### Data source and licence

- **Source:** the CMS NPPES NPI Registry Read API v2.1, `https://npiregistry.cms.hhs.gov/api/?version=2.1` ([documentation](https://npiregistry.cms.hhs.gov/api-page)). Public, no key needed. CMS refreshes it daily.
- **Licence:** NPPES data is FOIA-disclosable information that CMS publishes to the public ([CMS Data Dissemination](https://www.cms.gov/medicare/regulations-guidance/administrative-simplification/data-dissemination)). It is a US Government work, which is not subject to copyright under 17 U.S.C. § 105 and is in the US public domain ([resources.data.gov: Open Licenses](https://resources.data.gov/open-licenses/)). Every record carries `source` and `licence` fields.
- **Disclaimer from CMS:** issuance of an NPI does not ensure or validate that a provider is licensed or credentialed.
- **Fair use:** CMS limits NPI Registry queries per hour and asks that bulk downloads use its monthly data file. This Actor sends one request at a time with a pause between requests, backs off on errors, identifies itself with a descriptive User-Agent, and caps requests per run. For a copy of the whole registry, use the [CMS NPI Downloadable File](https://download.cms.gov/nppes/NPI_Files.html).

### Limits and tips

- One NPI Registry search returns at most 1,200 matches. With `autoSplit` on, bigger searches are split by ZIP prefix (state-aware), so you can go past that. Very broad national searches may still stop at the request cap: add a state or taxonomy.
- State/city/ZIP filters match **any** address by default, so an organisation with a mailing address in your state but a practice elsewhere can appear. Set `addressPurpose` to `PRIMARY` to match the main practice location only.
- Taxonomy search matches the description text, so `Pharmacy` also returns `Pharmacy, Community/Retail Pharmacy` and similar.
- Phone numbers and addresses are what the organisation reported to NPPES and can be out of date. Check `lastUpdated`.
- Some organisations are small practices that carry a clinician's name in the business name; that is the organisation's registered legal name as published by CMS.

### Use with AI agents (MCP)

Add this Actor as a tool through the [Apify MCP server](https://mcp.apify.com) and ask, for example: *"Find skilled nursing facilities in Columbus, Ohio with their NPI and phone"* or *"Check whether NPI 1881018208 is an active organisation and what its primary taxonomy is."* The flat, de-duplicated output keeps agent context small.

### Not affiliated

This Actor is not affiliated with or endorsed by CMS or HHS.

# Actor input Schema

## `organizationNames` (type: `array`):

Names to search (legal name, DBA, former or other name all match). One per line. By default each name matches as 'starts with' (e.g. 'mayo' finds 'MAYO CLINIC').

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

Two-letter US state codes, e.g. CA, NY, TX. A state cannot be the only filter: combine it with a name, city, ZIP or taxonomy.

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

City names, e.g. Boston. Best combined with a state.

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

5 or 9 digit ZIP codes, or a prefix with a trailing \* (at least 2 digits, e.g. 021\*).

## `taxonomyDescriptions` (type: `array`):

NUCC taxonomy descriptions, e.g. 'General Acute Care Hospital', 'Pharmacy', 'Clinic/Center', 'Home Health', 'Skilled Nursing Facility', 'Ambulatory Surgical', 'Clinical Medical Laboratory'.

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

Look up specific 10-digit NPIs. Individual-provider NPIs (Type 1) are skipped: only organisations are returned.

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

Maximum number of organisation records to return across all searches. You pay per record.

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

Apply state / city / ZIP filters to any address (default), practice locations, the primary practice location only, secondary locations only, or the mailing address.

## `namePrefixMatch` (type: `boolean`):

On: 'mayo' finds every organisation whose name starts with MAYO. Off: exact name match only (you can still add \* yourself).

## `autoSplit` (type: `boolean`):

The NPI Registry API can page through at most 1,200 matches per search. When a search has more and you asked for more, it is split by ZIP-code prefix so you can get past that ceiling.

## `includeDeactivated` (type: `boolean`):

Off by default. When on, deactivated NPIs are returned with NPI and status only, as CMS asks.

## Actor input object example

```json
{
  "organizationNames": [
    "mayo clinic"
  ],
  "states": [
    "MN"
  ],
  "maxItems": 20,
  "addressPurpose": "ANY",
  "namePrefixMatch": true,
  "autoSplit": true,
  "includeDeactivated": false
}
```

# Actor output Schema

## `results` (type: `string`):

All organisation records returned by the run.

# 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 = {
    "organizationNames": [
        "mayo clinic"
    ],
    "states": [
        "MN"
    ],
    "maxItems": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("wooden_scanner_c1n/us-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 = {
    "organizationNames": ["mayo clinic"],
    "states": ["MN"],
    "maxItems": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("wooden_scanner_c1n/us-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 '{
  "organizationNames": [
    "mayo clinic"
  ],
  "states": [
    "MN"
  ],
  "maxItems": 20
}' |
apify call wooden_scanner_c1n/us-healthcare-organizations-npi --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,wooden_scanner_c1n/us-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/37fALWQaBvlXXORr0/builds/v1dC7XuRWWhFUge9x/openapi.json