REST API 参考

概述

LeadHub 包含完整的 REST API，允许外部工具读取和写入您的数据——潜在客户、管道、自动化、表单等。使用它与 Zapier 集成、构建自定义仪表板、连接您的网站或自动化任何内容。

---

基础 URL

所有 API 请求发送至：

https://yourdomain.com/api/v1

将 yourdomain.com 替换为您实际的 LeadHub 域名。

---

认证

每个请求（health check 除外）都需要 API 密钥。

在管理面板的 设置 → API 密钥 中创建 API 密钥。请参阅设置页面获取说明。

在每个请求的 Authorization 标头中以 Bearer 令牌形式包含您的 API 密钥：

Authorization: Bearer lh_your_api_key_here

如果发送不带 API 密钥或使用无效密钥的请求，您将收到 401 Unauthorized 响应。

---

速率限制

每个 API 密钥默认限制为每小时 1,000 个请求（可按密钥配置）。超出此限制将收到 429 Too Many Requests 响应。

每个响应都包含以下标头，以便您跟踪使用情况：

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1711580400

X-RateLimit-Reset 是限制重置时间的 Unix 时间戳。

---

分页

返回记录列表的端点支持分页。添加以下查询参数：

参数	默认值	最大值
page	1	—
per_page	15	100

示例：GET /api/v1/leads?page=2&per_page=25

---

响应格式

成功响应

{
  "data": { ... },
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 15,
    "total": 73,
    "from": 1,
    "to": 15
  },
  "links": {
    "first": "https://yourdomain.com/api/v1/leads?page=1",
    "last": "https://yourdomain.com/api/v1/leads?page=5",
    "prev": null,
    "next": "https://yourdomain.com/api/v1/leads?page=2",
    "self": "https://yourdomain.com/api/v1/leads?page=1"
  }
}

对于单记录响应（show、create、update），data 包含记录对象，meta 被省略。

错误响应

{
  "status": "error",
  "message": "The given data was invalid.",
  "code": "VALIDATION_FAILED",
  "errors": {
    "email": ["The email field must be a valid email address."]
  }
}

常见错误代码：

代码	HTTP 状态	含义
UNAUTHORIZED	401	API 密钥缺失或无效
FORBIDDEN	403	API 密钥缺少所需权限范围
NOT_FOUND	404	记录不存在
VALIDATION_FAILED	422	请求数据验证失败
RATE_LIMITED	429	请求过多
SERVER_ERROR	500	意外的服务器错误

---

健康检查

无需认证。

GET /api/v1/health

响应：

{
  "status": "ok",
  "version": "1.0.0",
  "timestamp": "2026-03-28T09:15:00+00:00"
}

在发送其他请求之前，使用此端点检查您的 LeadHub 实例是否可访问。

---

潜在客户（Leads）

所需权限范围： read:leads（检索）、write:leads（创建/更新）、delete:leads（删除）。

列出潜在客户

GET /api/v1/leads

过滤查询参数：

参数	描述
source	按来源筛选（如 facebook、website）
status	按状态筛选（如 new、contacted、qualified）
pipeline_id	按管道 ID 筛选
stage_id	按管道阶段 ID 筛选
assigned_user_id	按分配用户 ID 筛选
tag	按标签名称筛选
search	按姓名、邮箱或电话搜索
created_after	ISO 8601 日期——仅返回此日期之后创建的潜在客户
created_before	ISO 8601 日期——仅返回此日期之前创建的潜在客户
starred	true 仅显示已星标的潜在客户
sort	排序字段：created_at、updated_at、lead_score、first_name、last_name、email
direction	asc 或 desc（默认：desc）

获取单个潜在客户

GET /api/v1/leads/{id}

创建潜在客户

POST /api/v1/leads

请求体（JSON）：

{
  "first_name": "Sarah",
  "last_name": "Johnson",
  "email": "[email protected]",
  "phone": "+14155551234",
  "source": "website",
  "status": "new",
  "pipeline_id": 1,
  "pipeline_stage_id": 2,
  "assigned_user_id": 5,
  "notes": "Interested in the enterprise plan.",
  "custom_fields": {
    "budget": "10000"
  },
  "tags": ["hot-lead", "enterprise"]
}

first_name 为必填项，其他所有字段均为可选。

更新潜在客户

PUT /api/v1/leads/{id}
PATCH /api/v1/leads/{id}

仅发送您要更新的字段，与创建时的字段相同。

删除潜在客户

DELETE /api/v1/leads/{id}

为潜在客户添加标签

POST /api/v1/leads/{id}/tags

请求体：{ "tag": "vip-client" }

从潜在客户移除标签

DELETE /api/v1/leads/{id}/tags/{tag}

---

管道（Pipelines）

所需权限范围： read:pipelines 或 write:pipelines

GET    /api/v1/pipelines
POST   /api/v1/pipelines
GET    /api/v1/pipelines/{id}
PUT    /api/v1/pipelines/{id}
PATCH  /api/v1/pipelines/{id}
DELETE /api/v1/pipelines/{id}

管道阶段

GET    /api/v1/pipelines/{pipeline_id}/stages
POST   /api/v1/pipelines/{pipeline_id}/stages
GET    /api/v1/pipelines/{pipeline_id}/stages/{stage_id}
PUT    /api/v1/pipelines/{pipeline_id}/stages/{stage_id}
PATCH  /api/v1/pipelines/{pipeline_id}/stages/{stage_id}
DELETE /api/v1/pipelines/{pipeline_id}/stages/{stage_id}

---

标签（Tags）

所需权限范围： read:tags 或 write:tags

GET    /api/v1/tags
POST   /api/v1/tags
GET    /api/v1/tags/{id}
PUT    /api/v1/tags/{id}
PATCH  /api/v1/tags/{id}
DELETE /api/v1/tags/{id}

---

用户（Users）

所需权限范围： read:users、write:users 或 delete:users

GET    /api/v1/users
POST   /api/v1/users
GET    /api/v1/users/{id}
PUT    /api/v1/users/{id}
PATCH  /api/v1/users/{id}
DELETE /api/v1/users/{id}

---

表单（Forms）

所需权限范围： read:forms、write:forms 或 delete:forms

GET    /api/v1/forms
POST   /api/v1/forms
GET    /api/v1/forms/{id}
PUT    /api/v1/forms/{id}
PATCH  /api/v1/forms/{id}
DELETE /api/v1/forms/{id}

提交表单

POST /api/v1/forms/{id}/submissions

请求体：以键值对形式提交表单字段值。

---

自动化（Automations）

所需权限范围： read:automations、write:automations 或 delete:automations

GET    /api/v1/automations
POST   /api/v1/automations
GET    /api/v1/automations/{id}
PUT    /api/v1/automations/{id}
PATCH  /api/v1/automations/{id}
DELETE /api/v1/automations/{id}

---

集成（Integrations）

所需权限范围： read:integrations 或 write:integrations

GET    /api/v1/integrations/types
GET    /api/v1/integrations
POST   /api/v1/integrations
GET    /api/v1/integrations/{id}
PUT    /api/v1/integrations/{id}
PATCH  /api/v1/integrations/{id}
DELETE /api/v1/integrations/{id}

GET /api/v1/integrations/types 返回可用集成类型列表（Facebook、Google Ads、Mailgun 等）。

---

入站潜在客户接收

用于从外部来源、webhook 或 Zapier、Make 等无代码工具创建潜在客户的简化端点。

POST /api/inbound/leads?tenant={workspace-slug}

使用 Authorization: Bearer {api_key} 进行认证，并以查询参数形式传递工作区 slug。

请求体：

{
  "email": "[email protected]",
  "first_name": "Sarah",
  "last_name": "Johnson",
  "phone": "+14155551234",
  "company": "Tech Corp",
  "source": "zapier",
  "notes": "Came from newsletter signup",
  "tags": ["newsletter"],
  "custom_fields": {
    "utm_campaign": "spring-promo"
  }
}

email 为必填项，其他所有字段均为可选。

成功响应（201）：

{
  "status": "created",
  "lead_id": 1842,
  "is_duplicate": false
}

如果潜在客户已存在（通过邮箱或电话匹配），is_duplicate 为 true，并返回现有潜在客户的 ID。

---

代码示例

cURL

curl -X GET "https://yourdomain.com/api/v1/leads?status=new&per_page=25" \
  -H "Authorization: Bearer lh_your_api_key_here" \
  -H "Accept: application/json"

curl -X POST "https://yourdomain.com/api/v1/leads" \
  -H "Authorization: Bearer lh_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Sarah","email":"[email protected]","source":"api"}'

PHP

$apiKey = 'lh_your_api_key_here';
$baseUrl = 'https://yourdomain.com/api/v1';

// List leads
$response = file_get_contents($baseUrl . '/leads', false, stream_context_create([
    'http' => [
        'header' => "Authorization: Bearer {$apiKey}\r\nAccept: application/json\r\n",
    ],
]));
$leads = json_decode($response, true);

// Create a lead
$ch = curl_init($baseUrl . '/leads');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer {$apiKey}",
    "Content-Type: application/json",
    "Accept: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'first_name' => 'Sarah',
    'email'      => '[email protected]',
    'source'     => 'api',
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

JavaScript (fetch)

const apiKey = 'lh_your_api_key_here';
const baseUrl = 'https://yourdomain.com/api/v1';

// List leads
const response = await fetch(`${baseUrl}/leads?status=new`, {
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Accept': 'application/json',
  },
});
const { data, meta } = await response.json();

// Create a lead
const createResponse = await fetch(`${baseUrl}/leads`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
    'Accept': 'application/json',
  },
  body: JSON.stringify({
    first_name: 'Sarah',
    email: '[email protected]',
    source: 'website',
  }),
});
const newLead = await createResponse.json();