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 文字の形式です。1 回だけ表示され、フィンガープリントとしてのみ保存され、リクエストのたびに検証され、いつでも無効にできます（Revoke key）。1 つのサイト環境で有効にできるキーは最大 20 件です。キーの作成時に、スマートフォンでの 2 回目の確認が必要になる場合があります。

ベース 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 を確認してください。

リードを 1 件取得する

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 のタイムスタンプ

リードのステータスを変更する

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`	1 分あたり 300 リクエストを超過。待ってから再試行してください

レート制限は Atlas API サーバーごとに適用されるため、1 分あたり 300 リクエストは保証値ではなく上限と考えてください。