Us Healthcare Npi Medical Practice Lead Enricher

Find US medical practices, their authorized decision makers, and official contact details directly from the federal NPPES NPI Registry.

Build prospect lists for dental practices, medical clinics, physical therapy centers, laboratories, and other registered healthcare organizations. Optionally confirm their public websites and collect homepage emails, social links, and booking software signals. No browser or API key is required for the federal registry search.

Best for healthcare organization research and practice enrichment. Each successful row is an NPI record. An authorized official is not necessarily the owner; use narrow geographic queries to work within the registry search limit and improve relevance.

Ready-to-run example

The Input form includes public example values. A fresh apify run uses the input schema defaults. To explicitly select the small sample, including when input was saved by an earlier local run, use:

apify run --input-file .actor/input.example.json

You can also paste .actor/input.example.json into the JSON input editor in Apify Console. Replace the example sources with your own targets and increase the limits when you are ready.

How to use

1. Select a specialty and a two-letter state abbreviation.
2. Optionally narrow the search by city or ZIP code. Clear City to search an entire state; omitting City retains the Austin default.
3. Keep Organizations and practices (NPI-2) selected for organization leads. Choose NPI-1 for individual providers.
4. Enable website enrichment if you also need public homepage contacts and booking software.
5. Set the maximum saved records, run the Actor, and download JSON, CSV, Excel, or XML from the dataset.

The prefilled sample finds three dentists in Austin, Texas, with website enrichment disabled. The specified maxItems default is 100; the Console prefill is 3. On an available network, the direct sample normally completes within a few seconds. Federal API outages and throttling can affect timing.

{
  "taxonomyDescription": "Dentist",
  "state": "TX",
  "city": "AUSTIN",
  "enumerationType": "NPI-2",
  "enrichWebsiteAndContacts": false,
  "maxItems": 3,
  "timeoutSecs": 15
}

What data can you extract?

Data	Output fields
Federal provider identity	npiNumber, enumerationType, organizationName, dbaName
Specialty	primaryTaxonomyCode, specialtyDescription
Authorized official	authorizedOfficialFullName, authorizedOfficialTitle, authorizedOfficialPhone
Practice location	practicePhone, practiceFax, streetAddress, city, state, zipCode
Registration signals	enumerationDate, isNewlyRegistered90Days
Optional website contacts	discoveredWebsite, primaryEmail, allEmails, instagramUrl, facebookUrl
Booking software	bookingWidgetDetected: NexHealth, Zocdoc, LocalMed, Calendly, JaneApp, Mindbody
Result diagnostics	status, scrapedAt, errorMessage

The authorized official is the person listed by NPPES, such as an owner, officer, administrator, or director. Their registry title and telephone are reported as supplied; the Actor does not assert that the number is a personal line. NPI-1 records normally have no authorized official. organizationName holds the individual provider's full name in those records.

The primary practice address comes exclusively from LOCATION, never from a mailing address. The 90-day flag uses the enumeration date and UTC extraction time, excluding future dates. Missing strings remain empty; missing collections are empty arrays. allEmails and bookingWidgetDetected are arrays in an otherwise flat record.

Input settings

Setting	Default	Details
taxonomyDescription	Dentist	NPPES specialty description, 2–120 characters. Examples: Physical Therapist, Clinical Medical Laboratory, Clinic/Center.
state	TX	US state or territory abbreviation.
city	AUSTIN	Optional. Use "" to remove this filter.
postalCode	Empty	Optional five-digit ZIP or ZIP+4. Clear City when searching another city.
enumerationType	NPI-2	NPI-2 organizations or NPI-1 individuals.
enrichWebsiteAndContacts	false	Best-effort public website discovery and homepage inspection.
maxItems	100	1–5,000 saved rows, including errors; prefilled sample: 3.
timeoutSecs	15	3–60 seconds per HTTP operation, including fallbacks.
maxConcurrency	25	1–100 simultaneous optional enrichments. Federal pagination stays sequential.
proxyConfiguration	Automatic direct-first	Optional Apify proxy editor. See proxy behavior below.

MedSpa searches: NPPES does not define one universal MedSpa taxonomy. Select the relevant registered medical specialty; providers without an NPI do not appear in the registry.

Proxy behavior: Federal NPPES requests always use direct access and incur no proxy traffic fees. Website requests try direct access first. HTTP 403, 429, or 503 can trigger a SHADER datacenter attempt, followed by the account's default datacenter proxy if available. Configured groups, including residential groups, are used only when useApifyProxy: true is explicitly selected. Custom proxy URLs are used as the selected transport. useApifyProxy: false with no custom proxy URLs forces direct access. Proxy availability and traffic fees depend on the account.

Website confirmation: Search results and public NPPES endpoint URLs supply candidates. The Actor checks up to three candidates per discovery stage and requires practice-name evidence plus a matching practice telephone or street/city/state address. Directory pages and social platforms are excluded as practice websites. Only a confirmed public website supplies contacts. No candidate is guessed or fabricated. A missing website is a supported outcome.

Output example

This illustrative record shows the output shape. Contact details and NPI below are fictional sample data, not a live healthcare listing.

{
  "npiNumber": "1234567890",
  "status": "SUCCESS",
  "enumerationType": "NPI-2",
  "organizationName": "AUSTIN EXAMPLE DENTAL PLLC",
  "dbaName": "AUSTIN EXAMPLE DENTAL",
  "primaryTaxonomyCode": "1223G0001X",
  "specialtyDescription": "Dentist, General Practice",
  "authorizedOfficialFullName": "ALEX J SMITH",
  "authorizedOfficialTitle": "OWNER",
  "authorizedOfficialPhone": "5125550101",
  "practicePhone": "512-555-0100",
  "practiceFax": "512-555-0199",
  "streetAddress": "123 MAIN ST SUITE 100",
  "city": "AUSTIN",
  "state": "TX",
  "zipCode": "787011234",
  "enumerationDate": "2026-09-01",
  "isNewlyRegistered90Days": true,
  "discoveredWebsite": "",
  "primaryEmail": "",
  "allEmails": [],
  "bookingWidgetDetected": [],
  "instagramUrl": "",
  "facebookUrl": "",
  "scrapedAt": "2026-10-20T12:00:00.000Z",
  "errorMessage": ""
}

SUCCESS means an official practice record with a valid NPI, name, and location was extracted. Optional enrichment failure preserves this status and adds a safe note such as WEBSITE_NOT_CONFIRMED. A successfully salvaged partial homepage can add PARTIAL_HTML_SALVAGED; absence of an email or booking widget then reflects only the available page prefix. ERROR indicates a failed registry request or incomplete official record and carries no custom event fee. A failed query produces one diagnostic row because no individual providers can be identified from an unavailable page. Zero matches produces an empty dataset.

Use the results in Clay, n8n, Make, or your API

• Clay: Import the dataset as CSV or JSON. Use npiNumber as a stable deduplication key and map the authorized official, practice phone, and confirmed email into your enrichment table.
• n8n: Run the Actor using the Apify integration, retrieve the dataset after completion, filter status to SUCCESS, and send rows to your CRM.
• Make: Connect an Apify run-completed trigger to dataset retrieval and your destination application.
• API: The Actor output links to the run's default dataset. The Apify dataset items endpoint supports format=json and clean=true. Use your normal Apify connection for private datasets.

Use the overview dataset view to inspect human-readable columns before export. Potential spreadsheet formula strings are escaped, while valid telephone numbers and numeric strings retain their values.

Pricing and limits

The custom pay-per-event event is practice-enriched. Each saved SUCCESS record can incur one event fee, including registry-only extraction and records with unavailable optional website enrichment. ERROR rows cost $0 in custom event fees. Both statuses count toward maxItems and the free-account cap.

The Store price is configured separately on Apify; this repository does not assign a live Store price. For a concrete example, at $0.001 per successful practice, 1,000 successful records cost $1.00 in event fees. A run with 900 successful records and 100 error rows costs $0.90 in event fees at that example rate. Actual Store event prices, platform compute/storage charges, any platform events, and optional proxy traffic can differ. Check the Actor's Pricing tab for the active rate.

Free Apify accounts can save at most 25 rows per run. Paid accounts and local runs can save up to the requested maximum of 5,000. The Actor checks only the platform-provided paying flags and supports limited permissions without querying user profile endpoints. It stops cleanly when the custom event budget is exhausted and never applies that event to an ERROR row.

NPPES returns up to 200 records per request and accepts offsets through 1,000. Saturated searches are subdivided using postal prefixes, with NPIs deduplicated across pages. A ZIP that still saturates the API's 1,200-record window is reported in the logs; narrow the city or specialty to retrieve additional records. Registry coverage, upstream limits, and outages can produce fewer results than requested. Exact ZIP and ZIP+4 searches retain their original scope.

FAQ and troubleshooting

Why are some official or contact fields empty? NPPES records are provider-reported. Individual providers normally have no authorized official, and some practices do not publish email addresses. The Actor does not invent missing details.

Why was no website confirmed? The practice may use a different brand, have an unindexed or blocked site, or publish insufficient matching identity evidence. Official registry details remain usable. Discovery and contacts are best effort, not guaranteed coverage.

Will this find every email or booking integration? Only public homepage content and links are inspected. Browser-rendered contacts, protected pages, hidden booking integrations, and contact-page-only emails may not appear. Detection reports a vendor signal, not an assertion that an appointment can currently be booked.

Why is my ZIP search empty? City defaults to Austin even when omitted. Set city to "" when searching another area. Use an official NPPES specialty description; an arbitrary marketing category may not match a taxonomy.

What do HTTP and network errors mean? Safe codes such as HTTP_ERROR, TIMEOUT, or CERT_HAS_EXPIRED identify the affected public host. Per-target failures produce diagnostic rows or enrichment notes and do not crash the run. Invalid input is the only application-level reason to exit with code 1.

Can I use the data for provider credentialing? An NPI identifies a registered provider. It does not establish a current professional license, credentialing status, availability, or endorsement. Consult the relevant official sources for those checks.

Local development and deployment

Use Node.js 22 or newer:

npm ci --ignore-scripts
npm run build
npm test
npm run smoke
npm run smoke:enrich

npm test uses node:test and sets UV_THREADPOOL_SIZE=64, NODE_ENV=production, and strict TLS in its child process. npm run smoke makes a real, direct, three-record NPPES request and verifies the extracted practice fields. Run it with UV_THREADPOOL_SIZE=64 and NODE_ENV=production set in your shell for production-equivalent settings. Node.js receives these variables before startup. npm start reads the normal Apify INPUT record; with no local input it uses the documented defaults. No .env file is required or loaded.

The multi-stage node:22-alpine Dockerfile builds and tests the project, prunes development dependencies, and runs as the non-root node user with a 160 MB JavaScript heap ceiling. Container defaults are 256 MB memory and a 3,600-second run timeout. Publish or connect this directory through the Apify Console or CLI using the included Actor and storage schemas.

Before enabling Store monetization, register the practice-enriched event and its intended price in Apify's pay-per-event configuration. Verify the run's maximum charge in a test run. To keep error rows free of all event fees, do not configure a paid automatic default-dataset-item event. The SDK's platform pricing is the authority; unknown or inactive custom events are not charged by this Actor. Select LIMITED_PERMISSIONS in the Actor's deployment settings; the code requires no user-profile permission.

The implementation caps decompressed responses at 4 MB for HTML, 2 MB for JSON, and 15 MB for XML. HTML parsing has no external-entity resolution and caps nesting at 128. Public IP validation, DNS pinning, per-hop redirect checks, and TLS verification protect both direct connections and proxy tunnels. Dataset writes are serialized in batches of 100 or every five seconds. Abort, SIGTERM, and SIGINT stop network work and flush completed rows before shutdown. An ambiguous dataset write is not retried automatically, preventing duplicate billed writes; a safe terminal status reports the storage failure.

Official references: NPPES API, Apify charging manager, Actor definition.