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

{
  "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

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, CMS bulk V.2 files, Apify PPE.