🦖 TinyRex Data Toolspractical guides for web data APIs

How to validate NPI numbers in bulk and build US healthcare provider lists from NPPES

Updated 2026-10-28 · Tool used: NPI Registry Lookup - Bulk NPI Search & Healthcare Providers on Apify · Price: $0.0008 per provider record ($0.80 per 1,000); invalid, unknown or deactivated NPIs, empty searches, filtered and duplicate providers are free

Every US healthcare provider that bills insurance has a 10-digit National Provider Identifier (NPI) in the NPPES registry run by CMS. Credentialing teams check NPIs, billing teams clean them up in claims data, and healthcare sales teams use the registry to find every practice of a given specialty in their territory. The public search page shows one provider at a time and caps results.

This guide shows how to use the free NPPES NPI Registry API in bulk: validate thousands of NPIs (the check digit is verified locally first), or build a provider list by specialty and location with flat spreadsheet columns for name, credential, primary specialty, license, practice address and phone.

Open NPI Registry Lookup on Apify →

Steps

  1. To validate or enrich, paste NPI numbers into npis, one per line. Numbers with a wrong check digit, unknown or deactivated NPIs come back as free found: false rows.
  2. To build a list, set taxonomyDescription (e.g. Dentist, Nurse Practitioner, cardio*) and combine it with cities, states or ZIP codes. Each city and state pair runs as its own search, up to the NPPES limit of 1,200 results per search.
  3. Turn on primaryTaxonomyOnly to keep real specialists (NPPES also matches secondary specialties), and set entityType to individuals or organizations.
  4. Run it and export the dataset as CSV or Excel, or send it to Google Sheets from the Integrations tab.

Example input

{
  "taxonomyDescription": "Dentist",
  "entityType": "individual",
  "cities": [
    "Austin",
    "Dallas"
  ],
  "states": [
    "TX"
  ],
  "primaryTaxonomyOnly": true,
  "maxRecords": 500
}

Example output (one item, shortened)

{
  "query": "1881018208",
  "queryType": "npi",
  "found": true,
  "npi": "1881018208",
  "entityType": "organization",
  "name": "MAYO CLINIC",
  "status": "active",
  "primaryTaxonomyCode": "261QM1300X",
  "primaryTaxonomy": "Clinic/Center, Multi-Specialty",
  "practiceAddress": {
    "address1": "200 1ST ST SW",
    "address2": null,
    "city": "ROCHESTER",
    "state": "MN",
    "postalCode": "55905-0001",
    "countryCode": "US"
  },
  "practiceCity": "ROCHESTER",
  "practiceState": "MN",
  "practicePostalCode": "55905-0001",
  "authorizedOfficial": {
    "name": "DENNIS DAHLEN",
    "title": "Chief Financial Officer",
    "credential": null
  },
  "taxonomies": [
    {
      "code": "261QM1300X",
      "description": "Clinic/Center, Multi-Specialty",
      "primary": true,
      "state": null,
      "license": null
    }
  ],
  "otherIdentifiers": [],
  "endpoints": [],
  "enumerationDate": "2014-02-05",
  "lastUpdated": "2021-04-12",
  "npiRegistryUrl": "https://npiregistry.cms.hhs.gov/provider-view/1881018208",
  "error": null
}

Every run's dataset can be downloaded as JSON, CSV, Excel, XML or HTML from the Apify Console, or via https://api.apify.com/v2/datasets/<datasetId>/items?format=csv.

Run it from code

Python

from apify_client import ApifyClient  # pip install apify-client

client = ApifyClient("<YOUR_APIFY_TOKEN>")
run_input = {
  "taxonomyDescription": "Dentist",
  "entityType": "individual",
  "cities": [
    "Austin",
    "Dallas"
  ],
  "states": [
    "TX"
  ],
  "primaryTaxonomyOnly": true,
  "maxRecords": 500
}
run = client.actor("tinyrex/npi-registry-lookup").call(run_input=run_input)
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

JavaScript / Node.js

import { ApifyClient } from 'apify-client'; // npm i apify-client

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('tinyrex/npi-registry-lookup').call({
  "taxonomyDescription": "Dentist",
  "entityType": "individual",
  "cities": [
    "Austin",
    "Dallas"
  ],
  "states": [
    "TX"
  ],
  "primaryTaxonomyOnly": true,
  "maxRecords": 500
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);

curl (no SDK)

# Runs the actor and returns the results directly (CSV here; use format=json for JSON)
curl -X POST "https://api.apify.com/v2/acts/tinyrex~npi-registry-lookup/run-sync-get-dataset-items?format=csv" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"taxonomyDescription": "Dentist", "entityType": "individual", "cities": ["Austin", "Dallas"], "states": ["TX"], "primaryTaxonomyOnly": true, "maxRecords": 500}' > results.csv

Get your API token in Apify Console → Settings → API & Integrations. The free Apify plan includes monthly credit that is enough to try this.

Use it from an AI agent (MCP)

The Apify MCP server exposes this actor as a tool for Claude, Cursor, VS Code, n8n and other MCP clients. Add this to your client's MCP config (or use the OAuth flow at mcp.apify.com instead of a token):

{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=tinyrex/npi-registry-lookup",
      "headers": {
        "Authorization": "Bearer <YOUR_APIFY_TOKEN>"
      }
    }
  }
}

Then ask in plain language, e.g. "Npi lookup api for this list and give me a table".

Pricing

Pay per result: $0.0008 per provider record ($0.80 per 1,000); invalid, unknown or deactivated NPIs, empty searches, filtered and duplicate providers are free. You can cap the cost of every run in the run options.

FAQ

Is there a free API for NPI lookups?

Yes. CMS runs the NPPES NPI Registry API with no key. The data is public by law (FOIA-disclosable), free to reuse, and US government work. This actor adds check-digit validation, paging, deduplication and flat columns.

How do I get a list of all dentists or pharmacies in a ZIP code?

Set the specialty and the ZIP codes, or use a raw NPPES search with taxonomy_description and postal_code. For a whole state, split by city or ZIP, since NPPES returns at most 1,200 providers per search.

Does an active NPI prove a provider is licensed?

No. An NPI is an identifier, not a license check. Use the license number and state in the output to verify with the state board.

What does it cost?

$0.0008 per provider found ($0.80 per 1,000). Rows with found: false, filtered-out providers and duplicates are not charged.

Try it on Apify →

More guides