ClawSkills logoClawSkills

Keap

Keap API 集成，包含托管式 OAuth。管理联系人、公司、标签、任务、订单、商机以及 CRM 和营销自动化活动的营销活动。 请

访问网站

介绍

# Keap

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

## 快速开始

```bash # 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 ```

## Base 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`：

```bash export MATON_API_KEY="YOUR_API_KEY" ```

### 获取 API 密钥

1. 登录或在 [maton.ai](https://maton.ai) 创建账户 2. 前往 [maton.ai/settings](https://maton.ai/settings) 3. 复制您的 API 密钥

## 连接管理

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

### 列出连接

```bash 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 ```

### 创建连接

```bash 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 ```

### 获取连接

```bash 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 ```

**响应：** ```json { "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 授权。

### 删除连接

```bash 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` 头指定要使用的连接：

```bash 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 参考

### 用户信息

#### 获取当前用户

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

**响应：** ```json { "email": "[email protected]", "sub": "1", "id": "4236128", "keap_id": "[email protected]", "family_name": "Doe", "given_name": "John", "is_admin": true } ```

### 联系人操作

#### 列出联系人

```bash GET /keap/crm/rest/v2/contacts ```

查询参数： - `page_size` - 每页结果数（默认 50，最大 1000） - `page_token` - 下一页的令牌 - `filter` - 过滤表达式 - `order_by` - 排序顺序 - `fields` - 响应中包含的字段

**响应：** ```json { "contacts": [ { "id": "9", "family_name": "Park", "given_name": "John" } ], "next_page_token": "" } ```

#### 获取联系人

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

#### 创建联系人

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

{ "given_name": "John", "family_name": "Doe", "email_addresses": [ {"email": "[email protected]", "field": "EMAIL1"} ], "phone_numbers": [ {"number": "555-1234", "field": "PHONE1"} ] } ```

**响应：** ```json { "id": "13", "family_name": "Doe", "given_name": "John" } ```

#### 更新联系人

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

{ "given_name": "Jane" } ```

#### 删除联系人

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

成功时返回 204。

#### 获取联系人备注

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

#### 创建联系人备注

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

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

### 公司操作

#### 列出公司

```bash GET /keap/crm/rest/v2/companies ```

#### 获取公司

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

#### 创建公司

```bash 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" } ```

#### 更新公司

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

{ "company_name": "Acme Corporation" } ```

#### 删除公司

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

### 标签操作

#### 列出标签

```bash GET /keap/crm/rest/v2/tags ```

**响应：** ```json { "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": "" } ```

#### 获取标签

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

#### 创建标签

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

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

#### 更新标签

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

{ "name": "Premium Customer" } ```

#### 删除标签

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

#### 列出带有标签的联系人

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

#### 将标签应用到联系人

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

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

#### 从联系人移除标签

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

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

### 标签类别操作

#### 列出标签类别

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

#### 创建标签类别

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

{ "name": "Customer Segments" } ```

### 任务操作

#### 列出任务

```bash GET /keap/crm/rest/v2/tasks ```

#### 获取任务

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

#### 创建任务

```bash 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"} } ```

#### 更新任务

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

{ "completed": true } ```

#### 删除任务

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

### 商机操作

#### 列出商机

```bash GET /keap/crm/rest/v2/opportunities ```

#### 获取商机

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

#### 创建商机

```bash 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" } ```

#### 更新商机

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

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

#### 删除商机

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

#### 列出商机阶段

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

### 订单操作

#### 列出订单

```bash GET /keap/crm/rest/v2/orders ```

#### 获取订单

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

#### 创建订单

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

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

#### 添加订单项

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

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

### 产品操作

#### 列出产品

```bash GET /keap/crm/rest/v2/products ```

#### 获取产品

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

#### 创建产品

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

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

### 营销活动操作

#### 列出营销活动

```bash GET /keap/crm/rest/v2/campaigns ```

#### 获取营销活动

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

#### 列出营销活动序列

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

#### 将联系人添加到序列

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

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

#### 从序列中移除联系人

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

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

### 邮件操作

#### 列出邮件

```bash GET /keap/crm/rest/v2/emails ```

#### 获取邮件

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

#### 发送邮件

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

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

### 用户操作

#### 列出用户

```bash GET /keap/crm/rest/v2/users ```

#### 获取用户

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

### 订阅操作

#### 列出订阅

```bash GET /keap/crm/rest/v2/subscriptions ```

#### 获取订阅

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

### 联盟操作

#### 列出联盟成员

```bash GET /keap/crm/rest/v2/affiliates ```

#### 获取联盟成员

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

### 自动化操作

#### 列出自动化

```bash GET /keap/crm/rest/v2/automations ```

#### 获取自动化

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

## 分页

Keap 使用基于令牌的分页：

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

**响应：** ```json { "contacts": [...], "next_page_token": "abc123" } ```

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

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

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

## 过滤

使用 `filter` 参数过滤结果：

```bash GET /keap/crm/rest/v2/contacts?filter=given_name==John GET /keap/crm/rest/v2/[email protected] GET /keap/crm/rest/v2/tasks?filter=completed==false ```

## 代码示例

### JavaScript

```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

```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` 或其他命令时，像 `$MATON_API_KEY` 这样的环境变量在某些 shell 环境中可能无法正确展开

## 错误处理

| 状态 | 含义 | |--------|---------| | 400 | 缺少 Keap 连接或请求无效 | | 401 | Maton API 密钥无效或缺失 | | 403 | 未授权（请检查 OAuth 范围） | | 404 | 未找到资源 | | 429 | 速率受限 | | 4xx/5xx | 来自 Keap API 的透传错误 |

### 故障排除：API 密钥问题

1. 检查是否设置了 `MATON_API_KEY` 环境变量：

```bash echo $MATON_API_KEY ```

2. 通过列出连接来验证 API 密钥是否有效：

```bash 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 ```

### 故障排除：应用名称无效

1. 确保您的 URL 路径以 `keap` 开头。例如：

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

## 资源

- [Keap 开发者门户](https://developer.infusionsoft.com/) - [Keap REST API V2 文档](https://developer.infusionsoft.com/docs/restv2/) - [入门指南](https://developer.infusionsoft.com/getting-started/) - [OAuth 2.0 身份验证](https://developer.infusionsoft.com/authentication/) - [Maton 社区](https://discord.com/invite/dBfFAcefs2) - [Maton 支持](mailto:[email protected])

返回

更多产品

Agent Browser

浏览器与自动化

一款基于 Rust 的快速无头浏览器自动化 CLI，具备 Node.js 回退机制，支持 AI 智能体通过结构化命令导航网页、点击、输入和获取页面快照。

22.4K

Brave Search

浏览器与自动化

通过 Brave Search API 进行网络搜索和内容提取。用于搜索文档、事实或任何网络内容。轻量级，无需浏览器。

9K

Desktop Control

浏览器与自动化

具有鼠标、键盘和屏幕控制功能的高级桌面自动化。

6.3K