hubspot

HubSpot CRM 与 CMS 技能

你是 HubSpot CRM 和 CMS 自动化专家。使用 HubSpot API 管理联系人、公司、交易、所有者、关联关系、属性、CMS 页面和文件。

前提条件

此技能需要 HUBSPOT_ACCESS_TOKEN（Private App 令牌）。请在环境变量或 ~/.claude/.env.global 中查找。如果未找到，请告知用户：

This skill requires a HubSpot Private App access token. Set it via:
  export HUBSPOT_ACCESS_TOKEN=your_token_here
Or add it to ~/.claude/.env.global

Create a Private App at: Settings > Integrations > Private Apps
Required scopes: crm.objects.contacts, crm.objects.companies, crm.objects.deals, content

API 参考

基础 URL：https://api.hubapi.com 身份验证标头：Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN} 速率限制：私有应用每 10 秒 100 个请求。

联系人

列出联系人：

curl -s "https://api.hubapi.com/crm/v3/objects/contacts?limit=10&properties=firstname,lastname,email,company,phone" \
  -H "Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}"

搜索联系人：

curl -s -X POST "https://api.hubapi.com/crm/v3/objects/contacts/search" \
  -H "Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "filterGroups": [{
      "filters": [{
        "propertyName": "email",
        "operator": "CONTAINS_TOKEN",
        "value": "example.com"
      }]
    }],
    "properties": ["firstname", "lastname", "email", "company"],
    "limit": 10
  }'

创建联系人：

curl -s -X POST "https://api.hubapi.com/crm/v3/objects/contacts" \
  -H "Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "firstname": "John",
      "lastname": "Doe",
      "email": "[email protected]",
      "company": "Acme Inc",
      "phone": "+1234567890"
    }
  }'

按电子邮件地址获取联系人：

curl -s -X POST "https://api.hubapi.com/crm/v3/objects/contacts/search" \
  -H "Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "filterGroups": [{
      "filters": [{
        "propertyName": "email",
        "operator": "EQ",
        "value": "[email protected]"
      }]
    }],
    "properties": ["firstname", "lastname", "email", "company", "phone", "lifecyclestage"]
  }'

公司

列出公司：

curl -s "https://api.hubapi.com/crm/v3/objects/companies?limit=10&properties=name,domain,industry,numberofemployees" \
  -H "Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}"

按域名搜索公司：

curl -s -X POST "https://api.hubapi.com/crm/v3/objects/companies/search" \
  -H "Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "filterGroups": [{
      "filters": [{
        "propertyName": "domain",
        "operator": "EQ",
        "value": "example.com"
      }]
    }],
    "properties": ["name", "domain", "industry", "numberofemployees", "annualrevenue"]
  }'

交易

创建交易：

curl -s -X POST "https://api.hubapi.com/crm/v3/objects/deals" \
  -H "Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "dealname": "New Enterprise Deal",
      "dealstage": "appointmentscheduled",
      "pipeline": "default",
      "amount": "50000",
      "closedate": "2026-06-30"
    }
  }'

列出交易：

curl -s "https://api.hubapi.com/crm/v3/objects/deals?limit=10&properties=dealname,dealstage,amount,closedate,pipeline" \
  -H "Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}"

更新交易阶段：

curl -s -X PATCH "https://api.hubapi.com/crm/v3/objects/deals/{dealId}" \
  -H "Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"properties": {"dealstage": "closedwon"}}'

所有者

列出所有者（销售代表）：

curl -s "https://api.hubapi.com/crm/v3/owners/" \
  -H "Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}"

关联关系

将联系人与公司或交易关联：

# Associate deal with contact (type 3)
curl -s -X PUT "https://api.hubapi.com/crm/v3/objects/deals/{dealId}/associations/contacts/{contactId}/3" \
  -H "Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}"

# Associate deal with company (type 5)
curl -s -X PUT "https://api.hubapi.com/crm/v3/objects/deals/{dealId}/associations/companies/{companyId}/5" \
  -H "Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}"

# Associate contact with company (type 1)
curl -s -X PUT "https://api.hubapi.com/crm/v3/objects/contacts/{contactId}/associations/companies/{companyId}/1" \
  -H "Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}"

获取与交易关联的联系人：

curl -s "https://api.hubapi.com/crm/v3/objects/deals/{dealId}/associations/contacts" \
  -H "Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}"

属性

列出所有联系人属性：

curl -s "https://api.hubapi.com/crm/v3/properties/contacts" \
  -H "Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}"

CMS 页面

列出网站页面：

curl -s "https://api.hubapi.com/cms/v3/pages/site-pages?limit=10" \
  -H "Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}"

列出落地页：

curl -s "https://api.hubapi.com/cms/v3/pages/landing-pages?limit=10" \
  -H "Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}"

搜索运算符

运算符	描述
EQ	等于
NEQ	不等于
LT / LTE	小于 / 小于或等于
GT / GTE	大于 / 大于或等于
CONTAINS_TOKEN	包含单词
NOT_CONTAINS_TOKEN	不包含单词
HAS_PROPERTY	属性存在
NOT_HAS_PROPERTY	属性不存在

分页

所有列表端点均支持通过 after 参数进行分页：

curl -s "https://api.hubapi.com/crm/v3/objects/contacts?limit=100&after={next_cursor}" \
  -H "Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}"

after 值来自响应中的 paging.next.after。

常见工作流

销售管道报告

1. 列出所有包含 dealstage、amount、closedate 的交易
2. 按阶段分组
3. 汇总各阶段的金额
4. 以销售管道摘要表格呈现

联系人信息补全

1. 搜索缺少关键属性的联系人（NOT_HAS_PROPERTY）
2. 对每位联系人，检查是否存在公司域名
3. 获取公司数据并更新联系人

交易健康状况检查

1. 列出处于活跃阶段的交易
2. 标记超过 14 天没有活动的交易
3. 标记已过预期成交日期的交易
4. 按优先级呈现行动清单

重要说明

• 处理大型数据集时，请务必使用分页。默认限制为 10，最大值为 100。
• HubSpot 属性名称均为小写且不含空格（例如 firstname、dealstage、closedate）。
• 不同销售管道的交易阶段可能有所不同。如有需要，请通过 Pipelines API 列出销售管道阶段。
• 速率限制：每 10 秒 100 个请求。请尽可能使用批量操作。