# API リファレンス：リード

> https://okaeri.tech/developers/reference/leads/ の Markdown 版。

リード（`leads`）の操作です。共通の決まり（認証・レート制限・エラーの形）は[概要](https://okaeri.tech/developers/index.md)を、型の詳細は[スキーマ](https://okaeri.tech/developers/reference/schemas.md)を参照してください。

- [GET /api/v1/leads](https://okaeri.tech/developers/reference/leads.md#listLeads)　リードの一覧（`listLeads`）
- [GET /api/v1/leads/{lead_id}](https://okaeri.tech/developers/reference/leads.md#getLead)　リードの取得（流入元・時系列つき）（`getLead`）

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

## GET /api/v1/leads/{lead_id}

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

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

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

### パラメータ

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

### 応答

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