Leads API
通过限定范围的 API 密钥，从您自己的系统读取线索并更新其状态。
本页面由英文翻译而来。如有任何差异，以英文版本为准。 阅读英文版
Leads API 让您的 CRM、数据仓库或自动化工具读取您的线索并更新其状态。
在 Studio 的 Integrations → Leads API → New key 下创建密钥。每个密钥包含：
- 名称；
- 授权：
leads:read（Read leads），以及可选的leads:write-status（Change lead status）； - 30、90、180 天或 1 年的有效期。
密钥形如 atl_lead_ 后跟 43 个字符。它们只显示一次，仅以指纹形式存储，每次请求都会被检查，并且可以随时撤销（Revoke key）。每个站点环境最多可有 20 个有效密钥。创建密钥时可能需要在手机上进行二次确认。
基础 URL 和身份验证
Section titled “基础 URL 和身份验证”https://<delivery host>/v1/leads-api/environments/{environmentId}Authorization: Bearer atl_lead_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX响应带有 Cache-Control: private, no-store。错误使用 RFC 9457 的 application/problem+json 格式。
GET /leads?since=2026-10-01T00:00:00Z&limit=50&cursor=…
| 参数 | 说明 |
|---|---|
since |
仅返回在此时间或之后更新的线索。带时区的 ISO 8601 |
limit |
1 到 200，默认 50 |
cursor |
上一次响应中的 nextCursor |
线索按最早变更优先的顺序返回。响应为 { "leads": [ … ], "nextCursor": "…" | null }。持续翻页直到 nextCursor 为 null，并保存最后一个 updatedAt，以便下次只获取有变化的线索。
列表包含已合并、已匿名化和测试线索。请检查 mergedInto、anonymisedAt 和 isTest。
获取单条线索
Section titled “获取单条线索”GET /leads/{leadId}
| 字段 | 说明 |
|---|---|
id, source |
source 是线索来自的表单或聊天机器人 |
form |
{ key, name }，聊天机器人线索则为 null |
name, email, phone, company, message |
保留规则清除个人数据后为空 |
details |
任何其他答案 |
status |
new、contacted、qualified、won、lost 或 spam |
isTest |
Studio 测试提交 |
version |
更改状态时需要回传 |
mergedInto, anonymisedAt |
线索被合并或匿名化时设置 |
createdAt, updatedAt |
ISO 8601 时间戳 |
更改线索状态
Section titled “更改线索状态”PATCH /leads/{leadId}/status，请求体为 { "status": "qualified", "expectedVersion": 4 }。需要 Change lead status 授权。该更改在线索的历史记录中显示为由该密钥所做。
| 状态 | 代码 | 含义 |
|---|---|---|
| 401 | CP_UNAUTHENTICATED |
密钥缺失、错误、已过期或已撤销 |
| 403 | CP_FORBIDDEN |
该密钥缺少此请求所需的授权 |
| 404 | CP_NOT_FOUND |
此环境中没有这条线索 |
| 409 | CP_VERSION_CONFLICT |
线索在您读取之后已发生变化。请重新读取 |
| 422 | REQUEST_SCHEMA_INVALID |
请求体或某个参数无效 |
| 422 | CURSOR_INVALID |
无法读取该游标 |
| 429 | RATE_LIMITED |
每分钟超过 300 次请求。请等待后重试 |
速率限制按每台 Atlas API 服务器分别应用，因此请把每分钟 300 次请求视为上限，而非保证值。