イベント取り込みAPI - 非金銭アクティビティのモニタリング

取引はお金の動きです。イベントは、それ以外にプラットフォームが把握しているすべてのことです。出金に先立つログイン、2つのアカウント間でチップを動かしたハンド、2回受け取られたボーナス、1週間後に届いたチャージバックなどがこれにあたります。イベントはすべてのカテゴリで共通の1つのエンベロープを使用し、設計上冪等であり、取引をスコアリングするのと同じルールエンジンで評価されます。

イベントの取り込みはオプトインです。Transactions → Settings → Event monitoringで有効にしてください。有効にするまでは何も変わりません。既存の取引ルールは引き続き取引に対してのみ発火します。また、ルールは明示的にイベントを含めない限り取引に適用されるため、誤ってイベントルールが作成されることはありません。有効になるまでは、すべての書き込みレーン（POST /v3/events/、POST /v3/events/batch/、POST /v3/events/sdk-token/、および/v1/events/デバイスレーン）が403と{"code": "event_monitoring_disabled"}を返し、何も保存、エンリッチ、評価されることはありません。読み取りには影響しません。

エンドポイント

エンドポイント	認証	用途
`POST /v3/events/`	APIキー	バックエンドからの1件のイベント
`POST /v3/events/batch/`	APIキー	1回のリクエストで最大500件のイベント
`POST /v3/events/sdk-token/`	APIキー	スコープ付きのデバイス認証情報を発行
`POST /v1/events/`	`X-Monitoring-Token`	デバイスSDKからの1件のイベント
`POST /v1/events/batch/`	`X-Monitoring-Token`	フラッシュ済みのSDKバッファー
`GET /v3/events/`	APIキー	イベントの一覧取得とフィルタリング
`GET /v3/events/{event_uuid}/`	APIキー	ルールの根拠を含む1件のイベント
`GET /v3/events/subjects/{vendor_data}/`	APIキー	1つのサブジェクトのタイムライン（下記の`entity_type`を参照）
`GET /v3/events/enrichment-metrics/`	APIキー	IPエンリッチメントキャッシュの健全性

/v3/はサーバー向けで、取引APIの他の部分と同じx-api-key認証を使用します。/v1/events/はデバイス向けです。詳しくはSDKからのイベント送信を参照してください。

エンベロープ

curl -X POST https://verification.didit.me/v3/events/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "login-2026-08-31-000001",
    "event_category": "auth",
    "action_type": "login",
    "occurred_at": "2026-08-31T20:40:31.123Z",
    "time_zone": "UTC",
    "subject": {
      "entity_type": "individual",
      "vendor_data": "user_391"
    },
    "session": { "session_id": "web-session-abc", "sequence": 142 },
    "device_context": {
      "fingerprint": "didit-fp-v2:a8c1",
      "network_context": { "ip_address": "203.0.113.42" }
    },
    "payload": { "method": "password" }
  }'

{
  "event_uuid": "0f2b...",
  "event_id": "login-2026-08-31-000001",
  "status": "ACCEPTED",
  "score": 0,
  "rules_evaluated_count": 6,
  "rules_matched_count": 0,
  "correlation_pending": false,
  "retention_class": "standard",
  "expires_at": "2026-09-30T20:40:31.123Z",
  "idempotent_replay": false,
  "rule_matches": []
}

フィールド	必須	備考
`event_id`	はい	独自の識別子で、アプリケーションごとに一意です。冪等性キーとして使われます。
`event_category`	はい	下記の10カテゴリのいずれか。
`action_type`	はい	自由形式の文字列で、最大128文字。
`occurred_at`	はい	自社側で発生した日時。過去は7日前まで、未来は5分後まで指定できます。
`subject.vendor_data`	はい	自社のユーザーID。取引で特定されるユーザーと同じユーザーに紐付けられます。
`subject.entity_type`	いいえ	`individual`（デフォルト）または`company`。
`business.vendor_data`	いいえ	イベントが属する企業。
`session`	いいえ	`session_id`、`sequence`、`page_url`、`referrer`。
`device_context`	いいえ	`fingerprint`、`persistent_device_id`、`bot_score`、および`network_context.ip_address`。
`transaction_context`	いいえ	`amount`、`currency`、`direction`、`payment_reference_id`。
`payload`	いいえ	カテゴリ固有のドメインフィールド。最大16KB。
`custom_values`	いいえ	最大100個のスカラーキー。ルールから`custom_values.<key>`として参照できます。

カテゴリ

10種類のファーストクラスカテゴリがあり、それぞれに型付きのバリデーションと管理されたルールフィールドが用意されています。

カテゴリ	主なアクション
`auth`	`signup`、`login`、`login_failed`、`logout`、`password_forgot`、`password_reset`、`mfa_reset`、`mfa_challenge`
`session`	`session_started`、`session_ended`、`page_view`、`sdk_loaded`、`device_seen`、`bot_signal_observed`、`sdk_heartbeat`
`gameplay`	`round_started`、`round_completed`、`bet_placed`、`bet_settled`、`cashout`、`limit_change`、`p2p_settlement`
`bonus`	`bonus_claimed`、`bonus_wagered`、`bonus_released`、`promotion_viewed`
`affiliate`	`affiliate_attributed`、`referral_clicked`、`campaign_joined`、`commission_event`
`payment`	`deposit_initiated`、`deposit_completed`、`withdrawal_requested`、`withdrawal_completed`、`withdrawal_address_changed`、`payment_instrument_seen`
`dispute`	`chargeback_opened`、`chargeback_won`、`chargeback_lost`、`refund_issued`、`payment_dispute_updated`
`security`	`login_attempt`、`login_succeeded`、`login_failed`、`password_changed`、`mfa_changed`、`credential_reset`、`country_changed`、`device_changed`、`account_locked`
`responsible_gambling`	`self_exclusion_checked`、`self_exclusion_match`、`re_registration_attempt`、`limit_breach_attempt`、`registry_status_changed`
`custom`	任意に定義したアクション

authはプロダクト全般を対象とする広いカテゴリです。securityはリスク判定向けのサブセットで、アカウント乗っ取り対策のルールが参照する順序付きのライフサイクルを持ちます。

必須のペイロードキー

一部のアクションは特定のキーがないと関連付けができません。そのため、関連付けられない証跡を保存するのではなく、バリデーションでリジェクトします。

アクション	必須
`gameplay.p2p_settlement`	`game_id`、`counterparty_vendor_data`、`stake_amount`、`net_result_amount`、`role`、および`hand_id` / `round_id` / `match_id`のいずれか
`gameplay.bet_placed`、`gameplay.bet_settled`	`game_id`
`payment.deposit_*`、`payment.withdrawal_completed`、`payment.withdrawal_requested`、`payment.deposit_initiated`	`payment_reference_id`、`amount`、`currency`、`payment_method`、`status`
`payment.withdrawal_address_changed`	`withdrawal_address_hash`
`dispute.chargeback_*`	`payment_reference_id`、および`dispute_id` / `chargeback_id`のいずれか
`security.*_changed`	`changed_field`。アカウント制御または出金制御の変更では、`previous_reference_hash`または`new_reference_hash`も必要です
`session.bot_signal_observed`	`telemetry_schema_version`に加えて、`bot_score`または1つ以上のテレメトリ指標
`responsible_gambling.self_exclusion_match`	`registry_source`、`exclusion_status`、`identity_match_ref`

送信するのは参照とハッシュだけにし、生のシークレットは絶対に送信しないでください。決済手段、出金先、アカウント管理に関する変更は、送信されたハッシュ化済みの参照として保存されます。カード番号、出金先アドレスの全体、パスワードハッシュ、MFAシークレットは絶対に送信しないでください。

例: P2P精算

{
  "event_id": "p2p-hand-8842-user-391",
  "event_category": "gameplay",
  "action_type": "p2p_settlement",
  "occurred_at": "2026-08-31T12:34:17.392Z",
  "subject": { "vendor_data": "user_391" },
  "payload": {
    "game_id": "poker_holdem",
    "table_id": "table_17",
    "hand_id": "hand_8842",
    "role": "winner",
    "counterparty_vendor_data": "user_812",
    "stake_amount": "250.00",
    "net_result_amount": "240.50",
    "effective_margin": "0.038",
    "operator_ledger_ref": "ledger_998123"
  }
}

例: チャージバック

{
  "event_id": "chargeback-cb_921-opened",
  "event_category": "dispute",
  "action_type": "chargeback_opened",
  "occurred_at": "2026-08-31T09:22:05.000Z",
  "subject": { "vendor_data": "user_391" },
  "transaction_context": {
    "amount": "1000.00",
    "currency": "EUR",
    "payment_reference_id": "dep_735"
  },
  "payload": {
    "dispute_id": "disp_498",
    "chargeback_id": "cb_921",
    "reason_code": "fraudulent",
    "liability_shift": false
  }
}

紛争のライフサイクルは追記専用です。訂正は新しいdisputeイベントとして送信し、最初のイベントを編集することはありません。

冪等性

event_idはアプリケーションごとに一意であり、これが冪等性の仕組みのすべてです。

同じevent_idで同じ内容の場合は、200と"idempotent_replay": true、そして最初に保存されたイベントが返されます。何度でも再試行できます。
同じevent_idで異なる内容の場合は、409が返されます。誤ってIDを再利用しています。

バッチ

POST /v3/events/batch/は最大500件のイベントを受け付けます。バッチは設計上、部分的な成功を許容します。不正な形式のページビュー1件が、同じバッチ内のチャージバックを巻き添えにすることがあってはならないためです。

{
  "accepted_count": 2,
  "replayed_count": 0,
  "rejected_count": 1,
  "results": [
    { "index": 0, "outcome": "rejected", "errors": { "occurred_at": ["This field is required."] } },
    { "index": 1, "outcome": "accepted", "event_uuid": "…", "status": "ACCEPTED" },
    { "index": 2, "outcome": "accepted", "event_uuid": "…", "status": "IN_REVIEW" }
  ]
}

いずれかがリジェクトされた場合のレスポンスは207 Multi-Status、すべて保存された場合は201 Createdです。

ステータス

ステータス	意味
`ACCEPTED`	保存済み。ステータスを変更したルールはありません(ほとんどのイベントでは、これが通常の結果です)。
`APPROVED`	ルールが実行され、スコアがレビューのしきい値を下回りました。
`IN_REVIEW`	ルールによってスコアがレビューのしきい値を超えたか、ルールがステータスを直接設定しました。
`DECLINED`	ルールによって却下されました。

correlation_pending: trueは、複数のサブジェクトにまたがるルールがまだ実行待ちであることを示します。数分以内に解消され、イベントのステータスとスコアが更新されます。詳しくは非同期ルールを参照してください。

データ保持

イベントは取引よりもはるかに量が多いため、受信時にそれぞれ保持クラスに振り分けられます。

クラス	デフォルトのホット保持期間	対象
`low_value`	14日	ページビュー、ハートビート、デバイス検出のping、ボットのテレメトリ、プロモーション閲覧
`standard`	30日	認証、セッション、ゲームプレイ、ボーナス、アフィリエイト、カスタム
`risk_relevant`	90日	セキュリティおよび責任あるギャンブルのイベント、そしてルールに一致したすべてのイベント
`monetary_or_compliance`	取引の保持期間	決済および紛争のイベント

この表から、次の2つのルールが導かれます。

ルールに一致したイベントは証跡となるため、自動的にrisk_relevantに昇格します。
決済および紛争のイベントには取引の保持期間が適用されます。イベントの保持スケジュールでは期限切れにならず、クラスごとの上書き設定で短縮することもできません。

期限切れになる3つのクラスは、Transactions → Settings → Event monitoringでアプリケーションごとに上書きできます(それぞれ1〜730日)。

IPエンリッチメント

イベントには、取引と同じIPエンリッチメント(国、ASN、VPN/プロキシおよびデータセンターのフラグ)が付与されます。エンリッチメントはイベントごとではなく、一意のIPアドレスごとに取得されます。1つのアドレスから200件のページビューを送信するセッションでも、そのアドレスのエンリッチメントの取得は1回だけです。重要度の低いテレメトリでは、エンリッチメントの参照がさらに制限されます。他のイベントがすでにそのアドレスを解決している場合にのみエンリッチメントを参照し、独自にルックアップをトリガーすることはありません。 GET /v3/events/enrichment-metrics/がその結果を返し、コンソールではイベント一覧の上に同じ数値が表示されます。

{
  "events_ingested": 128450,
  "enrichment_lookups": 41230,
  "enrichment_cache_hits": 40118,
  "enrichment_provider_calls": 1112,
  "enrichment_skipped_low_value": 74320,
  "unique_ips_seen": 1112,
  "cache_hit_rate": 0.973,
  "unique_ip_ratio": 0.0087,
  "provider_calls_per_1k_events": 8.65,
  "period_days": 30
}

イベントの読み出し

curl "https://verification.didit.me/v3/events/?event_category=payment&event_category=dispute&matched_only=true" \
  -H "x-api-key: YOUR_API_KEY"

フィルター:event_category、action_type、status、retention_class、subject_vendor_data、business_vendor_data、session_id、device_fingerprint、ip_address、game_id、round_id、affiliate_code、payment_reference_id、counterparty_vendor_data、matched_only、occurred_from、occurred_to、search。複数の値を指定するフィルターでは、パラメーターを繰り返して指定します(?status=A&status=B)。

1つの対象者のタイムライン

curl "https://verification.didit.me/v3/events/subjects/acct_9931/?entity_type=company" \
  -H "x-api-key: YOUR_API_KEY"

vendor_dataが一意となるのは、同じエンティティタイプの中だけです。同じIDがユーザーと企業の両方を指すことがあり、Diditはそれらを2つの異なる対象者として扱います。どちらを要求するかはentity_typeで指定します。指定できる値はindividual(デフォルト)またはcompanyです。企業のIDに対してこれを省略すると、両方ではなく個人のタイムラインが返されます。一覧と同じフィルターを使用できます。 GET /v3/events/{event_uuid}/は、ペイロード、デバイスコンテキスト、IPエンリッチメント、対象者のキャッシュ済みリスクシグナル、および一致したすべてのルールとその根拠を追加で返します。根拠には、一致した各フィールドがサーバー由来、SDK由来、顧客提供のいずれであるかも含まれます。 DELETE /v3/events/{event_uuid}/delete/は、1件のイベントを削除します。削除されたイベントはどの読み出しでも返されなくなり、削除は取り消せません。

次のステップ

イベントに対するルール

イベントデータに対するベロシティ、比率、シーケンス、相関のルール。

SDKによるイベント送信

スコープ付きの認証情報を使い、デバイスから直接イベントを収集します。

はじめに

機能

リファレンス

コンソール

イベント取り込みAPI - 非金銭アクティビティのモニタリング

エンドポイント

エンベロープ

カテゴリ

必須のペイロードキー

例: P2P精算

例: チャージバック

冪等性

バッチ

ステータス

データ保持

IPエンリッチメント

イベントの読み出し

1つの対象者のタイムライン

次のステップ

イベントに対するルール

SDKによるイベント送信

​エンドポイント

​エンベロープ

​カテゴリ

​必須のペイロードキー

​例: P2P精算

​例: チャージバック

​冪等性

​バッチ

​ステータス

​データ保持

​IPエンリッチメント

​イベントの読み出し

​1つの対象者のタイムライン

​次のステップ

イベントに対するルール

SDKによるイベント送信

エンドポイント

エンベロープ

カテゴリ

必須のペイロードキー

例: P2P精算

例: チャージバック

冪等性

バッチ

ステータス

データ保持

IPエンリッチメント

イベントの読み出し

1つの対象者のタイムライン

次のステップ