NPPES NPI Healthcare Provider Crawler

Extract healthcare provider records from the CMS NPPES NPI Registry, the official federal database of 2.5M+ National Provider Identifiers. Returns NPI numbers, names, credentials, specialties, taxonomy codes, practice addresses, phone numbers, license information, and gender for individual providers and healthcare organizations across all 50 US states.

---

Features

• Queries the official CMS NPPES REST API (v2.1) for structured JSON data -- no HTML scraping
• Filter by state, specialty/taxonomy code, city, ZIP code, provider type, or provider name
• Returns 25+ fields per record including practice and mailing addresses with formatted phone numbers
• Supports both individual providers (NPI-1: doctors, nurses, therapists) and organizations (NPI-2: hospitals, clinics, labs)
• State-only searches automatically enumerate through name prefixes to work around the API's minimum-criteria requirement
• No proxy required -- the NPPES API is a free, open government service with no authentication or rate limiting

---

Who Uses NPI Provider Data?

• Pharma sales teams -- Build targeted call lists of physicians by specialty and geography
• Medical device companies -- Identify orthopedic surgeons, radiologists, or other specialists in target markets
• Healthcare SaaS platforms -- Enrich provider directories with verified NPI numbers and taxonomy codes
• Insurance companies -- Validate provider credentials and network participation
• Market researchers -- Analyze provider density, specialty distribution, and practice patterns by region
• Recruiting firms -- Find healthcare professionals by specialty, location, and credential type

---

How It Works

1. Configure filters -- Select states, specialties, cities, or ZIP codes. Combine filters to narrow results.
2. API queries -- The crawler builds optimized queries against the CMS NPPES API, paginating through results in batches of 200.
3. Data transformation -- Raw API responses are normalized: phone numbers formatted as (XXX) XXX-XXXX, ZIP codes hyphenated, taxonomy codes mapped to human-readable descriptions.
4. Export -- Clean JSON records land in your Apify dataset. Set maxItems to control volume.

---

Input

Search by state and specialty

{
  "states": ["AZ"],
  "taxonomyCode": "207R00000X",
  "maxItems": 100
}

Search by ZIP code

{
  "zip": "85016",
  "maxItems": 50
}

Search by city and state

{
  "states": ["WY"],
  "city": "Cheyenne",
  "maxItems": 100
}

Search by provider name

{
  "states": ["CA"],
  "lastName": "Smith",
  "providerType": "NPI-1",
  "maxItems": 50
}

Search organizations only

{
  "states": ["TX"],
  "providerType": "NPI-2",
  "taxonomyCode": "261QM1300X",
  "maxItems": 100
}

Field	Type	Default	Description
states	array	["AZ"]	One or more US state codes. Filters by practice address state.
taxonomyCode	string	all	NUCC taxonomy code for specialty filtering (e.g., 207R00000X for Internal Medicine).
city	string	--	City name. Works best combined with a state filter.
zip	string	--	ZIP code. Can be used as the sole filter.
providerType	string	all	NPI-1 for individuals (doctors, nurses), NPI-2 for organizations (hospitals, clinics).
lastName	string	--	Provider last name. Supports * wildcard with 2+ leading characters (e.g., Smi*).
organizationName	string	--	Organization name search.
maxItems	integer	100	Maximum records to return.
proxyConfiguration	object	no proxy	Proxy settings. Government API typically needs no proxy.

Search Criteria Rules

The NPPES API requires at least two search criteria. A state alone is not sufficient. Valid combinations:

• State + specialty (taxonomyCode)
• State + city
• State + last name or organization name
• ZIP code alone
• State alone (the crawler auto-generates name prefix queries to satisfy the API requirement)

---

Output Fields

{
  "npi": "1234567890",
  "provider_type": "NPI-1",
  "first_name": "JANE",
  "last_name": "SMITH",
  "credential": "MD",
  "organization_name": "",
  "taxonomy_code": "207R00000X",
  "taxonomy_description": "Internal Medicine",
  "specialty": "Internal Medicine",
  "license_number": "MD12345",
  "license_state": "AZ",
  "address_practice": "1234 E CAMELBACK RD",
  "city_practice": "PHOENIX",
  "state_practice": "AZ",
  "zip_practice": "85016-2345",
  "phone_practice": "(602) 555-0100",
  "fax_practice": "(602) 555-0101",
  "address_mailing": "PO BOX 1234",
  "city_mailing": "PHOENIX",
  "state_mailing": "AZ",
  "zip_mailing": "85001-1234",
  "phone_mailing": "(602) 555-0100",
  "gender": "F",
  "sole_proprietor": "NO",
  "enumeration_date": "2005-06-15",
  "last_update_date": "2024-01-20",
  "other_identifiers": ["MEDICAID: 123456: (AZ)"]
}

Field	Description
npi	10-digit National Provider Identifier
provider_type	NPI-1 (individual) or NPI-2 (organization)
first_name	Provider first name (individuals only)
last_name	Provider last name (individuals only)
credential	Professional credential: MD, DO, NP, PA, DDS, etc.
organization_name	Organization legal name (organizations only)
taxonomy_code	NUCC Healthcare Provider Taxonomy Code
taxonomy_description	Human-readable taxonomy description
specialty	Primary specialty derived from taxonomy
license_number	State license number
license_state	State that issued the license
address_practice	Practice location street address
city_practice	Practice city
state_practice	Practice state abbreviation
zip_practice	Practice ZIP code (formatted as XXXXX-XXXX)
phone_practice	Practice phone formatted as (XXX) XXX-XXXX
fax_practice	Practice fax number
address_mailing	Mailing street address
city_mailing	Mailing city
state_mailing	Mailing state
zip_mailing	Mailing ZIP code
phone_mailing	Mailing phone number
gender	M or F (individuals only)
sole_proprietor	YES, NO, or X
enumeration_date	Date NPI was assigned (YYYY-MM-DD)
last_update_date	Date record was last updated (YYYY-MM-DD)
other_identifiers	Array of other IDs (Medicaid, Medicare, etc.) as formatted strings

---

Supported Taxonomy Codes

The taxonomy dropdown includes the most common healthcare provider specialties:

Code	Specialty
207R00000X	Internal Medicine
208D00000X	General Practice
207Q00000X	Family Medicine
207V00000X	Obstetrics & Gynecology
2084P0800X	Psychiatry
207X00000X	Orthopedic Surgery
207Y00000X	Otolaryngology
208600000X	Surgery
2085R0001X	Radiology
207RG0100X	Gastroenterology
204E00000X	Oral & Maxillofacial Surgery
1223G0001X	General Dentistry
363L00000X	Nurse Practitioner
363A00000X	Physician Assistant
152W00000X	Optometrist
367500000X	Certified Registered Nurse Anesthetist
261QM1300X	Medical Lab
332B00000X	Durable Medical Equipment Supplier

You can also enter any valid NUCC taxonomy code not listed in the dropdown by using the API directly.

---

Performance

• Speed: ~200 records per second. A 100-record run completes in under 5 seconds.
• Memory: 256 MB default. Sufficient for runs of any size since data streams through in batches.
• No proxy cost: The NPPES API is a free government service. No Apify proxy credits are consumed.
• Pricing: Pay-per-event at $0.001 per record ($1 per 1,000 records) plus $0.10 per actor start.

---

Data Source

All data comes from the CMS National Plan & Provider Enumeration System (NPPES), maintained by the Centers for Medicare & Medicaid Services (CMS), a division of the U.S. Department of Health and Human Services. The NPPES NPI Registry is updated continuously as providers create or modify their records. The database contains 2.5M+ active NPI records.