HubSpot

2026-03-28 新闻来源：网淘吧围观:12

电脑广告

手机广告

HubSpot

通过托管的OAuth认证访问HubSpot CRM API。创建和管理联系人、公司、交易及其关联。

快速开始

# List contacts
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/hubspot/crm/v3/objects/contacts?limit=10&properties=email,firstname,lastname')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

基础URL

https://gateway.maton.ai/hubspot/{native-api-path}

将{native-api-path}替换为实际的HubSpot API端点路径。网关将请求代理到api.hubapi.com并自动注入您的OAuth令牌。

认证

所有请求都需要在Authorization头中包含Maton API密钥：

Authorization: Bearer $MATON_API_KEY

环境变量：将您的API密钥设置为MATON_API_KEY：

export MATON_API_KEY="YOUR_API_KEY"

获取您的API密钥

登录或创建一个账户，访问maton.ai
前往maton.ai/settings
复制您的API密钥

连接管理

在https://ctrl.maton.ai管理您的 HubSpot OAuth 连接。

列出连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=hubspot&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

创建连接

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'hubspot'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

获取连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

响应：

{
  "connection": {
    "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
    "status": "ACTIVE",
    "creation_time": "2025-12-08T07:20:53.488460Z",
    "last_updated_time": "2026-01-31T20:03:32.593153Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "hubspot",
    "metadata": {}
  }
}

在浏览器中打开返回的网址以完成 OAuth 授权。

删除连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

指定连接

如果您有多个 HubSpot 连接，请使用Maton-Connection请求头来指定要使用哪一个：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/hubspot/crm/v3/objects/contacts')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

如果省略，网关将使用默认（最早创建的）活动连接。

API 参考

联系人

列出联系人

GET /hubspot/crm/v3/objects/contacts?limit=100&properties=email,firstname,lastname,phone

带分页：

GET /hubspot/crm/v3/objects/contacts?limit=100&properties=email,firstname&after={cursor}

获取联系人

GET /hubspot/crm/v3/objects/contacts/{contactId}?properties=email,firstname,lastname

创建联系人

POST /hubspot/crm/v3/objects/contacts
Content-Type: application/json

{
  "properties": {
    "email": "john@example.com",
    "firstname": "John",
    "lastname": "Doe",
    "phone": "+1234567890"
  }
}

更新联系人

PATCH /hubspot/crm/v3/objects/contacts/{contactId}
Content-Type: application/json

{
  "properties": {
    "phone": "+0987654321"
  }
}

删除联系人

DELETE /hubspot/crm/v3/objects/contacts/{contactId}

搜索联系人

POST /hubspot/crm/v3/objects/contacts/search
Content-Type: application/json

{
  "filterGroups": [{
    "filters": [{
      "propertyName": "email",
      "operator": "EQ",
      "value": "john@example.com"
    }]
  }],
  "properties": ["email", "firstname", "lastname"]
}

公司

列出公司

GET /hubspot/crm/v3/objects/companies?limit=100&properties=name,domain,industry

获取公司

GET /hubspot/crm/v3/objects/companies/{companyId}?properties=name,domain,industry

创建公司

POST /hubspot/crm/v3/objects/companies
Content-Type: application/json

{
  "properties": {
    "name": "Acme Corp",
    "domain": "acme.com",
    "industry": "COMPUTER_SOFTWARE"
  }
}

注意：行业属性需要特定的枚举值（例如：计算机软件、金融、医疗保健）。请使用“列出属性”端点获取有效值。

更新公司

PATCH /hubspot/crm/v3/objects/companies/{companyId}
Content-Type: application/json

{
  "properties": {
    "industry": "COMPUTER_SOFTWARE",
    "numberofemployees": "50"
  }
}

删除公司

DELETE /hubspot/crm/v3/objects/companies/{companyId}

搜索公司

POST /hubspot/crm/v3/objects/companies/search
Content-Type: application/json

{
  "filterGroups": [{
    "filters": [{
      "propertyName": "domain",
      "operator": "CONTAINS_TOKEN",
      "value": "*"
    }]
  }],
  "properties": ["name", "domain"],
  "limit": 10
}

交易

列出交易

GET /hubspot/crm/v3/objects/deals?limit=100&properties=dealname,amount,dealstage

获取交易

GET /hubspot/crm/v3/objects/deals/{dealId}?properties=dealname,amount,dealstage

创建交易

POST /hubspot/crm/v3/objects/deals
Content-Type: application/json

{
  "properties": {
    "dealname": "New Deal",
    "amount": "10000",
    "dealstage": "appointmentscheduled"
  }
}

更新交易

PATCH /hubspot/crm/v3/objects/deals/{dealId}
Content-Type: application/json

{
  "properties": {
    "amount": "15000",
    "dealstage": "qualifiedtobuy"
  }
}

删除交易

DELETE /hubspot/crm/v3/objects/deals/{dealId}

关联（v4 API）

关联对象

PUT /hubspot/crm/v4/objects/{fromObjectType}/{fromObjectId}/associations/{toObjectType}/{toObjectId}
Content-Type: application/json

[{"associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 279}]

常见关联类型ID：

279- 联系人关联公司
3- 交易关联联系人
341- 交易关联公司

列出关联

GET /hubspot/crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}

批量操作

批量读取

POST /hubspot/crm/v3/objects/{objectType}/batch/read
Content-Type: application/json

{
  "properties": ["email", "firstname"],
  "inputs": [{"id": "123"}, {"id": "456"}]
}

批量创建

POST /hubspot/crm/v3/objects/{objectType}/batch/create
Content-Type: application/json

{
  "inputs": [
    {"properties": {"email": "one@example.com", "firstname": "One"}},
    {"properties": {"email": "two@example.com", "firstname": "Two"}}
  ]
}

批量更新

POST /hubspot/crm/v3/objects/{objectType}/batch/update
Content-Type: application/json

{
  "inputs": [
    {"id": "123", "properties": {"firstname": "Updated"}},
    {"id": "456", "properties": {"firstname": "Also Updated"}}
  ]
}

批量归档

POST /hubspot/crm/v3/objects/{objectType}/batch/archive
Content-Type: application/json

{
  "inputs": [{"id": "123"}, {"id": "456"}]
}

属性

列出属性

GET /hubspot/crm/v3/properties/{objectType}

搜索运算符

EQ- 等于
NEQ- 不等于
LT/LTE- 小于 / 小于等于
大于/大于等于- 大于 / 大于或等于
包含标记- 包含标记
不包含标记- 不包含标记

分页

列表端点返回一个paging.next.after游标：

{
  "results": [...],
  "paging": {
    "next": {
      "after": "12345"
    }
  }
}

使用after查询参数获取下一页：

GET /hubspot/crm/v3/objects/contacts?limit=100&after=12345

代码示例

JavaScript

const response = await fetch('https://gateway.maton.ai/hubspot/crm/v3/objects/contacts', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.MATON_API_KEY}`
  },
  body: JSON.stringify({
    properties: { email: 'john@example.com', firstname: 'John' }
  })
});

Python

import os
import requests

response = requests.post(
    'https://gateway.maton.ai/hubspot/crm/v3/objects/contacts',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
    json={'properties': {'email': 'john@example.com', 'firstname': 'John'}}
)

注意事项

批量操作每次请求最多支持100条记录
归档/删除是软删除 - 记录可在90天内恢复
删除端点成功时返回HTTP 204（无内容）
该行业属性对公司需要特定的枚举值
重要提示：使用 curl 命令时，若 URL 包含括号（fields[]、sort[]、records[]）时，请使用curl -g来禁用通配符解析
重要提示：将 curl 输出通过管道传递给jq或其他命令时，在某些 shell 环境中，类似$MATON_API_KEY的环境变量可能无法正确展开。通过管道传递时，您可能会遇到“无效的 API 密钥”错误。

错误处理

状态码	含义
400	缺少 HubSpot 连接
401	无效或缺少 Maton API 密钥
429	请求频率受限（每个账户每秒10次请求）
4xx/5xx状态码错误	HubSpot API透传错误

故障排查：API密钥问题

请检查MATON_API_KEY环境变量是否已设置：

echo $MATON_API_KEY

通过列出连接验证API密钥有效性：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

故障排查：无效应用名称

请确保URL路径以hubspot开头。例如：

正确示例：https://gateway.maton.ai/hubspot/crm/v3/objects/contacts
错误示例：https://gateway.maton.ai/crm/v3/objects/contacts

资源文档

免责申明

部分文章来自各大搜索引擎，如有侵权，请与我联系删除。

打赏

文章底部电脑广告

手机广告位-内容正文底部

标签

上一篇：SendClaw Email - Bots & Agents get their own email address 下一篇：Win Mouse Native (Windows)

HubSpot

HubSpot

快速开始

基础URL

认证

获取您的API密钥

连接管理

列出连接

创建连接

获取连接

删除连接

指定连接

API 参考

联系人

列出联系人

获取联系人

创建联系人

更新联系人

删除联系人

搜索联系人

公司

列出公司

获取公司

创建公司

更新公司

删除公司

搜索公司

交易

列出交易

获取交易

创建交易

更新交易

删除交易

关联（v4 API）

关联对象

列出关联

批量操作

批量读取

批量创建

批量更新

批量归档

属性

列出属性

搜索运算符

分页

代码示例

JavaScript

Python

注意事项

错误处理

故障排查：API密钥问题

故障排查：无效应用名称

资源文档

相关文章

推荐文章

热门浏览

标签列表