# NPPES NPI Leads (`foxk1996/nppes-npi-leads`) Actor Scrape public NPPES NPI Registry provider records from the official CMS API for healthcare sales lead generation. Search by state, taxonomy or specialty, and optional city; no login or proxies required. - **URL**: https://apify.com/foxk1996/nppes-npi-leads.md - **Developed by:** [Kronos Fox](https://apify.com/foxk1996) (community) - **Categories:** Business - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing $10.00 / 1,000 provider scrapeds 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/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. Actors are written with capital "A". ## 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. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## NPPES NPI Leads NPPES NPI Leads is an Apify actor for collecting public healthcare provider records from the official CMS NPPES NPI Registry API v2.1. It is designed for compliant healthcare sales lead generation, market mapping, territory research, and provider directory enrichment using public data only. The actor does not require logins, cookies, proxies, or private datasets. ### NPI Registry provider search Searches are built from the criteria that the NPPES API expects: state plus taxonomy or specialty description, with an optional city filter. Example searches include Nurse Practitioner in Pittsburgh, Dentist in TX, Physical Therapist in FL, or Cardiology in NY. The actor sends a descriptive User-Agent with a contact email, applies a polite delay between requests, and uses request timeouts on every network call. ### What you get Each `provider-scraped` dataset row is a flattened lead record with the NPI number, provider or organization name, enumeration type, status, credentials, primary taxonomy code and description, all taxonomy descriptions and codes, location address, mailing address, phone and fax fields when available, authorized official details for organizations, the source label, the query that found the record, and a direct CMS provider-view URL. ### Healthcare sales lead generation use cases Use the dataset to build specialty-specific outreach lists, estimate provider density by city or state, enrich CRM records with NPI and taxonomy data, identify organizations in a target care category, or prepare territory plans for healthcare services. Because the source is CMS NPPES, records may include organizations, individuals, mailing addresses, practice locations, and public phone numbers when the registry provides them. ### How to run Provide one or more two-letter states and one or more taxonomy or specialty descriptions. Optionally add city names to narrow each search. Set `maxResults` to the exact maximum number of provider rows you want. The actor enforces that cap client-side even if the API returns extra rows. The default input is intentionally small and should finish in under five minutes. ### Pricing This actor uses pay-per-event monetization. The single paid event is `provider-scraped` at $0.01 per provider record pushed to the dataset. Error rows are diagnostic and are not charged as provider records. Local or non-PPE runs are protected by a free cap in the actor code. ### FAQ #### Is this official CMS data? The actor reads from the public NPPES NPI Registry API v2.1 hosted by CMS. #### Does it scrape private data? No. It only collects fields returned by the public NPPES API for provider registry records. #### Why do I need at least state and specialty? The NPPES API requires multiple search criteria for broad searches. This actor builds compliant queries from state plus taxonomy or specialty, and optional city. #### Can I deduplicate records? The actor deduplicates NPIs within a run so the same provider is not pushed twice when overlapping city or specialty searches return the same record. # Actor input Schema ## `states` (type: `array`): Two-letter US state abbreviations to search in the NPPES NPI Registry. Each query uses state plus taxonomy or specialty, and optional city. ## `cities` (type: `array`): Optional city names to narrow each state and specialty search. Leave empty to search state plus taxonomy only. ## `taxonomyDescriptions` (type: `array`): NPPES taxonomy_description search values such as Nurse Practitioner, Dentist, Physical Therapist, Cardiology, or Family Medicine. ## `maxResults` (type: `integer`): Hard cap on provider records pushed to the dataset and charged as provider-scraped events. The actor truncates client-side if the API returns more. ## `pageSize` (type: `integer`): Number of records requested per NPPES API page. Smaller values are useful for quick tests; NPPES allows up to 200. ## `requestDelaySeconds` (type: `number`): Polite delay between public CMS API calls. Keep this non-zero to avoid hammering a government endpoint. ## `contactEmail` (type: `string`): Optional contact email included in the descriptive User-Agent sent to the government API. ## Actor input object example ```json { "states": [ "PA" ], "cities": [ "Pittsburgh" ], "taxonomyDescriptions": [ "Nurse Practitioner" ], "maxResults": 25, "pageSize": 25, "requestDelaySeconds": 0.35, "contactEmail": "support@example.com" } ```` # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "states": [ "PA" ], "cities": [ "Pittsburgh" ], "taxonomyDescriptions": [ "Nurse Practitioner" ] }; // Run the Actor and wait for it to finish const run = await client.actor("foxk1996/nppes-npi-leads").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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "states": ["PA"], "cities": ["Pittsburgh"], "taxonomyDescriptions": ["Nurse Practitioner"], } # Run the Actor and wait for it to finish run = client.actor("foxk1996/nppes-npi-leads").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "states": [ "PA" ], "cities": [ "Pittsburgh" ], "taxonomyDescriptions": [ "Nurse Practitioner" ] }' | apify call foxk1996/nppes-npi-leads --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=foxk1996/nppes-npi-leads", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "NPPES NPI Leads", "description": "Scrape public NPPES NPI Registry provider records from the official CMS API for healthcare sales lead generation. Search by state, taxonomy or specialty, and optional city; no login or proxies required.", "version": "0.1", "x-build-id": "DKs8Jyj8D037Vx4os" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/foxk1996~nppes-npi-leads/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-foxk1996-nppes-npi-leads", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/foxk1996~nppes-npi-leads/runs": { "post": { "operationId": "runs-sync-foxk1996-nppes-npi-leads", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/foxk1996~nppes-npi-leads/run-sync": { "post": { "operationId": "run-sync-foxk1996-nppes-npi-leads", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "states", "taxonomyDescriptions" ], "properties": { "states": { "title": "States", "type": "array", "description": "Two-letter US state abbreviations to search in the NPPES NPI Registry. Each query uses state plus taxonomy or specialty, and optional city.", "items": { "type": "string" } }, "cities": { "title": "Cities", "type": "array", "description": "Optional city names to narrow each state and specialty search. Leave empty to search state plus taxonomy only.", "items": { "type": "string" } }, "taxonomyDescriptions": { "title": "Taxonomy or specialty descriptions", "type": "array", "description": "NPPES taxonomy_description search values such as Nurse Practitioner, Dentist, Physical Therapist, Cardiology, or Family Medicine.", "items": { "type": "string" } }, "maxResults": { "title": "Maximum provider records", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Hard cap on provider records pushed to the dataset and charged as provider-scraped events. The actor truncates client-side if the API returns more.", "default": 25 }, "pageSize": { "title": "API page size", "minimum": 1, "maximum": 200, "type": "integer", "description": "Number of records requested per NPPES API page. Smaller values are useful for quick tests; NPPES allows up to 200.", "default": 25 }, "requestDelaySeconds": { "title": "Request delay seconds", "minimum": 0, "maximum": 10, "type": "number", "description": "Polite delay between public CMS API calls. Keep this non-zero to avoid hammering a government endpoint.", "default": 0.35 }, "contactEmail": { "title": "Contact email for User-Agent", "type": "string", "description": "Optional contact email included in the descriptive User-Agent sent to the government API.", "default": "support@example.com" } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```