Keap技能使用说明

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

电脑广告

手机广告

Keap

通过托管的OAuth认证访问Keap API。为CRM和营销自动化管理联系人、公司、标签、任务、订单、商机、营销活动等。

快速开始

# List contacts
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/keap/crm/rest/v2/contacts?page_size=10')
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/keap/crm/rest/{api-path}

网关代理请求至api.infusionsoft.com/crm/rest并自动注入您的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密钥

连接管理在以下地址管理您的Keap OAuth连接：.

列出连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=keap&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': 'keap'}).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": "d5242090-02ae-4195-83e3-8deca823eb9a",
    "status": "ACTIVE",
    "creation_time": "2026-02-08T01:34:44.738374Z",
    "last_updated_time": "2026-02-08T01:35:20.106942Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "keap",
    "metadata": {}
  }
}

在浏览器中打开返回的URL以完成 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

指定连接

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

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/keap/crm/rest/v2/contacts')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', 'd5242090-02ae-4195-83e3-8deca823eb9a')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

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

API 参考

用户信息

获取当前用户

GET /keap/crm/rest/v2/oauth/connect/userinfo

响应：

{
  "email": "user@example.com",
  "sub": "1",
  "id": "4236128",
  "keap_id": "user@example.com",
  "family_name": "Doe",
  "given_name": "John",
  "is_admin": true
}

联系人操作

列出联系人

GET /keap/crm/rest/v2/contacts

查询参数：

page_size- 每页结果数量（默认 50，最大 1000）
页面令牌- 下一页令牌
筛选条件- 筛选表达式
排序依据- 排序顺序
字段- 响应中包含的字段

响应：

{
  "contacts": [
    {
      "id": "9",
      "family_name": "Park",
      "given_name": "John"
    }
  ],
  "next_page_token": ""
}

获取联系人

GET /keap/crm/rest/v2/contacts/{contact_id}

创建联系人

POST /keap/crm/rest/v2/contacts
Content-Type: application/json

{
  "given_name": "John",
  "family_name": "Doe",
  "email_addresses": [
    {"email": "john@example.com", "field": "EMAIL1"}
  ],
  "phone_numbers": [
    {"number": "555-1234", "field": "PHONE1"}
  ]
}

响应：

{
  "id": "13",
  "family_name": "Doe",
  "given_name": "John"
}

更新联系人

PATCH /keap/crm/rest/v2/contacts/{contact_id}
Content-Type: application/json

{
  "given_name": "Jane"
}

删除联系人

DELETE /keap/crm/rest/v2/contacts/{contact_id}

成功时返回204状态码。

获取联系人备注

GET /keap/crm/rest/v2/contacts/{contact_id}/notes

创建联系人备注

POST /keap/crm/rest/v2/contacts/{contact_id}/notes
Content-Type: application/json

{
  "body": "Note content here",
  "title": "Note Title"
}

公司操作

列出公司

GET /keap/crm/rest/v2/companies

获取公司

GET /keap/crm/rest/v2/companies/{company_id}

创建公司

POST /keap/crm/rest/v2/companies
Content-Type: application/json

{
  "company_name": "Acme Corp",
  "phone_number": {"number": "555-1234", "type": "MAIN"},
  "website": "https://acme.com"
}

更新公司

PATCH /keap/crm/rest/v2/companies/{company_id}
Content-Type: application/json

{
  "company_name": "Acme Corporation"
}

删除公司

DELETE /keap/crm/rest/v2/companies/{company_id}

标签操作

列出标签

GET /keap/crm/rest/v2/tags

获取标签

{
  "tags": [
    {
      "id": "91",
      "name": "Nurture Subscriber",
      "description": "",
      "category": {"id": "10"},
      "create_time": "2017-04-24T17:26:26Z",
      "update_time": "2017-04-24T17:26:26Z"
    }
  ],
  "next_page_token": ""
}

创建标签

GET /keap/crm/rest/v2/tags/{tag_id}

更新标签

POST /keap/crm/rest/v2/tags
Content-Type: application/json

{
  "name": "VIP Customer",
  "description": "High value customers"
}

删除标签

PATCH /keap/crm/rest/v2/tags/{tag_id}
Content-Type: application/json

{
  "name": "Premium Customer"
}

列出带标签的联系人

DELETE /keap/crm/rest/v2/tags/{tag_id}

为联系人应用标签

GET /keap/crm/rest/v2/tags/{tag_id}/contacts

从联系人移除标签

POST /keap/crm/rest/v2/tags/{tag_id}/contacts:applyTags
Content-Type: application/json

{
  "contact_ids": ["1", "2", "3"]
}

标签类别操作

POST /keap/crm/rest/v2/tags/{tag_id}/contacts:removeTags
Content-Type: application/json

{
  "contact_ids": ["1", "2", "3"]
}

列出标签类别

创建标签类别

GET /keap/crm/rest/v2/tags/categories

任务操作

POST /keap/crm/rest/v2/tags/categories
Content-Type: application/json

{
  "name": "Customer Segments"
}

列出任务

获取任务

GET /keap/crm/rest/v2/tasks

创建任务

GET /keap/crm/rest/v2/tasks/{task_id}

更新任务

POST /keap/crm/rest/v2/tasks
Content-Type: application/json

{
  "title": "Follow up call",
  "description": "Call to discuss proposal",
  "due_date": "2026-02-15T10:00:00Z",
  "contact": {"id": "9"}
}

删除任务

PATCH /keap/crm/rest/v2/tasks/{task_id}
Content-Type: application/json

{
  "completed": true
}

商机操作

DELETE /keap/crm/rest/v2/tasks/{task_id}

列出商机

获取商机

GET /keap/crm/rest/v2/opportunities

创建商机

GET /keap/crm/rest/v2/opportunities/{opportunity_id}

更新商机

POST /keap/crm/rest/v2/opportunities
Content-Type: application/json

{
  "opportunity_title": "New Deal",
  "contact": {"id": "9"},
  "stage": {"id": "1"},
  "estimated_close_date": "2026-03-01"
}

删除商机

PATCH /keap/crm/rest/v2/opportunities/{opportunity_id}
Content-Type: application/json

{
  "stage": {"id": "2"}
}

列出商机阶段

DELETE /keap/crm/rest/v2/opportunities/{opportunity_id}

订单操作

GET /keap/crm/rest/v2/opportunities/stages

Order Operations

列出订单

GET /keap/crm/rest/v2/orders

获取订单

GET /keap/crm/rest/v2/orders/{order_id}

创建订单

POST /keap/crm/rest/v2/orders
Content-Type: application/json

{
  "contact": {"id": "9"},
  "order_date": "2026-02-08",
  "order_title": "Product Order"
}

添加订单项

POST /keap/crm/rest/v2/orders/{order_id}/items
Content-Type: application/json

{
  "product": {"id": "1"},
  "quantity": 2
}

产品操作

列出产品

GET /keap/crm/rest/v2/products

获取产品

GET /keap/crm/rest/v2/products/{product_id}

创建产品

POST /keap/crm/rest/v2/products
Content-Type: application/json

{
  "product_name": "Consulting Package",
  "product_price": 500.00,
  "product_short_description": "1 hour consulting"
}

营销活动操作

列出营销活动

GET /keap/crm/rest/v2/campaigns

获取营销活动

GET /keap/crm/rest/v2/campaigns/{campaign_id}

列出营销序列

GET /keap/crm/rest/v2/campaigns/{campaign_id}/sequences

向序列添加联系人

POST /keap/crm/rest/v2/campaigns/{campaign_id}/sequences/{sequence_id}:addContacts
Content-Type: application/json

{
  "contact_ids": ["1", "2"]
}

从序列移除联系人

POST /keap/crm/rest/v2/campaigns/{campaign_id}/sequences/{sequence_id}:removeContacts
Content-Type: application/json

{
  "contact_ids": ["1", "2"]
}

邮件操作

列出邮件

GET /keap/crm/rest/v2/emails

获取邮件

GET /keap/crm/rest/v2/emails/{email_id}

发送邮件

POST /keap/crm/rest/v2/emails:send
Content-Type: application/json

{
  "contacts": [{"id": "9"}],
  "subject": "Hello",
  "html_content": "<p>Email body</p>"
}

用户操作

列出用户

GET /keap/crm/rest/v2/users

获取用户

GET /keap/crm/rest/v2/users/{user_id}

订阅操作

列出订阅

GET /keap/crm/rest/v2/subscriptions

获取订阅

GET /keap/crm/rest/v2/subscriptions/{subscription_id}

联盟操作

列出联盟会员

GET /keap/crm/rest/v2/affiliates

获取联盟会员

GET /keap/crm/rest/v2/affiliates/{affiliate_id}

自动化操作

列出自动化流程

GET /keap/crm/rest/v2/automations

获取自动化流程

GET /keap/crm/rest/v2/automations/{automation_id}

分页

Keap使用基于令牌的分页：

GET /keap/crm/rest/v2/contacts?page_size=50

响应：

{
  "contacts": [...],
  "next_page_token": "abc123"
}

对于后续页面，请使用page_token参数：

GET /keap/crm/rest/v2/contacts?page_size=50&page_token=abc123

当next_page_token为空时，表示没有更多页面。

过滤

使用filter参数来过滤结果：

GET /keap/crm/rest/v2/contacts?filter=given_name==John
GET /keap/crm/rest/v2/contacts?filter=email_addresses.email==john@example.com
GET /keap/crm/rest/v2/tasks?filter=completed==false

代码示例

JavaScript

const response = await fetch(
  'https://gateway.maton.ai/keap/crm/rest/v2/contacts?page_size=10',
  {
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    }
  }
);
const data = await response.json();

Python

import os
import requests

response = requests.get(
    'https://gateway.maton.ai/keap/crm/rest/v2/contacts',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
    params={'page_size': 10}
)
data = response.json()

注意事项

所有API路径必须包含/crm/rest前缀（例如，/keap/crm/rest/v2/contacts)
Keap 使用 v2 版本的 REST API（之前的 v1 API 已弃用）
时间戳采用 ISO 8601 格式
ID 以字符串形式返回
分页使用page_size和page_token（而非基于偏移量）
最大page_size为 1000
重要提示：当将 curl 输出通过管道传递给jq或其他命令时，在某些 shell 环境中，像$MATON_API_KEY这样的环境变量可能无法正确展开

错误处理

状态码	含义
400	缺少 Keap 连接或请求无效
401	Maton API密钥无效或缺失
403	未授权（请检查OAuth权限范围）
404	资源未找到
429	请求频率受限
4xx/5xx	来自Keap 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路径以keap开头。例如：

正确示例：https://gateway.maton.ai/keap/crm/rest/v2/contacts
错误示例：https://gateway.maton.ai/crm/rest/v2/contacts

资源

免责申明

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

打赏

文章底部电脑广告

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

标签

上一篇：Master Marketing技能使用说明下一篇：Quick Reminders技能使用说明