enrich-company-name

用途

本技能用于补全 HubSpot 联系人记录中缺失的公司名称字段。它通过将关联公司记录中的公司名称复制到联系人记录，解决联系人因缺少公司名称而无法匹配 ICP 分类公司、破坏邮件个性化令牌、以及无法参与基于公司的细分等问题。在典型的疏于维护的 CRM 中，即使绝大多数联系人都有关联公司，仍可能有 40-60% 的联系人缺失该字段。

主要能力

审计缺失公司名称的联系人数量（补全前基线）。
通过 HubSpot 工作流持续补全：当联系人公司名称为未知时触发，复制关联公司记录中的名称。
可选 API 回填脚本，用于立即填充数据，无需等待工作流处理。
补全后验证，对比基线并检查剩余未补全联系人。
支持重新注册，当关联公司发生变化时自动重新处理联系人。

使用方式

前置条件

HubSpot Marketing Hub Professional 或 Sales Hub Professional（用于工作流）。
HubSpot 私有应用访问令牌（.env 中的 HUBSPOT_ACCESS_TOKEN），需具备联系人读写权限（用于脚本阶段）。
Python 3.10+ 及 uv。
已完成第一阶段清理流程（先移除无效/已删除联系人）。
已启用 HubSpot 自动关联：设置 > 对象 > 公司 > “创建公司并与联系人关联”开关必须开启。

脚本

补全前：uv run skills/enrich-company-name/scripts/before.py
补全后：uv run skills/enrich-company-name/scripts/after.py

没有执行脚本：补全本身作为 HubSpot 工作流运行，同时处理积压和未来联系人。

计划

如未启用，开启自动关联。
审计缺失公司名称的联系人数量（补全前状态）。
构建工作流，从关联公司记录复制公司名称。
可选：运行 API 回填脚本立即获得结果。
验证补全结果（补全后状态）。

补全前

运行补全前审计以捕获基线：uv run skills/enrich-company-name/scripts/before.py

核心查询：

resp = requests.post(f"{BASE}/crm/v3/objects/contacts/search", headers=HEADERS, json={
    "filterGroups": [{"filters": [
        {"propertyName": "company", "operator": "NOT_HAS_PROPERTY"},
    ]}],
    "limit": 1,
})
print(f"Contacts missing company name: {resp.json()['total']}")

手动方式：转到联系人 > 按公司名称筛选 > 未知。记录数量。保存该数量作为衡量成功的基线。

执行

方法 1：HubSpot 工作流（推荐——处理积压和未来）

转到自动化 > 工作流 > 创建工作流。
选择基于联系人 > 空白工作流。
名称：AUTO-ENRICH: Copy Company Name from Association。
注册触发器：联系人属性 > 公司名称 > 未知。
重新注册：启用“关联公司变化时重新注册”。
操作 1：延迟 10 分钟。此延迟至关重要，因为新联系人进入 HubSpot 后，自动关联引擎需要时间解析电子邮件域名、查找或创建匹配公司并创建关联。
操作 2：If/then 分支。条件：关联公司 > 公司名称（或名称）> 已知。
- YES 分支：添加复制属性操作。复制 FROM：公司 > 名称；复制 TO：联系人 > 公司名称。
- NO 分支：留空（联系人退出）。这些通常是使用个人电子邮件地址（gmail、yahoo 等）的联系人。
激活：点击审查 > 开启。提示时选择“是，注册现有联系人”。这会注册整个积压。

方法 2：API 回填脚本（可选——立即结果）

如果需要立即填充数据而非等待工作流处理，可使用此方法。

# 模式：获取缺失公司名称的联系人，
# 查找其关联公司，复制名称。
# 1. POST /crm/v3/objects/contacts/search  (company NOT_HAS_PROPERTY)
# 2. POST /crm/v4/associations/contacts/companies/batch/read  (获取关联)
# 3. POST /crm/v3/objects/companies/batch/read  (获取公司名称)
# 4. POST /crm/v3/objects/contacts/batch/update  (写入联系人的公司属性)

关键 API 说明：

使用搜索 API 查找 company NOT_HAS_PROPERTY 的联系人。
搜索 API 上限为 10,000 条结果。如需要，按 createdate 范围分段。
使用 Associations API v4 获取联系人与公司的关联。
通过 POST /crm/v3/objects/contacts/batch/update 批量更新联系人（每次 100 条）。
遵守速率限制：每 10 秒 100 个请求。

为什么两者都做？

工作流同时处理积压（激活时注册）和未来联系人，是长期解决方案。API 回填在无法等待工作流处理时提供立即结果。如果只做工作流也完全可以，因为激活时符合触发条件的现有联系人会被注册并处理积压。

补全后

激活工作流后等待 1-2 小时（非常大的数据库需要更长时间），然后验证：uv run skills/enrich-company-name/scripts/after.py（重新运行补全前查询并与基线对比）。

验证清单：

“缺失公司名称”数量应大幅下降（通常从 40-60% 降至 10% 以下）。
剩余无公司名称的联系人应主要是使用个人电子邮件地址（gmail.com、yahoo.com 等）的联系人。
抽查 10-20 个联系人，确认公司名称与其关联公司记录匹配。
检查工作流历史中的错误：属性类型不匹配（复制到错误的字段类型）、多个关联公司（HubSpot 使用主要公司）。
通过检查最近注册情况，验证工作流继续处理新联系人。

回滚

关闭工作流以停止进一步补全（自动化 > 工作流 > 关闭开关）。工作流只填充空字段，因此没有需要“恢复”的内容——但如果复制了错误值（例如来自错误的主要关联），可按工作流注册历史筛选联系人并清除公司属性，或从每个联系人的属性历史恢复值。

适用场景

联系人缺失公司名称，导致无法匹配 ICP 分类公司。
邮件个性化令牌因公司名称缺失而失效。
基于公司的细分无法覆盖缺失公司名称的联系人。
在创建 ICP Tier 工作流之前，需要先完成公司名称补全。

限制

需要 HubSpot Marketing Hub Professional 或 Sales Hub Professional 才能使用工作流。
需要启用 HubSpot 自动关联功能。
使用个人电子邮件域名（gmail.com、yahoo.com、hotmail.com、outlook.com 等）的联系人不会在 NO 分支被补全，需要手动补全或外部提供商。
搜索 API 上限为 10,000 条结果，超出需分段处理。
API 速率限制为每 10 秒 100 个请求。
工作流处理大型数据库可能需要数小时，验证应安排在激活后 2-4 小时。
联系人“公司名称”默认为单行文本字段；如果被改为下拉菜单，复制操作可能失败。
如果联系人关联多个公司，HubSpot 使用主要关联公司。
工作流不会覆盖现有值，因为注册触发器要求“公司名称为未知”。