通过 HubSpot API 管理 CRM 与 CMS…

当需要管理 HubSpot CRM 联系人、公司、交易、负责人、关联、属性或 CMS 页面时，用 HubSpot Private App token 调用 HubSpot API。

适用场景

解决思路

1. 检查环境变量 HUBSPOT_ACCESS_TOKEN，或检查 ~/.claude/.env.global；未找到时提示用户设置 export HUBSPOT_ACCESS_TOKEN=your_token_here 或加入 ~/.claude/.env.global。
2. 让用户到 HubSpot Settings > Integrations > Private Apps 创建 Private App，所需 scopes 为 crm.objects.contacts、crm.objects.companies、crm.objects.deals、content。
3. 使用 Base URL https://api.hubapi.com，请求头设置 Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}；Private App 速率限制为 100 requests per 10 seconds。
4. 列出联系人：GET https://api.hubapi.com/crm/v3/objects/contacts?limit=10&properties=firstname,lastname,email,company,phone，并带 Bearer token 请求头。
5. 搜索联系人：POST https://api.hubapi.com/crm/v3/objects/contacts/search，Content-Type: application/json，body 使用 filterGroups/filters，指定 propertyName、operator、value，并传 properties 与 limit。
6. 创建联系人：POST https://api.hubapi.com/crm/v3/objects/contacts，Content-Type: application/json，body 的 properties 包含 firstname、lastname、email、company、phone。
7. 按邮箱获取联系人：POST https://api.hubapi.com/crm/v3/objects/contacts/search，filters 设置 propertyName=email、operator=EQ、value=john@example.com，properties 包含 firstname、lastname、email、company、phone、lifecyclestage。
8. 列出公司：GET https://api.hubapi.com/crm/v3/objects/companies?limit=10&properties=name,domain,industry,numberofemployees，并带 Bearer token 请求头。
9. 按域名搜索公司：POST https://api.hubapi.com/crm/v3/objects/companies/search，filters 设置 propertyName=domain、operator=EQ、value=example.com，properties 包含 name、domain、industry、numberofemployees、annualrevenue。
10. 创建交易：POST https://api.hubapi.com/crm/v3/objects/deals，Content-Type: application/json，body 的 properties 包含 dealname、dealstage、pipeline、amount、closedate。
11. 列出交易：GET https://api.hubapi.com/crm/v3/objects/deals?limit=10&properties=dealname,dealstage,amount,closedate,pipeline，并带 Bearer token 请求头。
12. 更新交易阶段：PATCH https://api.hubapi.com/crm/v3/objects/deals/{dealId}，Content-Type: application/json，body 的 properties 设置 dealstage 为 closedwon。
13. 列出负责人（销售代表）：GET https://api.hubapi.com/crm/v3/owners/，并带 Bearer token 请求头。
14. 关联交易与联系人：PUT https://api.hubapi.com/crm/v3/objects/deals/{dealId}/associations/contacts/{contactId}/3。
15. 关联交易与公司：PUT https://api.hubapi.com/crm/v3/objects/deals/{dealId}/associations/companies/{companyId}/5。
16. 关联联系人与公司：PUT https://api.hubapi.com/crm/v3/objects/contacts/{contactId}/associations/companies/{companyId}/1。
17. 获取交易关联联系人：GET https://api.hubapi.com/crm/v3/objects/deals/{dealId}/associations/contacts。
18. 列出联系人属性：GET https://api.hubapi.com/crm/v3/properties/contacts，并带 Bearer token 请求头。
19. 列出站点页面：GET https://api.hubapi.com/cms/v3/pages/site-pages?limit=10，并带 Bearer token 请求头。
20. 列出落地页：GET https://api.hubapi.com/cms/v3/pages/landing-pages?limit=10，并带 Bearer token 请求头。
21. 搜索操作符可用：EQ、NEQ、LT、LTE、GT、GTE、CONTAINS_TOKEN、NOT_CONTAINS_TOKEN、HAS_PROPERTY、NOT_HAS_PROPERTY。
22. 分页：所有列表端点支持 after 参数，例如 GET ...?limit=100&after={next_cursor}；after 值来自响应的 paging.next.after。
23. Pipeline Report 工作流：列出所有 deals 的 dealstage、amount、closedate；按 stage 分组；对每个 stage 汇总 amount；以 pipeline summary table 呈现。
24. Contact Enrichment 工作流：用 NOT_HAS_PROPERTY 搜索缺少关键属性的联系人；逐个检查公司域名是否存在；拉取公司数据并更新联系人。
25. Deal Health Check 工作流：列出 active stages 中的 deals；标记 14+ 天无活动的 deal；标记超过预期 close date 的 deal；呈现按优先级排序的行动列表。
26. 处理大数集时始终分页；默认 limit 为 10，最大为 100。
27. HubSpot 属性名使用小写且无空格，例如 firstname、dealstage、closedate。
28. Deal stages 会随 pipeline 不同而变化；需要时通过 Pipelines API 列出 pipeline stages。
29. 遵守速率限制 100 requests per 10 seconds；尽量使用批量操作。

适用边界 · 注意事项

• 没有 HUBSPOT_ACCESS_TOKEN 或无法创建 HubSpot Private App 时不要使用。
• Private App 缺少所需 scopes（crm.objects.contacts、crm.objects.companies、crm.objects.deals、content）时不要使用。
• 需要操作非 HubSpot CRM/CMS，或需要超过速率限制且无法批量处理时不要使用。