Dureach API リファレンス：認証、エンドポイント、ページネーション、webhook

こちらのページでは、顧客が安全に利用できる Dureach API を説明します。API キー、webhook と配信履歴、バージョン分離された連絡先取得エンドポイント、認証、フィールド、レスポンス、カーソルページング、フィルター、制限、本番で処理するエラーを扱います。

対応範囲から始める

Settings -> Integrations で最小権限の API キーを作成し、サーバー側で保管して Authorization ヘッダーで送信します。各リクエストを対象 workspace に限定してください。ブラウザアプリ、private runner、未文書化の /api/v1/ と /api/v2/ は自動的に顧客 API にはなりません。

例は https://app.dureach.com を使います。YOUR_OAUTH_ACCESS_TOKEN と UUID を置き換え、実キーをブラウザ、URL、スクリーンショット、ログ、サポートチケットに入れないでください。

ガイド

認証

すべてのリクエストでキーを bearer token として送信します。

curl --fail-with-body \
  'https://app.dureach.com/api/v2/webhooks?limit=25' \
  -H 'Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN' \
  -H 'Accept: application/json'

キーは作成したアクティブな workspace に属し、workspace の境界を越えられません。401 が返った場合、漏えいの可能性があればキーを失効させ、交換用キーを作成してサーバー側のシークレットを更新します。

API キーエンドポイント

すべての API キーエンドポイントは /oauth/service-accounts にあり、対応する OAuth business scopes スコープ（または all:*）が必要です。

`POST /oauth/service-accounts`

キーを作成します。リクエストには空でない name（最大 255 文字）と空でない scopes 配列が必要です。スコープ名は有効で重複できません。完全な key 値はこのレスポンスでのみ返されます。

{
  "name": "Reporting integration",
  "scopes": ["campaigns:read", "campaigns:create"]
}

{
  "id": "0199f372-efec-7c2d-af53-85ab8eab7c73",
  "name": "Reporting integration",
  "scopes": ["campaigns:read", "campaigns:create"],
  "key": "dureach_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "workspace_id": "0199f372-efef-73e5-b1ed-e2d1fbe4654d",
  "timestamp_created": "2025-10-17T18:33:40.079Z",
  "timestamp_updated": "2025-10-17T18:33:40.079Z"
}

`GET /oauth/service-accounts`

アクティブな workspace のキーを一覧表示します。クエリパラメーター：

パラメーター	必須	詳細
`limit`	いいえ	レコード数。デフォルト 25。正の整数を使い、サーバーがページサイズを制限します。
`starting_after`	いいえ	前ページの最後のキーの UUID。`next_starting_after` を変更せず送ります。

レスポンスには items と、次のページがあれば next_starting_after が含まれます。後続の読み取りで返るのは安全なキー接頭辞だけで、元のシークレットではありません。

`DELETE /oauth/service-accounts/{id}`

キーを失効させます。レスポンスには削除したキーのメタデータと安全な接頭辞が含まれます。成功した削除は恒久的なものとして扱い、シークレットマネージャーからキーを削除します。

Webhook エンドポイント

Webhook エンドポイントは /api/v2 にあり、webhooks:*（または all:*）と webhook を含むプランが必要です。

`GET /api/v2/webhooks`

Webhook の宛先を一覧表示します。対応するフィルターは campaign（キャンペーン UUID）と event_type です。カーソルページングには limit と starting_after を使います。ページサイズは 1〜100、デフォルトは 25 です。レスポンス：

{
  "items": [
    {
      "id": "0199f372-efec-7c2d-af53-85ab8eab7c73",
      "campaign": "0199f372-efef-73e5-b1ed-e2d1fbe4654d",
      "name": "Interested lead receiver",
      "target_hook_url": "https://example.com/dureach-hook",
      "event_type": "lead.interested",
      "custom_interest_value": null,
      "timestamp_created": "2025-10-17T18:33:40.079Z"
    }
  ],
  "next_starting_after": "0199f372-efec-7c2d-af53-85ab8eab7c73"
}

`POST /api/v2/webhooks`

宛先を作成します。target_hook_url、name、event_type を送り、イベントがカスタム関心ラベルの場合は custom_interest_value も送ります。workspace レベルのイベントでは campaign は任意です。

`GET /api/v2/webhooks/{id}`, `PATCH /api/v2/webhooks/{id}`, `DELETE /api/v2/webhooks/{id}`

宛先を読み取り、更新、削除します。PATCH は作成時と同じフィールドを受け取り、送信されたフィールドだけを変更します。更新後に宛先を確認してください。削除しても過去の配信イベントは削除されません。

`GET /api/v2/webhooks/event-types`

標準イベントと、アクティブな workspace で利用できるカスタムリードラベルイベントを返します。返された id を event_type として使い、後で名前が変わる可能性のあるラベルをハードコードしないでください。

`POST /api/v2/webhooks/{id}/test`

テスト配信を送ります。成功レスポンスには success: true、status_code: 200、response_time_ms、error: null が含まれます。まず非本番の受信先でテストしてください。

`GET /api/v2/webhook-events`

配信試行を一覧表示します。success=true|false または webhook_url で絞り込みます。limit（1〜100、デフォルト 25）と starting_after を使います。イベントには payload、status_code、success、retry_count、will_retry、timestamp_next_retry、error_message、retry_successful、lead_email、response_time_ms が含まれます。アプリケーションログに書く前に payload と lead_email をマスキングしてください。

`GET /api/v2/webhook-events/{id}`

UUID で 1 件の配信試行を読み取ります。

`GET /api/v2/webhook-events/summary` と `GET /api/v2/webhook-events/summary-by-date`

配信の集計状態を返します。概要には total_events、successful_events、failed_events、success_rate、failure_rate が含まれます。日付概要は日ごとに 1 件のレコードを持つ items 配列を返します。監視に使い、イベントの再生には使わないでください。

連絡先取得エンドポイント

連絡先取得サービスは現在、個別に計測されるレガシーエンドポイントを /api/v1/leadbank に公開しています。利用可否は workspace の権限によります。

メソッド	パス	目的
`POST`	`/api/v1/leadbank/find`	対応する検索 payload で連絡先を検索します。
`POST`	`/api/v1/leadbank/acquire_email`	適格な連絡先の勤務先メール開示を要求します。
`GET`	`/api/v1/leadbank/balance/get`	現在の取得残高を読み取ります。
`GET`	`/api/v1/leadbank/acquire-lists`	取得リストを一覧表示します。
`GET`	`/api/v1/leadbank/acquire-lists/{list_id}/leads`	取得リスト内のリードを一覧表示します。
`GET`	`/leadbank/api/v1/company/{company_id}`	取得した会社レコードを読み取ります。

検索とリストのレスポンスは大きくなる場合があります。文書化されたページまたは limit パラメーターを必ず送り、次のページが示されなくなったら停止します。空の結果はそのクエリに一致がないことを意味するだけで、人や会社が存在しない証明ではありません。

リクエストの衛生管理

文書化されたメソッドとパスを使い、送信前にフィールドを検証し、カーソルまたはページ上限に従います。401、403、検証、レート、サーバーエラーを分けて処理してください。webhook コンシューマーを冪等にし、確認前にイベント ID を保存し、一時的な失敗後は安全に再試行します。

エラー

API キー管理は statusCode、error、message を含む JSON を返します。新しいエンドポイントには機械可読の code も含まれる場合があります。400 は無効な入力、401 は認証の欠落・無効・失効、403 はスコープ、ロール、workspace、プランの失敗、404 は不明なリソース、409 は状態の競合、429 はレートまたは使用量上限として扱います。一時的な 5xx の後だけ、範囲を制限した冪等なリクエストを再試行し、4xx を無条件に再試行しないでください。

トラブルシューティングチェックリスト

ベース URL https://app.dureach.com と正しいパスバージョンを確認します。
Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN を送り、query string のキーは使いません。
キーのスコープとアクティブな workspace を確認し、プランにエンドポイントが含まれることを確認します。
UUID、必須フィールド、limit の範囲、starting_after カーソルを検証します。
サポート用に、状態、マスキングした message または code、リクエスト時刻、エンドポイントを記録します。
キーが公開されたら失効させて交換します。キーや未加工の webhook payload を送らないでください。

エンドポイントのワークフロー

Settings → Integrations で API キーを作成し、最小限のスコープを選びます。
Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN と Accept: application/json を付けた読み取り専用リクエストを送ります。
インテグレーションを作る前にレスポンス形式を検証し、items、UUID、enum、next_starting_after を保持します。
返されたカーソルをそのまま使い、カーソルがなくなったら停止します。
確認前にイベント ID を保存して、webhook コンシューマーを冪等にします。

リクエストフィールドのルール

正の範囲内の limit、有効な UUID、文書化されたイベントタイプ、必須の JSON フィールドを使います。キーを query string、ブラウザバンドル、スクリーンショット、ログに入れないでください。

キャンペーンとリードの API

以下は、workspace に紐づく OAuth service account で利用できるキャンペーンとリードの操作です。Settings -> Integrations で key を作成し、一度だけ表示される値を保存してサーバー側で管理してください。Workspace のプランには API アクセスが必要です。以下のリクエストには https://api.dureach.com を使用します。

メソッド	パス	必要な権限	用途
`GET`	`/api/v2/campaigns`	`campaigns:read`	キャンペーン一覧
`POST`	`/api/v2/campaigns`	`campaigns:create`	キャンペーン作成
`GET`	`/api/v2/campaigns/{id}`	`campaigns:read`	キャンペーン取得
`PATCH`	`/api/v2/campaigns/{id}`	`campaigns:update`	キャンペーン更新
`POST`	`/api/v2/lead/add`	`leads:create`	リード追加
`GET`	`/api/v2/lead/get`	`leads:read`	メールでリード検索
`POST`	`/api/v2/lead/update/status`	`leads:update`	リードのステータス更新

まず読み取り専用のリクエストを送ります。

curl --fail-with-body 'https://api.dureach.com/api/v2/campaigns?limit=10' \
  -H 'Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN' \
  -H 'Accept: application/json'

一覧は items を返し、次のページがある場合は next_starting_after を含みます。次のリクエストではカーソルをそのまま渡してください。limit の上限は 100 です。詳細と更新にはレスポンス内の UUID を使います。

リードを追加するには、次の JSON を POST /api/v2/lead/add に送ります。

{
  "campaign_id": "CAMPAIGN_UUID",
  "leads": [{"email": "[email protected]", "first_name": "Jane"}]
}

GET /api/v2/lead/get?email=jane%40example.com&campaign_id=CAMPAIGN_UUID でリードを検索できます。ステータスの変更には、campaign_id、email、new_status を POST /api/v2/lead/update/status に送ります。キャンペーンの作成と更新は JSON を使います。日程とシーケンスの必須項目は OpenAPI schema を参照してください。

Key は作成元の workspace に固定されます。異なる X-Workspace-ID は拒否されます。Key の欠落や無効は 401、権限不足や workspace の不一致は 403 です。検証エラーとレート制限は別に処理してください。Key を URL、ブラウザー bundle、スクリーンショット、ログに入れないでください。

OpenAPI 仕様に、これら 7 操作のリクエスト項目、レスポンス、bearer 認証を記載しています。

対応範囲から始める

ガイド

認証

API キーエンドポイント

POST /oauth/service-accounts

GET /oauth/service-accounts

DELETE /oauth/service-accounts/{id}

Webhook エンドポイント

GET /api/v2/webhooks

POST /api/v2/webhooks

GET /api/v2/webhooks/{id}, PATCH /api/v2/webhooks/{id}, DELETE /api/v2/webhooks/{id}

GET /api/v2/webhooks/event-types

POST /api/v2/webhooks/{id}/test

GET /api/v2/webhook-events

GET /api/v2/webhook-events/{id}

GET /api/v2/webhook-events/summary と GET /api/v2/webhook-events/summary-by-date