API リファレンス：リード

リード（leads）の操作です。共通の決まり（認証・レート制限・エラーの形）は概要を、型の詳細はスキーマを参照してください。

AI・コーディングエージェント向けにこのページの Markdown 版とllms.txtがあります。

GET /api/v1/leads

リードの一覧

operationId：listLeads　必要なスコープ：leads:read

パラメータ

名前場所型必須説明
site_idクエリstring（uuid）（null 可）——
campaign_idクエリstring（uuid）（null 可）——
statusクエリstring（null 可）—値：started・captured・abandoned・queued・sent・converted・suppressed（今後増えることがある）
date_fieldクエリstring（null 可）—値：created_at・captured_at・abandoned_at・converted_at（今後増えることがある）
fromクエリstring（null 可）——
toクエリstring（null 可）——
limitクエリinteger—1〜200・既定値 50
cursorクエリstring（null 可）——

応答

ステータス説明型
200成功LeadListOut
401APIキーが無効・失効（authentication_error）Error
403スコープ不足（permission_error / scope_insufficient）・プランの上限（plan_limit_exceeded）・APIキーではできない操作（session_required 等）Error
422パラメータ不正（invalid_request）。param に対象の項目名、message に理由（日本語）Error
429レート制限の超過（rate_limit_error）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ X-RateLimit-Limit の値が正。Retry-After（秒）の後に再試行するError
5XXサーバ側の失敗（api_error）。request_id を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ Idempotency-Key を付けて再試行する）Error

GET /api/v1/leads/{lead_id}

リードの取得（流入元・時系列つき）

operationId：getLead　必要なスコープ：leads:read

1件の詳細。通常の閲覧スコープ＝連絡先はマスクのまま返す。

パラメータ

名前場所型必須説明
lead_idパスstring（uuid）必須—

応答

ステータス説明型
200成功LeadDetailOut
401APIキーが無効・失効（authentication_error）Error
403スコープ不足（permission_error / scope_insufficient）・プランの上限（plan_limit_exceeded）・APIキーではできない操作（session_required 等）Error
404対象が見つからない（not_found）。他のテナントの ID を指した時も同じ 404Error
422パラメータ不正（invalid_request）。param に対象の項目名、message に理由（日本語）Error
429レート制限の超過（rate_limit_error）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ X-RateLimit-Limit の値が正。Retry-After（秒）の後に再試行するError
5XXサーバ側の失敗（api_error）。request_id を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ Idempotency-Key を付けて再試行する）Error