客户 API 搜索、富化与导出
使用带权限的密钥创建异步商家任务，轮询状态、分页读取结果并下载 CSV。数据接口始终需要认证。
OwnerClue · 更新于
认证和限制
在密钥设置创建密钥，明文只展示一次。位置、状态、结果、导出需要 leads:read；创建任务及操作需要 leads:write。同时读写的工作流应包含两项权限，旧密钥不会自动获得权限。
发送 Authorization: Bearer sk_YOUR_KEY。密钥保存在凭据库，不放进公开工作流和 URL。接口按账户隔离数据。生产 D1 API 每账户每分钟最多 60 请求，请求间隔至少 200 ms。搜索、campaign、富化共用最多三个活跃任务的并发预算。
创建任务使用 8–100 位字母、数字、下划线或短横线组成的 Idempotency-Key。同一请求重试复用键，新任务使用新键。HTTP 202 表示任务已创建，并不表示结果已完成。
获取真实位置代码
GET /api/v1/leads/locations?country=US&type=City&q=Phoenix，或使用 country=CA。用返回的 code 创建任务。支持 parentCode、type 等条件。位置目录返回数组，没有任务列表的分页包裹结构。以下示例中的 123456 是占位值，必须替换。
{"keyword":"plumber","locationCode":123456,"languageCode":"en","depth":20}
创建任务并轮询
向 /api/v1/leads/searches POST 上述 JSON，加认证与幂等头。成功 JSON 包含 code: 0、data.id。GET /api/v1/leads/searches/{id}，直到 data.status 为 completed。queued、running 继续轮询，failed 查看错误。未完成时不要导出。
| /api/v1/leads 下的路径 | 用途 |
|---|---|
| GET /searches、/campaigns、/enrichments | 当前账户任务列表 |
| POST /searches | keyword、locationCode、languageCode、depth，可选 exactCategory |
| POST /campaigns/preview | 预览地区代码展开结果与最大数量 |
| POST /campaigns | keyword、locations 数组、languageCode、depth、maxLeads |
| POST /enrichments | rows: [{domain,name?}] 或 csv 字符串，最多 100 行 |
| GET /…/{id} | 状态和任务信息 |
| GET /…/{id}/results?limit=100&cursor=… | 分页结果 |
| GET /…/{id}/export?format=full | 完成后的 CSV |
| POST /campaigns/{id}/pause、/resume、/stop | 多城市任务控制 |
| POST /enrichments/{id}/resume | 恢复暂停的富化任务 |
搜索深度 1–700。Campaign 深度支持 20、50、100、300、500、700，选择 1–100 个地区代码，创建前先预览实际城市。详见多城市规则。
分页、筛选和导出
任务列表和结果在 data 中返回 items、nextCursor。整个分页过程保持相同 limit，原样传回游标，nextCursor 为 null 时停止。当前分页基于偏移量，运行中数据可能移动，建议完成后读取。位置目录为数组，是例外。
地图结果与导出共用 q、email=true、owner=true、websiteStatus、signal、phoneType、includeExcluded=true。Signal 支持 no_website、website_unreachable、booking_not_found、reviews_below_20。格式支持 basic、full、gohighlevel、instantly、1cw。域名结果按输入行返回，不使用地图名单筛选参数。
错误处理
202 保存 ID 并轮询。400 检查参数、幂等键、地区、额度与并发条件；401 补认证头；403 检查密钥、权限与导出状态；404 核对任务和账户；429 延后重试；503 等待功能恢复。记录 HTTP 状态和 JSON code，CSV 响应为 text/csv。