# US Aesthetics, MedSpa & Chiro — Organization NPI Leads (`afkdigital/newapi11-organization-npi-clinic-leads`) Actor

Find CMS NPPES NPI-2 organization records and export organization contacts to JSON/CSV with a spending cap.

- **URL**: https://apify.com/afkdigital/newapi11-organization-npi-clinic-leads.md
- **Developed by:** [AFK Digital](https://apify.com/afkdigital) (community)
- **Categories:** Lead generation, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$5.00 / 1,000 unique npi-2 organization 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

## US Aesthetics, MedSpa & Chiro Organization NPI Extractor — NEWAPI11

**Publisher:** AFK MESH | **Actor:** `newapi11-organization-npi-clinic-leads` | **Release:** 1.0.0

Search the official **CMS NPPES NPI Registry API v2.1** for **Type 2 / NPI-2 organizations** in U.S. healthcare, aesthetics-adjacent clinic groups, medspa-adjacent organizations, and chiropractic-related businesses. Export a structured flat dataset for Clay, n8n, spreadsheets, and API workflows.

**Important:** An NPI is an administrative identifier, **not** proof of a clinical license, specialty certification, operating status, suitability, or direct marketing consent. Taxonomy and contact fields are self-reported CMS data and can be missing or out of date. This Actor does **not** collect patient records, treatment records, or send messages.

### Data source and permitted scope

- Only `https://npiregistry.cms.hhs.gov/api/?version=2.1` is used for records.
- Only results whose `enumeration_type` equals `NPI-2` become outputs. Individual clinicians (NPI-1) belong to a separate product and are never emitted here.
- The CMS API accepts `taxonomy_description`, not an arbitrary taxonomy *code*. Known codes have query-description hints; all requested codes are always verified against the returned actual `taxonomies[].code`. For unknown codes, use an additional city, organization name, or description filter; the result is still locally filtered.
- "MedSpa", "aesthetics" and "chiropractic" do **not** necessarily map to standalone NPPES organization taxonomy descriptions. Use organization name or a real taxonomy description, and review the resulting records. Searching for `taxonomyDescription: "Chiropractic"` may return a CMS API error; this is not suppressed.
- CMS limits result pages to **200** and `skip` to **1,000**; do not expect more than 1,200 matches per query. CMS announced hourly query limits effective June 25, 2024. This Actor intentionally caps requests to at most 8 per run, with a minimum 1.1-second interval, a 12-second request timeout and bounded retries/backoff. A real bulk or national enumeration needs the official **NPPES Downloadable File V.2** (and relevant reference files), not repeated unrestricted API searches.

### Input

```json
{
  "state": "NY",
  "city": "Albany",
  "taxonomyDescription": "Clinic/Center",
  "taxonomyCode": "",
  "organizationName": "",
  "maxResults": 20,
  "maxCostUsd": 0.10,
  "maxApiRequests": 3
}
```

- `state` (USPS abbreviation), `city`, `taxonomyDescription`, `taxonomyCode`, `organizationName` narrow the CMS search. State-only and type-only queries are rejected because CMS requires an additional search field.
- `maxResults`: maximum unique NPI-2 rows, 1–1,200; not a promise of available matches.
- `maxCostUsd`: maximum event charges **per run**, US$0 to US$6. The output cap is `min(maxResults, floor(maxCostUsd / 0.005))`. Zero produces an empty dataset and no CMS calls.
- `maxApiRequests`: at most 1–8 CMS result pages; defaults to 3. The default narrow Albany search normally finishes well below five minutes.
- The user can separately set Apify's platform **maximum charge per run**. When available in the runtime, the Actor additionally constrains its local event budget to this value.

### Output (one row per unique NPI-2)

`organization_npi`, `clinic_legal_name`, `dba_name`, `taxonomy_code`, `taxonomy_desc`, `practice_address`, `business_phone`, `authorized_official_name`, `official_title`, `source_url`, `observed_at`.

Missing fields use **JSON null**, never fabricated placeholders. The `practice_address` and `business_phone` are based on the **LOCATION** address and telephone only (never a private personal/mobile inference). `dba_name` comes from an explicitly classified Doing Business As other-name entry. The selected taxonomy is the requested exact code, matched description, or primary taxonomy, in that priority order. `observed_at` is a UTC ISO timestamp showing when the API response was observed.

### Billing — US$0.005 per unique result

Configure Apify **Pay per event** with the synthetic event **`apify-default-dataset-item` = $0.005** and no extra paid event, with platform usage included. The Actor performs **one `Actor.pushData()` per unique NPI-2** in each run; no manual second charge is made. Duplicate NPIs across CMS pages within a run are excluded **before** saving/charging. Record generation for a separate later run is a new user purchase and may legitimately incur a new charge. This actor does not promise global cross-run free re-downloads.

If the Apify UI adds a separately priced synthetic actor-start event, remove it or set to $0 to keep exactly $5.00 for 1,000 records. The product price is not active until confirmed on the published Actor's pricing settings. The creator pays platform usage out of revenue. Apify's commission is 20% (the creator receives 80% before infrastructure cost). Do not publish paid until cloud monetization has been checked.

### Clay / n8n / CSV

The default Apify dataset provides JSON and CSV exports natively:

- JSON: `https://api.apify.com/v2/datasets/{DATASET_ID}/items?format=json&clean=true`
- CSV: `https://api.apify.com/v2/datasets/{DATASET_ID}/items?format=csv&clean=true`

Use Apify's dataset integration/HTTP Request node in n8n or Apify integration in Clay. Keep private dataset API access keys in the destination integration's credential manager; no token appears in this source, request URLs, files, or logs. Do not use this data for prohibited unsolicited outreach.

### Local QA

```bash
npm ci
npm test
npm run smoke
npm start
```

`npm run smoke` performs two tiny real-CMS runs (NY / CA), writes JSON/CSV samples to `samples/` and a check report to `reports/live-tests.json`. It does not bill Apify. Local Actor runs can supply `storage/key_value_stores/default/INPUT.json`. Tests include NPI-1 rejection, duplicate NPI suppression, exact taxonomy code matching, missing DBA and phone behavior, cost cap, HTTP 429 backoff, and CMS JSON error detection. No API key is needed for CMS queries.

### Versioning and guardrails

- Version: **1.0.0** (`.actor/actor.json`: `1.0`)
- Server path: `/opt/NEWAPI/NEWAPI11`
- Scope: this directory alone. Existing `/opt/APIFY`, `API01`–`API30`, other `NEWAPI` remain untouched.
- No patient datasets; no credential or license claims; no automatic emails/SMS.
- Links: [CMS Registry](https://npiregistry.cms.hhs.gov/), [CMS bulk V.2 files](https://download.cms.gov/nppes/NPI_Files.html), [Apify PPE](https://docs.apify.com/actors/publishing/monetize/pay-per-event).

# Actor input Schema

## `state` (type: `string`):

US state (e.g. NY, CA). A state alone is not a sufficient CMS search filter.

## `city` (type: `string`):

City to narrow the query.

## `taxonomyDescription` (type: `string`):

CMS looks up descriptions, not NUCC codes. Example: Clinic/Center. MedSpa/chiro are not guaranteed NPPES classifications.

## `taxonomyCode` (type: `string`):

Match this exact code against the returned NPI-2 organization's taxonomy list. Known codes are converted to search hints; unknown codes require additional city/name/description filters.

## `organizationName` (type: `string`):

Search organization legal names and additional name records as indexed by CMS.

## `maxResults` (type: `integer`):

Maximum dataset rows (1–1200; also constrained by spending and page caps).

## `maxCostUsd` (type: `number`):

Hard ceiling for $0.005 events in this run. The Apify platform can separately enforce its max total charge. Zero returns no rows. Max $6.

## `maxApiRequests` (type: `integer`):

Maximum pages requested per run, 1–8, with controlled delay. Large-scale discovery should use official NPPES downloadable files.

## Actor input object example

```json
{
  "state": "NY",
  "city": "Albany",
  "taxonomyDescription": "Clinic/Center",
  "maxResults": 20,
  "maxCostUsd": 0.1,
  "maxApiRequests": 3
}
```

# Actor output Schema

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

No description

# 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 = {
    "state": "NY",
    "city": "Albany",
    "taxonomyDescription": "Clinic/Center"
};

// Run the Actor and wait for it to finish
const run = await client.actor("afkdigital/newapi11-organization-npi-clinic-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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "state": "NY",
    "city": "Albany",
    "taxonomyDescription": "Clinic/Center",
}

# Run the Actor and wait for it to finish
run = client.actor("afkdigital/newapi11-organization-npi-clinic-leads").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 '{
  "state": "NY",
  "city": "Albany",
  "taxonomyDescription": "Clinic/Center"
}' |
apify call afkdigital/newapi11-organization-npi-clinic-leads --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,afkdigital/newapi11-organization-npi-clinic-leads"
        }
    }
}
```

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/fJXLWty202g4um0C4/builds/V2tBgFGT6r5cDkBbx/openapi.json