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 格式。
列出潛在客戶
Section titled “列出潛在客戶”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 次請求視為上限，而非保證。