didit-verification-management

Name: didit-verification-management
Author: didit-protocol

github.com/didit-protocolセキュリティ29234 回インストール2 週間前に更新

リポジトリ

didit-verification-management について

本人確認を導入し、Didit のワークフロー、セッション、ユーザー、請求などを管理するチーム向けのスキルです。アカウント設定から Webhook 管理までを扱い、個別の検証や専門機能には関連スキルを案内します。

主な機能

01アカウントとアプリの設定
02ワークフローとセッションの管理
03KYC ユーザーと KYB 企業の管理
04アンケート、リスト、一括インポート
05請求、ブランディング、Webhook

活用シーン

01Didit アカウントとアプリの作成
02検証ワークフローとセッションの設定
03KYC と KYB の記録管理
04Webhook の送信先と請求の管理

MCP 対応

MCP クライアントから Didit を利用するための `didit-mcp-server` を案内しています。

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/didit-protocol/skills --skill didit-verification-management

インストール後、Claude Code で/didit-verification-managementを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

scripts/

create_session.py

manage_workflows.py

setup_account.py

詳細

Didit アイデンティティ検証プラットフォーム

概要

Didit プラットフォームのハブスキルです。アカウントとアプリケーションのセットアップ、ワークフロー、セッション、一括インポート、アンケート、リスト、ユーザー（KYC）、企業（KYB）、請求、ブランディング、ウェブフックを扱います。

関連スキル：

ニーズ	スキル
単独のチェック（ID スキャン、ライブネス、顔照合、AML、住所証明、メール、電話、データベース検証、年齢、顔検索）	`didit-id-document-verification`、`didit-liveness-detection`、`didit-face-match`、`didit-aml-screening`、`didit-proof-of-address`、`didit-email-verification`、`didit-phone-verification`、`didit-database-validation`、`didit-biometric-age-estimation`、`didit-face-search`
エンドツーエンドの KYC オンボーディングフロー	`didit-kyc-onboarding`
トランザクションの作成、トラベルルール、ウォレットスクリーニング、トランザクションルール	`didit-transaction-monitoring`
監視用のユーザーイベント（ログイン、アカウント変更）の送信	`didit-event-monitoring`
ケース、ケースのブループリント、規制当局向けレポート	`didit-case-management`
不正ネットワーク（関連ユーザー、デバイス、書類）	`didit-fraud-networks`
不正チェック	`didit-fraud-check`
カスタム書類抽出（Document AI）	`didit-document-ai`
Web およびモバイル SDK、SDK トークン	`didit-sdk-integration`
MCP クライアントからの Didit の利用	`didit-mcp-server`

料金： セッションの料金は、そのワークフローで実行される機能の合計です。完了した機能のみが課金対象となります（ワークフローの total_price。DATABASE_VALIDATION や PHONE_VERIFICATION など、料金が変動する機能は含まれません）。各組織には、コア KYC 機能（書類のキャプチャ、パッシブライブネス、顔照合、デバイスおよび IP 分析）ごとに、毎月 500 件の無料チェックが提供されます。管理エンドポイント自体の定価は公開されていません。これらの定価は、Didit の料金が変更され、毎月 500 件の無料チェックが月額 10 ドル分の無料クレジットに変わる 2026 年 11 月 1 日まで有効です。現在の料金については、didit.me/pricing をご確認ください。

ベース URL： https://verification.didit.me/v3（x-api-key を使用するすべての機能）、https://apx.didit.me/auth/v2（アカウントのセットアップ）。 API リファレンスリンク：

アカウント設定： 登録 | メールアドレスの確認 | ログイン | 認証情報の取得 | アプリケーションの作成 | アプリケーションの更新
セッション： 作成 | 取得 | 一覧表示 | 削除 | ステータスの更新 | 再提出のプレビュー | 機能ステータスの更新 | AML ヒットステータスの更新 | データの更新 | PDF | 共有 | インポート
セッション操作： 一括削除 | 削除ジョブ | レビュー一覧 | レビューの作成
ワークフロー： 作成 | 一覧表示 | 取得 | 更新 | 削除 | 機能設定
アンケート： 作成 | 一覧表示 | 取得 | 更新 | 削除
ユーザー（KYC）： 一覧表示 | 作成 | 取得 | 更新 | ステータスの更新 | 削除 | PDF | 顔画像のアップロード
事業者（KYB）： 一覧表示 | 作成 | 取得 | 更新 | ステータスの更新 | 削除 | KYB 登記情報
AML モニタリング： ユーザーの切り替え | 事業者の切り替え | ジョブの取得
生体認証テンプレート： 概要 | 一覧表示 | 件数 | 取得 | 消去 | 一括消去
トランザクション： 一覧表示 | 作成 | 取得
請求： 残高 | チャージ
カスタマイズ： 取得 | 更新
リスト（ブロック／許可／カスタム）： 概要 | 一覧表示 | 作成 | 取得 | 更新 | 削除 | エントリー | エントリーの追加 | 顔画像のアップロード | エントリーの削除
一括インポート： 検証のインポート
Webhook の送信先： 一覧表示 | 作成 | 取得 | 更新 | 削除
ガイド： プログラムによる登録 | API キー | Webhooks | レート制限 | 検証ステータス | サンドボックステスト | MCP サーバー | API 概要

認証

エンドポイント	認証	ヘッダー
登録、メールアドレスの確認、コードの再送、ログイン	なし	（未認証）
組織とアプリケーション（`/organizations/me/...`）	Bearer	`Authorization: Bearer <access_token>`（メールアドレスの確認またはログインで取得）
`verification.didit.me/v3` 上のすべて	API キー	`x-api-key: <api_key>`

verification.didit.me へのリクエストにはすべて、x-api-key ヘッダーが必要です。Didit Business Console の Developers > API keys でアプリケーションの API キーを使用するか、アカウントとキーをプログラムで作成してください（「はじめに」を参照）。カスタムアクセス権を持つ名前付きキーには、各セクションで使用するリソース（Sessions、Decisions、Media、Users、Businesses、Transactions、Workflows、Webhooks、Application settings）に対する読み取りまたは書き込み権限が必要です。一部のワークフローまたは承認済みセッションのみに制限されたキーは、セッションエンドポイントでのみ使用できます。

API キー

トピック	動作
プライマリシークレット	すべてのアプリケーションに、フルアクセス権を持つキーが 1 つあります。編集や取り消しはできず、ローテーションのみ可能です。メールアドレスの確認レスポンスに含まれる `application.api_key` がこのキーです。
名前付きキー	サービスまたはパートナーごとに 1 つ作成できます。作成、編集、ローテーション、取り消しはコンソールでのみ行えます（API では不可）。有効期限は、なし、30 日、90 日、1 年、または指定した日付（その日の UTC 時刻で終了）から選べます。
アクセス	リソースごとに、なし、読み取り、書き込みを設定できます。読み取りは `GET`、書き込みは `POST`、`PUT`、`PATCH`、`DELETE` が対象です。リソース：Sessions（書き込みではスタンドアロンチェックとインポートも実行可能）、Decisions（書き込み：承認、却下、審査、機能、AML ヒットのステータス）、Media（読み取りのみ）、Users、Businesses、Transactions、Workflows（アンケートとリストも対象）、Webhooks、Application settings（カスタマイズ、残高、チャージ）、Analytics（読み取りのみ）。
制限	Workflows：選択したワークフローのセッションのみ表示および作成でき、それ以外は `404` を返します。承認済みセッションのみ：却下済み、審査中、未完了のセッションは非表示になります。いずれかの制限があるキーでは、ユーザー、ビジネス、取引、分析データにアクセスできず、スタンドアロンチェックも実行できません。
IP 許可リスト	最大 20 個の IPv4／IPv6 アドレスまたは CIDR 範囲を指定できます。リスト外からのリクエストには `403` を返します。
ローテーション	新しいシークレットは一度だけ表示されます。以前のシークレットは 24 時間引き続き使用できます。
出力の制限	Media の読み取り権限がない場合、判定内の画像、動画、PDF の URL はすべて `null` になり、PDF エンドポイントは `403` を返します。Sessions の書き込み権限がない場合、セッション URL と `session_token` は `null` になります。
ステータスコード	`401` はキーの有効期限切れ、`403` はキーがない、誤っている、または取り消されている場合、リソースへのアクセス権がない場合、または IP リスト外からのアクセスの場合、`404` はキーの制限対象外のセッションを示します。

はじめに（アカウントをお持ちでない場合）

Didit API キーをお持ちでない場合は、2 回の API 呼び出しで作成できます。

登録： POST https://apx.didit.me/auth/v2/programmatic/register/ に {"email": "[email protected]", "password": "MyStr0ng!Pass"} を送信します。
メールを確認し、6 文字の確認コードを取得します。
確認： POST https://apx.didit.me/auth/v2/programmatic/verify-email/ に {"email": "[email protected]", "code": "A3K9F2"} を送信します。キーはレスポンス内の application.api_key に含まれています。

クレジットを追加するには： GET /v3/billing/balance/ で残高を確認し、POST /v3/billing/top-up/ に {"amount_in_dollars": 50} を送信して Stripe のチェックアウトリンクを取得します。

4 回の呼び出しで、ゼロから検証リンクを公開：

import requests

AUTH = "https://apx.didit.me/auth/v2"
API = "https://verification.didit.me/v3"

# 1. Register: emails a 6-character code (valid 10 minutes)
requests.post(f"{AUTH}/programmatic/register/",
              json={"email": "[email protected]", "password": "MyStr0ng!Pass"}).raise_for_status()

# 2. Verify the code: the response carries the application's API key
resp = requests.post(f"{AUTH}/programmatic/verify-email/",
                     json={"email": "[email protected]", "code": "A3K9F2"})
resp.raise_for_status()
headers = {"x-api-key": resp.json()["application"]["api_key"]}

# 3. Create a KYC workflow from an ordered `features` array
wf = requests.post(f"{API}/workflows/", headers=headers, json={
    "workflow_label": "My KYC",
    "features": [
        {"feature": "OCR"},
        {"feature": "LIVENESS", "config": {"face_liveness_method": "PASSIVE"}},
        {"feature": "FACE_MATCH"},
    ],
}).json()

# 4. Create a session and send the user to its URL
session = requests.post(f"{API}/session/", headers=headers,
                        json={"workflow_id": wf["uuid"], "vendor_data": "user-123"}).json()
print("Send the user to:", session["url"])

アカウントの設定

ベース URL： https://apx.didit.me/auth/v2

手順	エンドポイント	ボディ	成功時のレスポンス
1. 登録	`POST /programmatic/register/`	`email`、`password`	`201` `{"message", "email"}`。未認証のメールアドレスを再登録すると、`200` "A new verification code has been sent to your email." が返されます。
2. メールアドレスの認証	`POST /programmatic/verify-email/`	`email`、`code`（6 文字）	`200` `{access_token, refresh_token, expires_in, organization{uuid, name}, application{uuid, name, client_id, api_key}}`
コードの再送	`POST /programmatic/resend-otp/`	`email`、`password`	`200`。認証情報が誤っている場合、またはメールアドレスがすでに認証済みの場合は `400`。
3. ログイン	`POST /programmatic/login/`	`email`、`password`	`200` `{access_token, refresh_token, expires_in, message}`
4. 組織の一覧表示	`GET /organizations/me/`（Bearer）	-	ページ分割された `200` `{count, next, previous, results[]}`。各結果には `uuid`、`name`、`contact_email`、`created_at` が含まれます。
5. アプリケーションの一覧表示	`GET /organizations/me/{org_id}/applications/`（Bearer）	-	アプリケーションレコードのページ分割された `200` 一覧
アプリケーションの作成	`POST /organizations/me/{org_id}/applications/`（Bearer）	任意：`name`、`website_url`、`redirect_uris`、`terms_url`、`privacy_url`、`description`	独自の `api_key` を持つ `201` アプリケーションレコード（デフォルト名は "<organization name> App"）
6. 認証情報の取得	`GET /organizations/me/{org_id}/applications/{app_id}/`（Bearer）	-	`200` `{uuid, name, client_id, api_key, website_url, redirect_uris, terms_url, privacy_url, description, created_at}`
アプリケーションの更新	`PATCH /organizations/me/{org_id}/applications/{app_id}/`（Bearer）	作成時のフィールドのいずれか	完全なレコードを含む `200`。`uuid`、`client_id`、`api_key` は変更されません。

ルール	値
パスワード	8 文字以上で、大文字、小文字、数字、特殊文字をそれぞれ 1 文字以上含む必要があります。
認証コード	英数字 6 文字。有効期限は最新のコード送信から 10 分です。メールアドレスごとに 1 時間あたり 10 回まで試行でき、試行するごとに待ち時間が長くなります。
登録／再送	1 IP あたり 1 時間に 5 回（共通）。再送にはメールアドレスごとに 60 秒のクールダウンもあります。
ログイン	5 回失敗すると 15 分、10 回で 1 時間、20 回で 24 時間、アカウントがロックされます。IP あたり 1 分に 20 回、1 時間に 100 回までです。組織で SSO が適用されている場合は `403`。
アクセストークン	`expires_in` は 86400（24 時間）です。`Authorization: Bearer` として送信し、`verification.didit.me` には送信しないでください。
アプリケーション	作成、参照、更新できるのは組織のオーナーと管理者のみです（それ以外は `403`）。参照権限のない組織またはアプリケーションの場合は `404`。
エラー	`429` には `Retry-After` ヘッダーが含まれます。

紛失した API キーの復旧： ログインし、GET /organizations/me/、GET /organizations/me/{org_id}/applications/ を実行してから、アプリケーションレコードの api_key を確認してください。

ワークフロー

ベース URL： https://verification.didit.me/v3

ワークフローは、セッションで実行されるチェックの順序付きリストです。各バージョンには uuid があります。セッション作成時には workflow_id として指定し、ここでは {settings_uuid} として渡します。また、同じワークフローのすべてのバージョンで共通の workflow_id があり、バージョン1では uuid と同じ値です。新しいセッションでは、最新の published バージョンが使用されます。作成時に workflow_type フィールドはありません。KYC と KYB の違いは機能によって決まります。

Method	Path	Notes
`GET`	`/v3/workflows/`	ページネーション形式の `{count, next, previous, results[]}`。新しい順に表示されます。`limit`（デフォルトは50）、`offset`
`POST`	`/v3/workflows/`	完全な設定を `201` で返します。冪等ではありません。アプリケーションあたりのワークフロー数の上限は50です。
`GET`	`/v3/workflows/{settings_uuid}/`	1つのバージョンの完全な設定（機能の切り替え、しきい値、`documents_allowed`、`workflow_graph`、再試行ポリシー、価格）
`PATCH`	`/v3/workflows/{settings_uuid}/`	作成時と同じフィールドの許可リストを使用します。結果のバージョンを `200` で返します（以下のバージョン管理を参照）
`DELETE`	`/v3/workflows/{settings_uuid}/`	`204`。このバージョンのみを削除します（ほかのバージョンは残ります）。セッションの結果は保持されますが、ワークフローへの参照は `null` になります。

一覧の行に含まれるフィールド： uuid、workflow_id、version、status（draft／published）、has_draft、workflow_label、workflow_type（グラフワークフローの場合は null）、is_default、is_archived、is_white_label_enabled、features（" + " で連結された文字列。例："OCR + LIVENESS + FACE_MATCH"）、total_price、min_price、max_price、is_simple_workflow、is_editable、workflow_url、max_retry_attempts、retry_window_days、session_expiration_time、created_by、updated_at。

作成時の本文（厳密な許可リスト：`workflow_type` やフラット形式の `is_*_enabled` フラグなど、記載されていないキーはすべて `400` になります）

Body	Type	Default	Description
`features`	array	-	必須。1つ以上指定してください。各項目は `{"feature": "<UPPERCASE>", "config": {...}, "label": "optional"}` の形式で、実行順に並べます
`workflow_label`	string	`ID Verification`	最大50文字。必ず設定してください
`status`	string	published	省略すると公開されます。`"draft"` を指定すると、公開せずに保存します
`is_default`	boolean	-	新しいセッションのデフォルトワークフロー
`is_white_label_enabled`	boolean	`false`	ホワイトラベルのブランディングを適用します
`is_desktop_allowed`	boolean	`false`	デスクトップブラウザーでのフローを許可します
`max_retry_attempts`	integer	`3`	却下後の再試行回数（0～10）。`0` の場合、最初の却下後にブロックされます
`retry_window_days`	integer or null	`7`	1～365。`null` は全期間の上限を意味します
`face_liveness_max_attempts`	integer	`3`	セッションごとのライブネス送信回数（1～3）
`face_match_max_attempts`	integer	`3`	セッションごとの顔照合送信回数（1～3）
`session_expiration_time`	integer	`604800`	未完了のセッションが期限切れになるまでの秒数：3600～2419200

機能の値： OCR、NFC、LIVENESS、FACE_MATCH、PROOF_OF_ADDRESS、QUESTIONNAIRE、DOCUMENT_AI、PHONE_VERIFICATION、EMAIL_VERIFICATION、DATABASE_VALIDATION、AML、IP_ANALYSIS、AGE_ESTIMATION、KYB_REGISTRY、KYB_DOCUMENTS、KYB_KEY_PEOPLE。

目的	機能（順序）
フル KYC（ID + セルフィー）	`OCR`、`LIVENESS`、`FACE_MATCH`、必要に応じて `NFC`、`AML`、`IP_ANALYSIS`
年齢制限	`AGE_ESTIMATION`（ライブネスも実行します。`config.enable_id_verification_fallback` を指定すると、年齢が境界付近の場合に ID 検証に進みます）
住所確認	`PROOF_OF_ADDRESS`
アンケート	`config.questionnaire_uuid` を指定した `QUESTIONNAIRE`
カスタム書類	`DOCUMENT_AI`（`didit-document-ai` スキルを参照）
メール／電話のみ	`EMAIL_VERIFICATION`／`PHONE_VERIFICATION`
KYB（事業者）	`KYB_REGISTRY`、`KYB_DOCUMENTS`、`KYB_KEY_PEOPLE`、必要に応じて `AML`
順序と組み合わせのルール（それ以外は `400`）：

IP_ANALYSIS、AML、DATABASE_VALIDATION、KYB_KEY_PEOPLE を最初の機能にすることはできません。
FACE_MATCH と NFC は OCR の後に配置します。DATABASE_VALIDATION と人物の AML も OCR の後に配置します（KYB では AML を KYB_REGISTRY の後に配置します）。
KYB_DOCUMENTS と KYB_KEY_PEOPLE は KYB_REGISTRY の後に配置します。
KYB 機能と組み合わせられるのは AML、DOCUMENT_AI、QUESTIONNAIRE、PHONE_VERIFICATION、EMAIL_VERIFICATION、IP_ANALYSIS のみです。人物向け機能（OCR、LIVENESS、FACE_MATCH、NFC、PROOF_OF_ADDRESS、DATABASE_VALIDATION、AGE_ESTIMATION）とは組み合わせられません。
QUESTIONNAIRE には config.questionnaire_uuid（このアプリケーションのアンケート）が必要です。KYB_DOCUMENTS には、グループを少なくとも1つ含む config.kyb_required_document_groups が必要です。

機能ごとに共通する config キー（一覧は機能設定を参照してください。スコアとしきい値は0～100です。アクション値は大文字の DECLINE、REVIEW、NO_ACTION です）：

機能	キー
`OCR`	`documents_allowed`（`{"USA": {"DL": {"enabled": 1, "sides": 2}}}`。省略、`null`、または `{}` の場合は、すべての国と書類が対象です）、`duplicated_user_action`
`LIVENESS`	`face_liveness_method`（大文字の `PASSIVE`、`ACTIVE_3D`、`FLASHING`）、`face_liveness_score_decline_threshold`、`face_liveness_score_review_threshold`
`FACE_MATCH`	`face_match_score_decline_threshold`、`face_match_score_review_threshold`
`AML`	`aml_score_approve_threshold`、`aml_score_review_threshold`
`AGE_ESTIMATION`	`minimum_age_threshold`、`borderline_minimum_age_threshold`、`borderline_maximum_age_threshold`（1～100）、`enable_id_verification_fallback`
`QUESTIONNAIRE`	`questionnaire_uuid`（アンケート作成時に返される `questionnaire_id`）

wf = requests.post("https://verification.didit.me/v3/workflows/",
    headers={"x-api-key": API_KEY},
    json={"workflow_label": "KYC + AML", "features": [
        {"feature": "OCR", "config": {"duplicated_user_action": "REVIEW"}},
        {"feature": "LIVENESS", "config": {"face_liveness_method": "PASSIVE"}},
        {"feature": "FACE_MATCH", "config": {"face_match_score_decline_threshold": 40,
                                             "face_match_score_review_threshold": 60}},
        {"feature": "AML", "config": {"aml_score_approve_threshold": 80}},
    ]}).json()
workflow_uuid = wf["uuid"]

PATCH 時のバージョン管理：

現在のバージョン	送信する `status`	結果
公開済み	なし	同じ `uuid` と `version` のまま更新されます
公開済み	`"published"`	新しい公開バージョンが返されます（新しい `uuid`、`version` は + 1）。グループ内のドラフトはすべて削除されます。以降は返された `uuid` を使用してください。
公開済み	`"draft"`	`400` "Cannot revert a published version to draft."
ドラフト	`"published"`	ドラフトが更新され、公開されます
ドラフト	なし、または `"draft"`	ドラフトが更新され、ドラフトのまま維持されます

セッション

ベース URL： https://verification.didit.me/v3

ライフサイクル： セッションを作成し、ユーザーが url で認証します。Webhook を受信するか、判定をポーリングし、必要に応じて確認します（ステータスの更新、再提出、データの修正）。

ステータス： Not Started、In Progress、Approved、Declined、In Review、Expired、Abandoned、Kyc Expired、Resubmitted、Awaiting User（KYB で主要関係者の対応を待機中）。Pending ステータスはありません。

レート制限（キーあたり、1 分あたり）： すべての GET は 600、すべての POST／PATCH／DELETE は 300 です。POST /v3/session/ には個別に 600 の制限がありますが、書き込みの 300 件の制限にもカウントされるため、300 件を想定してください。update-data と update-poa-data はそれぞれ 10、generate-pdf は 50 です。429 には Retry-After が含まれます。

メソッド	パス	目的
`POST`	`/v3/session/`	セッションを作成
`GET`	`/v3/session/{sessionId}/decision/`	完全な結果
`GET`	`/v3/sessions/`	セッションの一覧表示とフィルタリング
`DELETE`	`/v3/session/{sessionId}/delete/`	1 件の KYC または KYB セッションを削除
`POST`	`/v3/sessions/delete/`	KYC セッションを一括削除
`GET`	`/v3/sessions/delete/{job_id}/`	一括削除ジョブをポーリング
`PATCH`	`/v3/session/{sessionId}/update-status/`	承認、却下、または再提出
`POST`	`/v3/session/{sessionId}/resubmission-preview/`	再提出メールをプレビュー
`PATCH`	`/v3/session/{sessionId}/features/{nodeId}/update-status/`	1 つのステップのステータスを設定
`PATCH`	`/v3/session/{sessionId}/update-aml-hit-status/`	1 件の AML ヒットを確認
`PATCH`	`/v3/session/{sessionId}/bulk-update-aml-hit-status/`	複数の AML ヒットを確認
`PATCH`	`/v3/session/{sessionId}/update-data/`	抽出された ID データを修正
`PATCH`	`/v3/session/{sessionId}/update-poa-data/`	住所証明データを修正
`PATCH`	`/v3/session/{sessionId}/kyb/{companyUuid}/update-data/`	KYB 企業データを修正
`PATCH`	`/v3/session/{sessionId}/kyb/parties/{partyUuid}/`	KYB の主要関係者をスキップまたは復元
`GET`	`/v3/session/{sessionId}/generate-pdf/`	PDF レポート
`POST`	`/v3/session/{sessionId}/share/`	別のアプリケーション用の共有トークン
`POST`	`/v3/session/import-shared/`	共有セッションをインポート
`GET`／`POST`	`/v3/sessions/{session_id}/reviews/`	アクティビティフィード／メモを追加
`POST`	`/v3/session/{sessionId}/sandbox/arm/`	サンドボックス専用：テストシナリオを準備

1. セッションを作成

POST /v3/session/

本文	型	必須	説明
`workflow_id`	uuid	はい	ワークフローの `uuid`
`vendor_data`	string	いいえ	ユーザーまたはビジネスの ID です。セッションをユーザー／ビジネスのエンティティに関連付け、重複検出に使用します。同じ `vendor_data` とワークフローを持つ未完了のセッションがある場合、新規作成の代わりにそのセッションが返されます（`201`、`callback` と `metadata` は更新されます）。
`callback`	url	いいえ	フロー完了後のリダイレクト先です。Didit は `verificationSessionId` と `status` を追加します
`callback_method`	string	いいえ	`initiator`（デフォルト）、`completer`、または `both`
`metadata`	JSON	いいえ	任意の JSON（オブジェクトを推奨）です。判定結果と Webhook に含まれます
`language`	string	いいえ	UI 言語：ISO 639-1 コード、または `pt-BR`、`zh-CN`、`zh-TW`、`cnr`。デフォルトはブラウザー検出です
`contact_details`	object	いいえ	`email`、`phone`（E.164）、`send_notification_emails`、`email_lang`：メールアドレス／電話番号の入力ステップに事前入力し、ステータスメールを送信します
`expected_details`	object	いいえ	ユーザーの入力内容との照合に使う値です（一致しない場合は警告になります）。詳細は以下を参照してください
`portrait_image`	base64	条件付き	参照用の顔画像。最大 2 MB、JPEG/PNG/WebP/TIFF。生体認証ワークフロー、および本人確認より先に顔照合を実行するグラフワークフローで必須です。ただし、`vendor_data` のユーザーに保存済みの顔画像がある場合を除きます（それ以外は `400`）。
`multi_account_segment`	string	いいえ	最大 64 文字です。重複顔チェックでは同じセグメントのセッションのみを比較します。ブロックリストには影響しません。
`sandbox_scenario`	string	いいえ	サンドボックスアプリケーション専用です（本番環境では `400`）：サンドボックステストのシナリオスラッグ

`expected_details` のキー	説明
`first_name`、`last_name`	あいまい一致で照合
`date_of_birth`	`YYYY-MM-DD`
`gender`	`M` または `F`
`nationality`、`country`、`id_country`、`poa_country`	ISO 3166-1 alpha-3。本人確認書類では `id_country` が `country` より優先されます
`address`	住所確認用の人が読める形式の住所です。`country` または `poa_country` が必要です（それ以外は `400`）
`identification_number`	予想される書類番号、個人番号、または納税者番号
`ip_address`	予想される IP
`expected_document_types`	`P`、`ID`、`DL`、`RP`、`HIC`、`TC`、`SSC` の配列
`company_name`、`registry_country`、`registration_number`	KYB セッション：登記検索に事前入力します。`registry_country` は ISO alpha-2、または `US-CA` のような下位区分です

レスポンス（201）：

{
  "session_id": "11111111-2222-3333-4444-555555555555",
  "session_number": 1234,
  "session_token": "abcdef123456",
  "url": "https://verify.didit.me/session/abcdef123456",
  "vendor_data": "user-123",
  "metadata": {"plan": "pro"},
  "status": "Not Started",
  "workflow_id": "a1b2c3d4-5678-90ab-cdef-111111111111",
  "workflow_version": 1,
  "callback": "https://yourdomain.com/verified"
}

ユーザーを url に誘導するか、session_token を SDK に渡してください（didit-sdk-integration を参照）。

2. セッションを取得（判定結果を取得）

GET /v3/session/{sessionId}/decision/

トップレベルのキー：session_id、session_kind、session_number、session_url、status、workflow_id、features、vendor_data、metadata、expected_details、contact_details、callback、created_at、expires_at、environment、resubmissions、reviews に加え、機能ごとの配列：id_verifications、nfc_verifications、liveness_checks、face_matches、phone_verifications、email_verifications、poa_verifications、document_ai_documents、questionnaire_responses、aml_screenings、ip_analyses、database_validations（KYB の場合：registry_checks、key_people_checks、document_verifications）。各機能ブロックには node_id が含まれます。以下のレビューエンドポイントではこの ID を使用します。メディア URL は署名付きで、有効期限は約 4 時間です。保存せずに、判定結果を再取得してください。

3. セッション一覧を取得

GET /v3/sessions/

クエリ	説明
`session_kind`	`user`（デフォルト）、`business`、または `all`
`status`	例：`Approved`、`Declined`、`In Review`
`vendor_data`	完全一致
`workflow_id`、`country`、`search`、`date_from`、`date_to`	一般的なフィルター
`limit` / `offset`	ページサイズ（デフォルトは 50）／スキップする行数

レスポンス（200）： {count, next, previous, results[]}。新しい順に並びます。各行には session_kind（user または business）が含まれます。

4. セッションの削除

DELETE /v3/session/{sessionId}/delete/      # one KYC or KYB session (KYB also deletes its key-people verifications)
POST   /v3/sessions/delete/                 # KYC sessions in bulk
GET    /v3/sessions/delete/{job_id}/        # poll a bulk job

削除は取り消せません。セッション、そのメディア、抽出データ、レビュー、顔の埋め込みが削除されます（顔テンプレートを保持する場合を除きます）。Webhook は送信されません。セッションから作成されたブロックリストのエントリと、User／Business エンティティは削除されません（lists エンドポイントと users/businesses エンドポイントを使用してください）。

Body（両エンドポイントで任意）	説明
`retain_face_embeddings`	`true` の場合、画像を含まない顔テンプレートをセッションの User に 1 つ保持します（重複検出は引き続き機能します）。`false` の場合は削除します。省略した場合はアプリケーションのポリシーを使用します
`face_retention_days`	1〜3650。テンプレートを保持し、アプリケーションに保持期間が設定されていない場合は必須です
`face_retention_deadline`	テンプレートの有効期限となる将来の日時
`deletion_instruction`	`operational_session_delete`（デフォルト）または `privacy_erasure`（データ主体からの要求：その User の保持されているすべてのテンプレートを消去します。`retain_face_embeddings: true` との併用はできません）
`instruction_id`	監査証跡に記録される参照情報（最大 255 文字）
`session_numbers`	一括削除のみ：数字のみの文字列（例：`["1201", "1202"]`）。`delete_all` を指定しない場合は必須です
`delete_all`	一括削除のみ：アプリケーションのすべての KYC セッションを削除します

単一削除：200 {session_id, session_number, face_retention_outcome, biometric_template_uuid, biometric_template_expires_at, deleted_child_verifications}。face_retention_outcome は deleted、retained_with_user、none、ineligible_no_vendor_user のいずれかです。再度呼び出すと 404 が返されます。503 の後はリクエストを再試行してください。
一括削除：20 セッション以下の場合は 200 {"results": [...]}、それを超える場合は {job_id, status, ...} を含む 202 が返されます。ジョブの status が COMPLETED または FAILED になるまでポーリングしてください（それまでは PENDING、PROCESSING）。ジョブは total、processed、outcomes、deleted_child_verifications、error を報告します。

5. セッションステータスの更新（承認、却下、再提出）

PATCH /v3/session/{sessionId}/update-status/

Body	型	必須	説明
`new_status`	string	はい	`Approved`、`Declined`、`Resubmitted` のいずれか
`comment`	string	いいえ	理由。セッションのレビューに保存されます
`nodes_to_resubmit`	array	いいえ	`Resubmitted` の場合：`[{"node_id": "ocr", "feature": "OCR"}]`。再提出が必要な、すでに試行済みのステップを自動選択する場合は省略します。
`send_email`	boolean	いいえ	ユーザーにメールを送信します（デフォルトは `false`）
`email_address`	string	条件付き	`send_email` が `true` の場合は必須です
`email_language`	string	いいえ	デフォルトは `en`
`email_preview_token`	string	いいえ	再提出プレビューの `preview_token`。`send_email` を指定する場合のみ使用します。メールの内容が変更された場合、またはトークンの有効期限（15 分）が切れた場合は `409` が返されます。

許可される現在のステータス： Approved、Declined、In Review、Kyc Expired、Abandoned、Resubmitted。Not Started、In Progress、Awaiting User、Expired のセッションは 400 を返します。新しいステータスは現在のステータスと異なる必要があります。
レスポンス（200）： {"session_id": "..."}。status.updated を発行します。
node_id： 判定の feature ブロックから取得してください。POST /v3/workflows/ で作成されたワークフローでは、feature のスラッグ（ocr、liveness、face_match など）を使用します。コンソールで作成したグラフでは、feature_ocr_1 のような ID を使用します。
再提出： 選択したステップのデータが削除され、有効期限がリセットされ、同じ url が再び機能します。サーバー側のステップ（AML、DATABASE_VALIDATION、IP_ANALYSIS）はユーザーなしで再実行されます。KYB_REGISTRY と KYB_KEY_PEOPLE は直接再提出できません。

再提出メールを事前にプレビューする（任意）： nodes_to_resubmit、email_address、email_language を指定して POST /v3/session/{sessionId}/resubmission-preview/ を呼び出します。何も変更されず、メールも送信されません。recipient、sender、subject、html、nodes_to_resubmit、requires_user_action、preview_token が返されます。その後、new_status: "Resubmitted"、同じ選択内容、send_email: true、email_preview_token を指定して update-status を呼び出します。

6. ステップと AML ヒットのレビュー

エンドポイント	本文	備考
`PATCH /v3/session/{sessionId}/features/{nodeId}/update-status/`	`new_status`（`Approved`、`Declined`、`In Review`。必須）、`comment`	1 つのステップのステータスです（グラフを使用しないワークフローでは、`nodeId` に `default` を指定します）。現在のステータスと異なる値を指定する必要があります。`{session_id, node_id, feature_type, new_status}` を返します。スタンドアロン API セッションでは利用できません。`data.updated` を発生させます。
`PATCH /v3/session/{sessionId}/update-aml-hit-status/`	`hit_id`、`review_status`（どちらも必須）、`node_id`	`hit_id` は AML チェックの `hits` 内のエントリーの `id` です。`data.updated` を発生させます。
`PATCH /v3/session/{sessionId}/bulk-update-aml-hit-status/`	`hit_updates: [{"hit_id", "review_status"}]`、`node_id`	すべて成功するか、すべて失敗します。不明な `hit_id` を指定すると `404` が返され、何も変更されません。

review_status：Unreviewed、Confirmed Match、False Positive、Inconclusive。レビュー担当者の判断は、継続的なモニタリングによる再スクリーニング後も保持されます。ワークフローに同じ種類の AML チェックが複数ある場合、node_id（本文またはクエリ）で対象を指定します。

7. 抽出データを修正する

変更するフィールドのみを送信します。同じ種類のチェックが複数あるワークフローでは、node_id（本文またはクエリ）を指定します。KYC と PoA の修正は data.updated を発生させます（manual_review をトリガーします）。

エンドポイント	セッションのステータス	フィールド
`PATCH /v3/session/{sessionId}/update-data/`	`Approved`、`Declined`、`In Review`、`Kyc Expired`	`document_type`、`document_subtype`、`document_number`、`personal_number`、`date_of_birth`、`date_of_issue`、`expiration_date`、`issuing_state`、`first_name`、`last_name`、`gender`（`M`/`F`/`U`）、`address`、`place_of_birth`、`nationality`、`marital_status`、`extra_fields`、`parsed_address`
`PATCH /v3/session/{sessionId}/update-poa-data/`	同上	`issuing_state`、`document_type`、`document_language`、`issuer`、`issue_date`、`poa_address`、`name_on_document`、`extra_fields`、`poa_parsed_address`
`PATCH /v3/session/{sessionId}/kyb/{companyUuid}/update-data/`	任意	`company_name`、`registration_number`、`country_code`、`region`、`incorporation_date`、`registration_date`、`dissolution_date`、`tax_number`、`legal_address`、`company_type`、`registry_status`、`verification_status`、`alternative_names`、`nature_of_business`、`registered_capital`、`registered_capital_amount`、`registered_capital_currency`、`website`、`email`、`phone`、`legal_entity_identifier`、`location_of_registration`、`vat_number`、`control_scheme`。`{}` を指定すると、変更せずに会社の情報を返します。Businesses の書き込み権限が必要です。
`PATCH /v3/session/{sessionId}/kyb/parties/{partyUuid}/`	任意	`is_skipped`（必須）：`true` にすると、Key People チェックから主要人物を除外し（例：その人物の KYC セッションが削除された場合）、ビジネスセッションを再計算します。`false` にすると、その人物を再度含めます。Businesses の書き込み権限が必要です。

8. PDF レポートを生成する

GET /v3/session/{sessionId}/generate-pdf/

application/pdf（添付ファイル）を返します。Approved、Declined、In Review、Kyc Expired のいずれかである KYC セッションと、Approved、Declined、In Review のいずれかである KYB セッションのみが対象です。それ以外のステータスでは 403 が返されます。スコープ付きキーで Media の読み取り権限が必要です。1 分あたり 50 件までです。

9. 共有とインポート（アプリケーション間で再利用可能な KYC）

POST /v3/session/{sessionId}/share/
POST /v3/session/import-shared/

共有リクエスト本文	必須	説明
`for_application_id`	はい	インポートする Didit アプリケーション（自身のアプリケーションではありません）の UUID
`ttl_in_seconds`	いいえ	60～86400。デフォルトは 3600

共有は Approved、Declined、In Review のセッションで利用できます（それ以外は 400）。応答は 200 で、{share_token, for_application_id, session_kind} を返します。

インポートリクエスト本文	必須	説明
`share_token`	はい	共有元アプリケーションのトークン
`trust_review`	はい	`true` の場合は元のステータスを維持し、`false` の場合はインポートされたセッションを `In Review` にします
`workflow_id`	はい	インポート先アプリケーションのワークフロー `uuid`（それ以外は `404`）
`vendor_data`	いいえ	ユーザー ID

インポートは、新しいセッションの判定結果とともに 201 を返します。セッションはアプリケーションごとに 1 回のみインポートできます（2 回目のインポートは 403）。期限切れ、無効、または別のアプリケーションのトークンの場合は 400 を返します。

10. セッションレビュー（アクティビティフィード）

GET  /v3/sessions/{session_id}/reviews/
POST /v3/sessions/{session_id}/reviews/

GET（KYC セッション）：{count, next, previous, results[]} をページネーション付きで返します。各項目には uuid、activity_type（COMMENT、STATUS_UPDATED、KYC_DATA_UPDATED、POA_DATA_UPDATED、AML_HIT_STATUS_UPDATED、...）、actor_display、actor_email、actor_type（API_KEY、CONSOLE_USER、SYSTEM）、previous_status、new_status、comment、mentioned_emails、previous_value、new_value、changed_fields、metadata、created_at が含まれます。
POST はメモのみを追加します。comment と new_status はどちらも任意です。new_status（セッションのあらゆるステータス）はラベルとしてのみ使用されます。セッションのステータスは変更されず、Webhook も送信されません。応答は 201 で、{user, new_status, comment, created_at} を返します。承認または却下するには、update-status を使用してください。

11. サンドボックス：シナリオの設定

Session-Token: <session_token> ヘッダー（x-api-key ではありません）と本文 {"scenario": "<slug>"} を指定して POST /v3/session/{sessionId}/sandbox/arm/ を実行すると、ユーザーが開始する前にサンドボックスシナリオが適用されます。{session_id, scenario, status} を返します。検証開始後は 400、ライブアプリケーションでは 404 を返します。シナリオのスラッグとマジック値については、サンドボックステストを参照してください。

一括インポート（移行）

Didit の標準スキーマに準拠した CSV または NDJSON ファイルから、過去の検証データをインポートします（最初に以前のプロバイダーのエクスポートデータをこのスキーマにマッピングしてください）。

POST /v3/session/imports/                       # JSON {source_file_url, ...} or multipart with `file`
GET  /v3/session/imports/template/?import_type=  # canonical CSV header for that import type
GET  /v3/session/imports/{importId}/            # job status and counters
GET  /v3/session/imports/{importId}/errors/     # per-row errors (row_number, external_id, error, raw_row)

本文	必須	説明
`source_file_url` または `file`	はい（いずれか一方）	ファイルの公開 URL、またはマルチパートアップロード。両方を指定した場合、またはどちらも指定しない場合は `400`。最大 25 MB。
`import_type`	いいえ	`user_verification`（デフォルト）、`business_verification`（KYB ワークフローが必要）、`status_rules`、`transactions`
`workflow_id`	`transactions` を除きはい	ワークフロー `uuid`。`user_verification` では KYB ワークフローを指定できません
`source_format`	いいえ	`csv` または `ndjson`。アップロードされたファイルの形式は拡張子（`.csv`、`.ndjson`）から判定されます。それ以外の拡張子の場合は `400` を返します。

インポートはデフォルトで無効になっており、Didit が組織ごとに有効化します（有効化されていない場合は 403）。サンドボックスアプリケーションでは 403 を返します。
アプリケーションごとに実行中のインポートジョブは 1 件のみです（実行中は 429）。
201 のジョブには、uuid、status（PENDING、PROCESSING、COMPLETED、FAILED、PAUSED、CANCELLED）、import_type、source_format、source_filename、total_rows、processed_rows、created_count、updated_count、skipped_count、failed_count、last_error、タイムスタンプが含まれます。
インポートされたレコードには metadata.imported_from: "generic" のタグが付けられます。

リスト（ブロック／許可／カスタム）

ブロックリストとの一致は、今後の検証やスクリーニングを拒否します。許可リストとカスタムリストは、ワークフローの条件やルールに使用されます。リストについては、上記のドキュメントページで説明しています。

list_type：blocklist（エントリータイプごとにシステムリストが1つあり、自動的に作成されます。作成、名前変更、削除はできません）、allowlist、custom。
entry_type：face、document、phone、email、ip_address、device_fingerprint、wallet_address、bank_account、user、business、country、key。

メソッド	パス	備考
`GET`	`/v3/lists/`	フィルター：`list_type`、`entry_type`。`ordering`：`created_at`、`entry_count`、`last_entry_added_at`（降順にするには先頭に `-` を付けます。デフォルトは `-created_at`）。`limit`、`offset`
`POST`	`/v3/lists/`	`name`（アプリケーションごとに一意。使用済みの場合は `400`）、`list_type`（`allowlist` または `custom`）、`entry_type`、`description`
`GET`	`/v3/lists/{list_uuid}/`	1つのリスト
`PATCH`	`/v3/lists/{list_uuid}/`	`name`、`description`。システムリストの場合は `400` を返します
`DELETE`	`/v3/lists/{list_uuid}/`	`204`。許可リストとカスタムリストのみ
`GET`	`/v3/lists/{list_uuid}/entries/`	`search`、`reference_session_id`、`limit`、`offset`
`POST`	`/v3/lists/{list_uuid}/entries/`	エントリーを追加（以下を参照）。`201`
`POST`	`/v3/lists/{list_uuid}/entries/face-upload/`	画像から顔を追加
`DELETE`	`/v3/lists/{list_uuid}/entries/{entry_uuid}/`	`204`。システムブロックリストでは、一致するエンティティのブロックも解除します

ブロックリストの uuid を検索する： GET /v3/lists/?list_type=blocklist&entry_type=face（または document、phone、…）。

エントリー本文	必須	説明
`value`	条件付き	値（メールアドレス、E.164 形式の電話番号、IP または CIDR、alpha-3 の国コード、…）。`reference_session_id` を指定しない場合は必須です。
`reference_session_id`	条件付き	リストの `entry_type` に応じて、セッションから値を取得します（face、document、phone、email、ip_address、device_fingerprint）
`face_image_source`	いいえ	`reference_session_id` を指定した顔ブロックリストの場合：`liveness`（デフォルト）、`front_image_camera_front`、`back_image_camera_front`（ユーザーが書類を撮影した際に撮った自撮り画像）
`reference_node_id`	いいえ	書類撮影の `face_image_source` と併用する場合：使用する自撮り画像の ID 検証ノード
`reference_object_uuid`	いいえ	追跡可能性のためのソーストランザクション、ユーザー、またはビジネス
`display_label`、`comment`	いいえ	ラベルと理由
`metadata`	いいえ	例：`{"reference_type": "vendor_user"}`

顔画像アップロードの本文： image（data: プレフィックスなしの base64 JPG または PNG、最大 2 MB）と任意の comment。顔ブロックリストまたは顔許可リストのみ（カスタムリストやその他のエントリータイプでは 400 を返します）。顔がない場合は 400。複数の顔がある場合は、最大の顔が使用されます。

ブロックリストとの一致では、次のような警告が発生します： FACE_IN_BLOCKLIST、POSSIBLE_FACE_IN_BLOCKLIST、ID_DOCUMENT_IN_BLOCKLIST、PHONE_NUMBER_IN_BLOCKLIST、EMAIL_IN_BLOCKLIST、IP_ADDRESS_IN_BLOCKLIST、DEVICE_FINGERPRINT_IN_BLOCKLIST。

アンケート

QUESTIONNAIRE ワークフロー機能で実行するカスタムフォームです。

Method	Path	Notes
`GET`	`/v3/questionnaires/`	ページ分割された `{count, next, previous, results[]}`
`POST`	`/v3/questionnaires/`	`201`。レスポンスの `questionnaire_id` が `config.questionnaire_uuid` に設定する値です
`GET`	`/v3/questionnaires/{questionnaire_uuid}/`	1件のアンケート
`PATCH`	`/v3/questionnaires/{questionnaire_uuid}/`	部分更新
`DELETE`	`/v3/questionnaires/{questionnaire_uuid}/`	`204`

Body	Required	Description
`title`	はい	最大255文字
`languages`	はい	`"en"` を含める必要があります
`form_elements`	はい	要素が1つ以上必要です
`default_language`	いいえ	デフォルトは `en`。`languages` に含まれている必要があります
`description`	いいえ	ユーザーに表示されます
`is_active`	いいえ	デフォルトは `true`
`status`	いいえ	公開する場合は省略します。公開せずに保存する場合は `draft` を指定します

Element field	Description
`element_type`	必須。 `short_text`、`long_text`、`paragraph`、`dropdown`、`single_choice`、`multiple_choice`、`number`、`image`、`file_upload`、`time`、`email`、`address`、`phone`、`country`、`date_picker`、`consent`、`section_header`、`separator`、`heading`（`checkbox` と `date` はありません）
`label`	必須。 `languages` に含まれるすべての言語の翻訳：`{"en": "Occupation?"}`
`id`	任意の固定ID（自動で `q1`、`q2`、…が割り当てられます）
`description`, `placeholder`	翻訳オブジェクト
`is_required`	デフォルトは `false`
`options`	`dropdown`、`single_choice`、`multiple_choice` で必須：`[{"value": "employed", "label": {"en": "Employed"}}]`（`value` は省略可能）
`max_files`	1～5。`file_upload` と `image` に使用します
`validation`	`short_text`／`long_text`：`pattern`、`min_length`、`max_length`。`number`：`min`、`max`

この API では、シンプルで直線的なアンケートを作成できます。分岐、条件付き質問、繰り返し可能なグループは Console で作成します。element_type: "repeatable_group" と branches、required_if、repeatable_config フィールドは 400 を返します。Console で作成した繰り返し可能なグループの回答は、決定内の REPEATABLE_GROUP 要素として返されます。

q = requests.post("https://verification.didit.me/v3/questionnaires/",
    headers={"x-api-key": API_KEY},
    json={
        "title": "Employment Details",
        "languages": ["en"],
        "default_language": "en",
        "form_elements": [
            {"element_type": "short_text", "label": {"en": "Occupation?"}, "is_required": True},
            {"element_type": "single_choice", "label": {"en": "Employment status"},
             "options": [{"label": {"en": "Employed"}}, {"label": {"en": "Student"}}]},
        ],
    }).json()
questionnaire_uuid = q["questionnaire_id"]

ユーザー（KYC）

vendor_data をキーとする、検証済みの個人です。ユーザーの status はモニタリングステータスであり、検証結果ではありません。値は ACTIVE、FLAGGED、BLOCKED のいずれかです。

メソッド	パス	備考
`GET`	`/v3/users/`	`limit`（デフォルトは 50）、`offset`
`POST`	`/v3/users/create/`	`201` でユーザーレコード全体を返します。同じ `vendor_data` が存在する場合は `400` を返します
`GET`	`/v3/users/{vendor_data}/`	1 人のユーザー
`PATCH`	`/v3/users/{vendor_data}/`	変更するフィールドのみを送信します（`metadata` は全体が置き換えられます）
`PATCH`	`/v3/users/{vendor_data}/update-status/`	`status`（必須）、任意の `reason`。`BLOCKED` にすると、`vendor_data` もシステムのブロックリストに追加されます。`user.status.updated` を発火します。
`POST`	`/v3/users/delete/`	`vendor_data_list`、`didit_internal_id_list`（併用可能）、または `delete_all: true` を指定します。`{deleted}` を返します
`GET`	`/v3/users/{vendor_data}/generate-pdf/`	報告対象となるユーザーの KYC セッション（新しいものから 20 件）を含む PDF。該当するセッションがない場合は `403`
`POST`	`/v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/`	信頼できる顔を登録します。`image`（base64 JPG/PNG、最大 2 MB）、`comment` を指定します。重複検出と顔検索のためにインデックス化されますが、ブロックリストには追加されません。`201`。

作成／更新フィールド： vendor_data（作成時は必須）、full_name、display_name、date_of_birth（YYYY-MM-DD）、status（デフォルトは ACTIVE）、metadata（オブジェクト）、approved_emails、approved_phones、issuing_states。

一覧の行フィールド： didit_internal_id、vendor_data、display_name、full_name、effective_name、date_of_birth、status、portrait_image_url、session_count、approved_count、declined_count、in_review_count、issuing_states、approved_emails、approved_phones、features、features_list、first_session_at、last_session_at、last_activity_at、tags、created_at。

AML 継続的モニタリング（ユーザーと事業者）

POST /v3/users/aml-monitoring/
POST /v3/businesses/aml-monitoring/
GET  /v3/aml-monitoring/jobs/{job_id}/

本文：is_enabled（必須）、estimate_only（デフォルトは false。変更を加えずに費用見積もりを返します）、vendor_data_list および／または didit_internal_id_list（合計で最大 1000 個の識別子）。最大 20 件のプロフィールはインラインで処理されます（ジョブ完了時に 200）。それを超える場合は 202 を返し、バックグラウンドで実行されます。ジョブ：job_id、status（PENDING、PROCESSING、COMPLETED、FAILED）、is_enabled、target_type、total、processed、outcomes、results[]、error、created_at、completed_at。クレジットが不足している場合は、estimate とともに 403 を返します。AML Monitoring は料金ページに年額 $0.07 として掲載されています。

生体認証テンプレート

セッション削除後（retain_face_embeddings またはアプリケーションの保持ポリシーにより）にアプリケーションが保持する、画像を含まない顔テンプレートです。これにより、重複検出を引き続き利用できます。API キーのみで使用できます。

メソッド	パス	備考
`GET`	`/v3/biometric-templates/`	`vendor_data`（部分一致）、`vendor_user_uuid`、`status`、`source_type`（`session_delete`、`automatic_retention`、`backfill`）、`retained_from`、`retained_to`、`ordering`（`retained_at`、`expires_at`。`-` を付けると逆順）；`limit`、`offset` で絞り込み
`GET`	`/v3/biometric-templates/count/`	同じフィルターを使用して `{count}` を返します
`GET`	`/v3/biometric-templates/{template_uuid}/`	1 件のテンプレート
`DELETE`	`/v3/biometric-templates/{template_uuid}/`	完全削除：`{uuid, outcome}`（`purged` または `already_purged`）
`POST`	`/v3/biometric-templates/delete/`	`template_uuids` または `delete_all: true`（対象を絞り込むフィルターも指定可能）：`{results: [{uuid, outcome}]}`

事業者（KYB）

vendor_data をキーとする、検証済みの企業です。モニタリングステータスはユーザーと同じく、ACTIVE／FLAGGED／BLOCKED です。

GET    /v3/businesses/                              # limit, offset
POST   /v3/businesses/create/                       # vendor_data, display_name, legal_name, registration_number, country_code (ISO alpha-2), status, metadata
GET    /v3/businesses/{vendor_data}/
PATCH  /v3/businesses/{vendor_data}/                # display_name, legal_name, registration_number, country_code, status, metadata
PATCH  /v3/businesses/{vendor_data}/update-status/  # status (required), optional reason; fires business.status.updated
POST   /v3/businesses/delete/                       # vendor_data_list, didit_internal_id_list, or delete_all: true -> {deleted}
POST   /v3/businesses/aml-monitoring/               # see AML Ongoing Monitoring above

KYB Registry（セッションなし）

エンドポイント	本文	料金
`POST /v3/kyb/search/`	`country_code`（必須。ISO alpha-2。US の場合は `US-CA` のように州も指定）、`name` および／または `registration_number`、`search_type`（`contains`）、`vendor_data`、`metadata`、`webhook_url`	有料ソースの結果が得られた検索1回につき $0.50
`POST /v3/kyb/select/`	`kyb_response_id`（必須）、`vendor_data`、`metadata`	ライトプロフィールと役員。$2.00（国によって料金が異なります）
`POST /v3/kyb/shareholders/`	select と同じ	ライトプロフィールに直接の株主情報を追加。国によって $5.00～$22.00
`POST /v3/kyb/ubo/`	select と同じ	株主情報に最終受益所有者を追加。国によって $9.00～$96.00

kyb_response_id は同じアプリケーションでの検索によって取得する、有効期間の短い ID です。すぐに select を呼び出し、保存するのではなく再検索してください。webhook_url を指定すると、検索結果は直ちに返され（search_status: "pending"）、その後 Didit が署名なしの kyb.registry_search.resolved コールバックを POST します（ヘッダー X-Didit-Unsigned-Callback: true）。request_id で照合してください。レジストリの処理中は、Shareholders と UBO の呼び出しが 202 を返すことがあります。

トランザクション

トランザクションモニタリングには専用のスキルがあります。トランザクションの作成、トラベルルールの交換、ウォレットのスクリーニング、ルールの管理には didit-transaction-monitoring を、ユーザーイベントには didit-event-monitoring を使用してください。基本的なルートは次のとおりです。

GET   /v3/transactions/          # limit, offset
POST  /v3/transactions/          # required: transaction_id, transaction_category, transaction_details, subject{vendor_data, full_name, ...}
GET   /v3/transactions/{uuid}/   # Didit's transaction uuid from the create response, NOT your transaction_id

transaction_category：finance、kyc、travel_rule、user_event、audit_trail_event、gambling_bet、gambling_limit_change、gambling_bonus_change。

請求

エンドポイント	本文	レスポンス
`GET /v3/billing/balance/`	-	`{"balance": "142.5000", "auto_refill_enabled": true, "auto_refill_amount": "100.0000", "auto_refill_threshold": "10.0000"}`。自動チャージの値が未設定の場合は `null` です
`POST /v3/billing/top-up/`	`amount_in_dollars`（必須、最小50）、`success_url`、`cancel_url`（両方を明示的に渡してください）	`200` `{"checkout_session_id": "cs_...", "checkout_session_url": "https://checkout.stripe.com/..."}`

支払い用に checkout_session_url をユーザーに提示してください。支払いが確定すると残高が増加します。チャージのエラー（400）は、例のような JSON 配列で返されます：["Amount must be at least $50."]。年間プランを利用している組織は 400 を受け取り、アカウントマネージャーを通じてチャージします。

カスタマイズ（ブランディング）

GET   /v3/customization/
PATCH /v3/customization/     # application/json for settings, multipart/form-data for images

PATCH フィールド	備考
`color_primary`、`color_secondary`、`color_background`、`color_panel`、`color_panel_10`、`color_on_panel_1`、`color_on_panel_2`、`color_on_background`、`color_button_1`、`color_button_2`、`color_button_text_1`、`color_button_text_2`、`color_pill_text`	16進数カラー
`border_radius_panel`、`border_radius_buttons`、`font_family`、`font_weight`	レイアウトとフォント
`app_public_name`、`privacy_policy_url`、`skip_welcome_screen`、`disable_login_with_didit`、`hide_progress_bar`、`callback_seconds`	フローのオプション
`image_square`、`image_rectangular`、`image_favicon`	マルチパートアップロード（ロゴとファビコン）
`delete_logo_square`、`delete_logo_rectangular`、`delete_favicon`	`true` を指定すると画像が削除されます

送信したフィールドのみが変更されます。カスタムドメインとホワイトラベルのメールは Business Console でのみ設定できます（ここでは 400 が返されます）。

Webhook の宛先

任意の数の宛先を登録できます。それぞれに独自の URL、ペイロードのバージョン、イベント、署名シークレットを設定できます。

Method	Path	Notes
`GET`	`/v3/webhook/destinations/`	`uuid`、`label`、`url`、`enabled`、`webhook_version`、`subscribed_events`、`subscribed_events_count`、`deliveries_count`、`failed_deliveries_count`、`average_response_time_ms`、`error_rate_percentage`、`last_delivery_at`、`created_at`、`updated_at` の配列（古い順）。一覧の各行にシークレットは含まれません。
`POST`	`/v3/webhook/destinations/`	`secret_shared_key` と配信の `summary` を含む `201`
`GET`	`/v3/webhook/destinations/{destination_uuid}/`	`secret_shared_key` を含みます
`PATCH`	`/v3/webhook/destinations/{destination_uuid}/`	作成時と同じフィールドです。`subscribed_events` はマージされず、置き換えられます。シークレットはローテーションされません。
`DELETE`	`/v3/webhook/destinations/{destination_uuid}/`	`204`。繰り返し実行すると `404` を返します

Create body	必須	説明
`label`	はい	名前。最大 255 文字
`url`	はい	HTTPS エンドポイント。アプリケーションごとに一意である必要があります（すでに使用されている場合は `400`）
`subscribed_events`	実質的に必須	配信するイベント（以下の一覧を参照）。`[]` は `400` を返します。省略すると、何も受信しない宛先が作成されます。
`webhook_version`	いいえ	`v1`、`v2`、または `v3`。`v3` を使用してください
`enabled`	いいえ	デフォルトは `true` です。`false` にすると宛先は停止状態になります

dest = requests.post(
    "https://verification.didit.me/v3/webhook/destinations/",
    headers={"x-api-key": API_KEY},
    json={"label": "Prod", "url": "https://yourdomain.com/webhooks/didit", "webhook_version": "v3",
          "subscribed_events": ["status.updated", "data.updated"]},
).json()
secret = dest["secret_shared_key"]   # store it in your secrets manager

# Pause a destination without deleting it
requests.patch(f"https://verification.didit.me/v3/webhook/destinations/{dest['uuid']}/",
               headers={"x-api-key": API_KEY}, json={"enabled": False})

Webhook イベントと署名

Didit は、イベントを購読している有効なすべての宛先に JSON を POST します（User-Agent: DiditWebhook/2.0 +https://didit.me）。

イベント（`webhook_type`）	発生条件
`status.updated`	KYC または KYB セッションのステータスが変更されたとき（KYB ペイロードには `session_kind: "business"` と `business_session_id` が追加されます）
`data.updated`	セッションデータが後から編集されたとき（レビュアーによる修正、ステップまたは AML ヒットのステータス変更）
`user.status.updated` / `user.data.updated`	ユーザーの `ACTIVE`／`FLAGGED`／`BLOCKED` ステータス、またはプロフィールデータが変更されたとき
`business.status.updated` / `business.data.updated`	事業者の同様の変更があったとき
`activity.created`	`subscribed_events` では受け付けられますが、実際のトラフィックには送信されません
`transaction.created` / `transaction.status.updated`	取引が最初の判定とともに作成されたとき／取引のステータスが変更されたとき
`travel_rule.status.updated`	Travel Rule の交換のステータスが変更されたとき

セッションイベントのエンベロープ：

フィールド	説明
`event_id`	宛先間および再試行の間で同じです。この値を使って重複排除します
`webhook_type`	上記のいずれかのイベント
`timestamp`	ディスパッチ時の Unix 秒（再試行のたびに更新され、`X-Timestamp` と同じ値になります）
`created_at`	レコードが最後に更新された時刻を示す Unix 秒
`application_id`、`environment`	`environment` は `live` または `sandbox` です
`session_id`、`status`	ステータスにはセッションのラベル（`Approved`、`Kyc Expired`、...）が使用されます
`workflow_id`、`workflow_version`、`vendor_data`、`metadata`	設定されている場合
`sandbox_scenario`	サンドボックスセッションで設定されたシナリオ。それ以外の場合は `null`
`trigger`	任意：`manual_review`、`manual_step_update`、`ongoing_monitoring`
`decision`	`status` が `Approved`、`Declined`、`In Review`、または `Abandoned` の場合のみ。判定エンドポイントと同じスキーマです
`resubmit_info`	`status` が `Resubmitted` の場合の `{nodes_to_resubmit, reasons}`

配信： 速やかに 2xx を返し、非同期で処理してください。5xx、404、タイムアウト、または接続エラーの場合は最大 2 回再試行されます（約 1 分後、その後さらに約 4 分後）。その他の 3xx／4xx 応答は再試行されません。

署名ヘッダー

ヘッダー	署名対象	用途
`X-Timestamp`	ディスパッチ時の Unix 秒	現在時刻との差が 300 秒を超える場合は拒否します
`X-Signature-V2`	正規化した JSON の HMAC-SHA256（16 進数）。本文を解析し、整数値の浮動小数点数を整数に変換してから、`json.dumps(..., sort_keys=True, separators=(",", ":"), ensure_ascii=False)` を実行します。タイムスタンプのプレフィックスはありません。	推奨：JSON を再エンコードするフレームワークでも有効です
`X-Signature`	正確な生の本文バイト列の HMAC-SHA256（16 進数）	生の本文を読み取れる場合
`X-Signature-Simple`	`"{timestamp}:{session_id}:{status}:{webhook_type}"` の HMAC-SHA256（`session_id` を含まないイベントでは `"{timestamp}::{status}:{webhook_type}"`）	非推奨：`decision` ではなく、エンベロープのみを対象とします。これに依存する場合は、処理を実行する前に API からレコードを再取得してください。

キーは宛先の secret_shared_key です。

import hashlib
import hmac
import json
import time


def shorten_floats(value):
    """Whole-number floats become ints, recursively (87.0 -> 87), as Didit does before signing."""
    if isinstance(value, dict):
        return {k: shorten_floats(v) for k, v in value.items()}
    if isinstance(value, list):
        return [shorten_floats(v) for v in value]
    if isinstance(value, float) and value.is_integer():
        return int(value)
    return value


def verify_webhook(body: bytes, headers: dict, secret: str, now: int | None = None, tolerance: int = 300) -> bool:
    """Verify a Didit webhook. `body` is the raw request body, `headers` the request headers (any casing)."""
    h = {str(k).lower(): v for k, v in headers.items()}
    try:
        ts = int(h.get("x-timestamp", ""))
    except (TypeError, ValueError):
        return False
    current = now if now is not None else int(time.time())
    if abs(current - ts) > tolerance:
        return False

    if isinstance(body, str):
        body = body.encode("utf-8")
    key = secret.encode("utf-8")
    candidates = []
    try:
        canonical = json.dumps(
            shorten_floats(json.loads(body)), sort_keys=True, separators=(",", ":"), ensure_ascii=False
        )
        v2 = hmac.new(key, canonical.encode("utf-8"), hashlib.sha256).hexdigest()
        candidates.append((h.get("x-signature-v2"), v2))
    except (ValueError, TypeError):
        pass
    raw = hmac.new(key, body, hashlib.sha256).hexdigest()
    candidates.append((h.get("x-signature"), raw))
    return any(sig and hmac.compare_digest(str(sig), expected) for sig, expected in candidates)

# Minimal Flask receiver
import os
from flask import Flask, request, abort

app = Flask(__name__)

@app.post("/webhooks/didit")
def didit_webhook():
    body = request.get_data()  # raw bytes, before any JSON parsing
    if not verify_webhook(body, dict(request.headers), os.environ["DIDIT_WEBHOOK_SECRET"]):
        abort(401)
    event = request.get_json()
    # dedupe on event["event_id"], then queue work by event["webhook_type"]
    return {"ok": True}

エラーレスポンス（すべてのエンドポイント）

コード	意味	対応
`400`	リクエストが無効です	レスポンス本文のフィールドエラーを確認してください
`401`	API キーの有効期限が切れています	キーをローテーションするか、Developers > API keys で新しいキーを作成してください
`403`	API キーがない、誤っている、または取り消されている、スコープ付きキーにこのエンドポイントへのアクセス権がない、キーの IP 許可リスト外からのリクエスト、またはクレジット不足	`detail` または `error` のメッセージを確認してください。`x-api-key` ヘッダーまたはキーのアクセス権を修正するか、クレジットを追加してください
`404`	リソースが見つからない、またはセッションがスコープ付きキーのワークフロー／承認済みのみの制限対象外です	ID とキーの制限を確認してください
`409`	update-status：`email_preview_token` が一致しなくなっています（内容が変更されたか、15 分より前に生成されています）	もう一度プレビューしてから再試行してください
`429`	レート制限：キーごとに 1 分あたり POST/PATCH/DELETE は 300 リクエスト、GET は 600 リクエストです	`Retry-After` 秒待ってから再試行してください
`503`	セッションまたはユーザーの削除：ストレージ依存先を利用できません	同じリクエストを再実行してください

アカウント設定エンドポイント（apx.didit.me/auth/v2）では Bearer トークンを使用します。形式が不正または期限切れのトークンでは 401、トークンがない場合、または組織のオーナーか管理者ではない場合は 403、Retry-After とともに 429 が返されます。

一般的なワークフロー

KYC の完全なオンボーディング

1. POST /programmatic/register/ + POST /programmatic/verify-email/  -> application.api_key
2. POST /v3/workflows/                -> features [OCR, LIVENESS, FACE_MATCH, AML]; keep wf["uuid"]
3. POST /v3/webhook/destinations/     -> url + subscribed_events ["status.updated", "data.updated"]; store secret_shared_key
4. POST /v3/session/                  -> workflow_id + vendor_data; send the user to url
5. Webhook status.updated             -> verify_webhook(), dedupe on event_id
6. GET /v3/session/{id}/decision/     -> read results (re-fetch for fresh media URLs)

手動審査とブロックリスト

1. Webhook: status "In Review"
2. GET /v3/session/{id}/decision/                     -> inspect warnings, AML hits, node_ids
3. AML hits: PATCH .../update-aml-hit-status/         -> False Positive / Confirmed Match
4. Legit:  PATCH .../update-status/ {"new_status": "Approved", "comment": "..."}
   Fraud:  PATCH .../update-status/ {"new_status": "Declined", "comment": "..."}
           GET /v3/lists/?list_type=blocklist&entry_type=face   -> blocklist uuid
           POST /v3/lists/{uuid}/entries/ {"reference_session_id": "<session_id>"}
           (repeat with entry_type=document for the ID document)

ユーザーにステップのやり直しを依頼する

1. GET /v3/session/{id}/decision/                     -> node_id of the failed step (e.g. "ocr")
2. POST /v3/session/{id}/resubmission-preview/        -> preview_token (optional)
3. PATCH /v3/session/{id}/update-status/              -> new_status "Resubmitted", nodes_to_resubmit,
                                                         send_email true, email_address, email_preview_token
4. The same url works again; status.updated fires when the user finishes

複数のアプリケーション間で再利用できる KYC

App A: POST /v3/session/{id}/share/ {"for_application_id": "<app B uuid>"}  -> share_token
App B: POST /v3/session/import-shared/ {"share_token", "trust_review": true, "workflow_id": "<app B workflow uuid>"}

ワークフロー内のアンケート

1. POST /v3/questionnaires/  -> questionnaire_id
2. POST /v3/workflows/       -> {"features": [{"feature": "OCR"}, {"feature": "QUESTIONNAIRE",
                                 "config": {"questionnaire_uuid": "<questionnaire_id>"}}]}
3. POST /v3/session/         -> workflow_id = the new workflow's uuid

データ主体の消去

1. DELETE /v3/session/{id}/delete/ {"deletion_instruction": "privacy_erasure", "instruction_id": "ticket-123"}
2. POST /v3/users/delete/ {"vendor_data_list": ["user-123"]}

セッション作成前に残高を確認する

1. GET /v3/billing/balance/     -> balance
2. If low: POST /v3/billing/top-up/ {"amount_in_dollars": 50, "success_url": ..., "cancel_url": ...}
3. POST /v3/session/

ユーティリティスクリプト

setup_account.py：登録、認証、確認コードの再送、ログイン

pip install requests
read -rs DIDIT_PASSWORD && export DIDIT_PASSWORD   # optional: otherwise each command prompts
python scripts/setup_account.py register [email protected]
# (check email for the 6-character code)
python scripts/setup_account.py verify [email protected] A3K9F2      # prints org uuid, app uuid, api_key
python scripts/setup_account.py resend-otp [email protected]
python scripts/setup_account.py login [email protected]

パスワードは DIDIT_PASSWORD 環境変数から取得するか、入力内容を表示しないプロンプトで入力します。コマンドラインにパスワードを指定しないでください。他のローカルユーザーがプロセス一覧で読み取れるうえ、シェルの履歴やエージェントのログにも残ります。古い呼び出し元との互換性のため、位置引数でパスワードを指定することもできますが、スクリプトは警告を表示します。エージェントがターミナルなしでこれらのコマンドを実行する場合、スクリプトは入力を促せません。パスワードを会話に貼り付けるのではなく、エージェントの環境で DIDIT_PASSWORD をエクスポートするようユーザーに依頼してください。

manage_workflows.py：ワークフローの CRUD

export DIDIT_API_KEY="your_key"
python scripts/manage_workflows.py list --limit 50
python scripts/manage_workflows.py create --label "My KYC" --liveness --face-match
python scripts/manage_workflows.py create --label "Age check" --features '[{"feature": "AGE_ESTIMATION"}]'
python scripts/manage_workflows.py get <uuid>
python scripts/manage_workflows.py update <uuid> --label "Renamed KYC"
python scripts/manage_workflows.py update <uuid> --features '[{"feature":"OCR"},{"feature":"AML"}]' --status published
python scripts/manage_workflows.py delete <uuid>

create_session.py：セッションの作成、取得、一覧表示

export DIDIT_API_KEY="your_key"
python scripts/create_session.py create --workflow-id <uuid> --vendor-data user-123
python scripts/create_session.py create --workflow-id <uuid> --vendor-data user-123 \
    --callback https://yourdomain.com/verified --metadata '{"plan": "pro"}'
python scripts/create_session.py get <session_id>
python scripts/create_session.py list --status Approved --limit 20 --offset 0

すべてのスクリプトはライブラリとしてインポートできます。

from scripts.setup_account import register, verify_email, resend_otp, login
from scripts.manage_workflows import list_workflows, create_workflow, update_workflow
from scripts.create_session import create_session, get_decision, list_sessions

Markdown 対応

ログインしてコメント

基本情報

作者: didit-protocol
リポジトリ: didit-protocol/skills
カテゴリ: セキュリティ
インストール数: 234
GitHub スター: 29

問題を報告