# US Clinic Owners + Multi-Location DSO & NPI Intelligence (`grandiose_envelope_0fj/us-clinic-owner-leads-scraper`) Actor

🔗 \[Multi-Source Enriched] Extract US healthcare clinic owners (Authorized Officials) from CMS NPPES with E.164 direct phones, cross-joined Multi-Location DSO/MSO chain detection, clinic age (newly opened vs established), and B2B deal value tiering.

- **URL**: https://apify.com/grandiose_envelope_0fj/us-clinic-owner-leads-scraper.md
- **Developed by:** [Olive LI](https://apify.com/grandiose_envelope_0fj) (community)
- **Categories:** Lead generation, Agents, Integrations
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.40 / 1,000 cross-joined enriched lead / 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 Clinic Owners + Multi-Location DSO & NPI Intelligence (Healthcare Executive Lead Engine)

> **Apify Actor Name**: `us-clinic-owner-leads-scraper`\
> **Local Directory**: `/Volumes/Ziyang_Mini/antigravity_project/make_money/apify_actors/us-healthcare-clinic-owner-leads-scraper`\
> **Current Status**: 🟢 `isPublic: true` (Live on Apify Store)\
> **Pricing**: `$2.40 / 1,000 enriched records` (`$0.0024 / item`, upgraded from `$1.80/1k` after adding Multi-Location DSO Chain Detection, Clinic Age & Deal Value Tiering)

***

### 1. 这个爬虫是干什么的？（Core Purpose）

本爬虫是一个**全美医疗诊所老板（Authorized Official / 法人）直联电话提取与连锁集团（DSO/MSO）识别引擎**。\
它基于美国联邦医疗保险和医疗补助服务中心（CMS NPPES NPI Registry v2.1），不仅提取组织机构型诊所（`NPI-2`）的**最高决策人姓名、职位与 E.164 标准直线电话**，还通过**跨记录实体对齐（Entity Resolution by Owner Phone & Executive Name）**，自动识别出哪些老板名下拥有多家连锁诊所（Multi-Location DSO/MSO）、哪些是刚拿证开业不到 18 个月的新建诊所，并按专科高客单属性计算 B2B 签单潜力分级。

***

### 2. 它的商业作用与目标买家（Business Value & Buyer Persona）

- **解决的核心痛点**：
  - 普通 NPI 爬虫只是一维导出 800 万条医生/诊所记录，销售团队分不清哪家是只有 1 个人的小门诊、哪家是控制着 5～20 家门店的牙科/医美连锁老板（DSO/MSO），也分不清哪家是刚开业急需买设备的诊所。
- **目标付费买家（B2B Buyers）**：
  1. **医疗器械与高值耗材厂商**（牙科种植体、医美激光仪、康复理疗设备、超声影像销售团队）；
  2. **医疗诊所 SaaS 与 AI 语音前台厂商**（EHR 电子病历、AI 自动预约电话、医疗账单 RCM 软件 SDR）；
  3. **医疗私募并购基金（Healthcare PE Roll-up）与商业贷款经纪人**。
- **已合并的候选池方向（Merged Ideas）**：
  - ✅ 吸收了候选池中 **`#36 CMS PECOS / 连锁诊所集团归属关联`** 与 **`专科客单价分层模型`**。

***

### 3. 数据源明细（Data Sources & Endpoints）

| 数据源层级 | 官方接口名称 | 接口 Endpoint | 提取的核心数据 |
| :--- | :--- | :--- | :--- |
| **主数据源 A** | **CMS NPPES NPI Registry API v2.1** | `GET https://npiregistry.cms.hhs.gov/api/?version=2.1` | 10 位 NPI 编号、机构法定名称 (`organization_name`)、商业品牌名 (`other_names` DBA)、**法人/老板姓名 (`authorized_official_first/last_name`)、职位 (`authorized_official_title_or_position`)、老板直线电话 (`authorized_official_telephone_number`)**、执业地址、州执照号 (`license`) 与发证日期 (`enumeration_date`) |
| **内部交叉关联引擎 B** | **Cross-Record Entity Resolution** | 内存图聚合 (`owner_direct_phone_e164` + `owner_full_name`) | 统计同一法人电话或同一法人姓名在当前区域关联的诊所门店数 (`owner_locations_in_batch`) 及注册专科数量 (`all_specialties_count`) |

***

### 4. 它执行的具体操作与内在逻辑（Step-by-Step Execution Operations）

代码位于 [`src/main.py`](file:///Volumes/Ziyang_Mini/antigravity_project/make_money/apify_actors/us-healthcare-clinic-owner-leads-scraper/src/main.py)，每次运行执行以下 5 步：

1. **Step 1 · 突破单次 1,200 条限制的分片拉取（[`fetch_npi_leads()`](file:///Volumes/Ziyang_Mini/antigravity_project/make_money/apify_actors/us-healthcare-clinic-owner-leads-scraper/src/main.py#L96-L163)）**：
   - 针对 CMS 官方接口单查询上限 1,200 条的限制，自动按州/城市/邮编前缀构造查询切片队列，仅拉取 `enumeration_type="NPI-2"`（医疗机构法人实体）。
2. **Step 2 · 电话清洗与 E.164 标准化（[`format_us_phone()`](file:///Volumes/Ziyang_Mini/antigravity_project/make_money/apify_actors/us-healthcare-clinic-owner-leads-scraper/src/main.py#L12-L21)）**：
   - 优先提取法人直线电话（`authorized_official_telephone_number`），格式化为 `(XXX) XXX-XXXX` 与 `+1XXXXXXXXXX`（可直接导入 Twilio / HubSpot / GoHighLevel 自动外呼）。
3. **Step 3 · 推导内在逻辑 1：连锁集团与新开诊所识别（`practice_scale_signal`）**：
   - 聚合全部返回记录的老板直线电话与姓名：
     - 若同一老板关联 `>= 2` 家门店或同时具备 `>= 3` 个临床专科资质：标记为 **`MULTI_LOCATION_OR_MULTI_SPECIALTY_GROUP`**（连锁采购决策人，买一套软件可铺多家门店）；
     - 若 `enumeration_date` 距今 `<= 1.8 年`：标记为 **`NEWLY_OPENED_CLINIC_HIGH_CAPEX_NEED (<18 Months Old)`**（新开业诊所，正处于采购设备与 SaaS 的黄金窗口）；
     - 其余标记为 **`ESTABLISHED_INDEPENDENT_CLINIC`**。
4. **Step 4 · 推导内在逻辑 2：B2B 签单客单价分层（[`compute_deal_tier()`](file:///Volumes/Ziyang_Mini/antigravity_project/make_money/apify_actors/us-healthcare-clinic-owner-leads-scraper/src/main.py#L23-L29)）**：
   - 扫描诊所注册的所有 `taxonomies`：
     - 牙科、正畸、医美皮肤、眼科、日间手术中心（自费现金流极高）→ **`HIGH_TICKET_CASH_PAY_SURGICAL ($15k-$50k LTV)`**；
     - 影像、心内、骨科、康复理疗、脊椎指压 → **`SPECIALTY_OUTPATIENT ($8k-$20k LTV)`**；
     - 普通全科门诊 → **`GENERAL_PRIMARY_CARE ($3k-$8k LTV)`**。
5. **Step 5 · 保底快照防挂机制**：
   - 内置 20 条真实洛杉矶诊所老板快照（[`src/fallback_default_leads.json`](file:///Volumes/Ziyang_Mini/antigravity_project/make_money/apify_actors/us-healthcare-clinic-owner-leads-scraper/src/fallback_default_leads.json)）。

***

### 5. 后续可继续升级方向（Future Upgrade Hooks）

1. **合入候选池中的 `#35 CMS Open Payments (药械大厂向医生支付的讲课费/顾问费数据库)`**：通过 NPI 关联该诊所老板每年从美敦力、强生、隐适美等大厂领取的商业赞助金额，精准锁定 KOL 级诊所老板。

# Actor input Schema

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

Filter by specialty (e.g., 'Dental', 'Dermatology', 'Physical Therapy', 'Chiropractic', 'MedSpa', 'Radiology').

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

Two-letter state code (e.g., CA, TX, FL, NY).

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

City name filter (e.g., Los Angeles, Austin, Miami).

## `onlyWithOwnerPhone` (type: `boolean`):

Only return clinics with a verified E.164 direct phone number.

## `detectMultiLocationChains` (type: `boolean`):

Cross-reference owner phone and executive identity to detect multi-location clinic groups (DSO/MSO), newly opened clinics, and high-ticket procedure tiers.

## `maxItems` (type: `integer`):

Maximum number of enriched clinic owner leads to extract (1 to 50,000).

## Actor input object example

```json
{
  "taxonomyDescription": "Dental",
  "state": "CA",
  "city": "Los Angeles",
  "onlyWithOwnerPhone": true,
  "detectMultiLocationChains": true,
  "maxItems": 20
}
```

# Actor output Schema

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

🔗 \[Multi-Source Enriched] Extract US healthcare clinic owners (Authorized Officials) from CMS NPPES with E.164 direct phones, cross-joined Multi-Location DSO/MSO chain detection, clinic age (newly opened vs established), and B2B deal value tiering.

# 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 = {
    "taxonomyDescription": "Dental",
    "state": "CA",
    "city": "Los Angeles",
    "maxItems": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("grandiose_envelope_0fj/us-clinic-owner-leads-scraper").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 = {
    "taxonomyDescription": "Dental",
    "state": "CA",
    "city": "Los Angeles",
    "maxItems": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("grandiose_envelope_0fj/us-clinic-owner-leads-scraper").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 '{
  "taxonomyDescription": "Dental",
  "state": "CA",
  "city": "Los Angeles",
  "maxItems": 20
}' |
apify call grandiose_envelope_0fj/us-clinic-owner-leads-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,grandiose_envelope_0fj/us-clinic-owner-leads-scraper"
        }
    }
}
```

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/19yqaDd3nUcNQt0Xa/builds/h9KGByqT38wew0qZp/openapi.json