ユーザー操作API：ベンダーユーザーのCRUD

ユーザーエンティティの基本的な管理は、/v3/users/配下の公開エンドポイントで行います。インポートした顔画像のアップロードなど、プロフィールへの添付データはdidit_internal_idを用いた組織/アプリケーションのパスを使用します。このページでは概念的な流れを説明します。リクエストとレスポンスの完全なスキーマはAPIリファレンスを参照してください。

ユーザーの一覧取得

GET /v3/users/ アプリケーションのユーザーをページネーションされた一覧で返します。ステータス、検索、日付範囲などのフィルターに対応しています。

curl -G https://verification.didit.me/v3/users/ \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "status=ACTIVE" \
  --data-urlencode "search=jane" \
  --data-urlencode "page_size=50"

ユースケース:

ユーザーの一部を毎日データウェアハウスに同期する。
アナリストのキュー向けにフラグ付きユーザーを抽出する。
表示名でユーザーを検索する。

ユーザーの取得

GET /v3/users/{vendor_data}/ vendor_dataを指定して1人のユーザーを取得します。集計カウンターを含む完全なデータモデルを返します。

curl https://verification.didit.me/v3/users/user-42/ \
  -H "x-api-key: YOUR_API_KEY"

URL内のvendor_dataは大文字と小文字を区別します。必ずセッション作成時に使用した値をそのまま渡してください。

ユーザーの作成

POST /v3/users/create/ セッションが開始される前にユーザーエンティティを作成します。次の用途に役立ちます。

顧客が認証を行う前に、メタデータやカスタムフィールドを設定しておく。
初期ステータスを設定する(例: オンボーディングチームが手動で書類を確認している間はFLAGGEDにする)。
既存のデータベースからユーザーを事前に読み込み、初日から完全な名簿を用意する。

curl -X POST https://verification.didit.me/v3/users/create/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data": "user-42",
    "display_name": "Jane Doe",
    "metadata": { "tier": "premium", "signup_source": "web" }
  }'

そのvendor_dataを持つユーザーがすでに存在する場合、この呼び出しは競合エラーを返します。代わりにPATCHで更新してください。連絡先情報も送信できます: first_nameとlast_name(氏名を送信しない場合は連結されてfull_nameになります)、email、phone_number、countryです。 Diditはemailとphone_numberをmetadata.contactに、countryをmetadata.addressに保存します。同じ呼び出しで本人に認証を依頼するには、emailとworkflow_idとともにsend_verification_link: trueを追加します。 Diditはそのワークフローで本人用の検証セッションを作成し、リンクをメールで送信します。レスポンスのverification_linkには、セッションのsession_id、session_number、status、url、workflow_id、emailが含まれます。リンクを要求しない場合はnullになります。チェック内容とエラーについてはCreate Userを参照してください。

インポートした顔画像のアップロード

POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/ 既存のユーザープロフィールに信頼済みの顔画像を添付します。他のプロバイダーからユーザーをインポートし、Diditでの最初のセッションより前にDiditでその顔画像の証跡を保持したい場合に、次に行う操作として適しています。

# First create or retrieve the User and read didit_internal_id from the response.
curl -X POST https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/$DIDIT_INTERNAL_ID/faces/upload/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "<base64-encoded-jpg-or-png>",
    "comment": "Imported from previous KYC provider"
  }'

リクエストフィールド、制限、一覧取得/削除のエンドポイント、ブロックリストとの違いについてはUpload User Faceを参照してください。

ユーザーの更新

PATCH /v3/users/{vendor_data}/ 変更可能なプロフィールフィールドを更新します。検証済みセッションから導出されたフィールドの大半は読み取り専用で、PATCHで変更しようとすると無視されるか、監査ログにフラグが付けられます。 変更可能なフィールド: display_name、metadata、tags。 検証後は読み取り専用: full_name、date_of_birth、portrait_image、すべての集計カウンター、featuresマップ。

curl -X PATCH https://verification.didit.me/v3/users/user-42/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "tier": "enterprise" } }'

changed_fields配列を含むuser.data.updated Webhookイベントを送信します。

ステータスの変更

PATCH /v3/users/{vendor_data}/update-status/ ユーザーのステータスをACTIVE、FLAGGED、BLOCKEDの間で切り替えます。ステータスの変更は、以降のセッションと取引に反映されます。

curl -X PATCH https://verification.didit.me/v3/users/user-42/update-status/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "BLOCKED",
    "reason": "Chargeback fraud pattern detected"
  }'

変更前 → 変更後	主なトリガー
`ACTIVE` → `FLAGGED`	取引ルール、アナリストによるレビュー、継続的なAMLモニタリングでのヒット
`ACTIVE` → `BLOCKED`	不正の確定、自動ブロックを伴うセッションの却下、ブロックリストとの一致
`FLAGGED` → `ACTIVE`	アナリストがレビューを解除
`BLOCKED` → `ACTIVE`	アナリストによる手動のブロック解除

user.status.updated Webhookを送信します。

ユーザーの削除(一括)

POST /v3/users/delete/ 1人以上のユーザーを削除します。ユーザーレコードは、セッション削除後に保持されていたすべての生体認証テンプレートとともに完全に削除されます。ユーザーの検証セッションはこのエンドポイントの対象外で、ユーザーとの紐付けが解除された状態で残ります。これらはDelete SessionまたはBatch Delete Sessionsで削除してください。取引も対象外のため、コンソールから削除してください。

curl -X POST https://verification.didit.me/v3/users/delete/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data_list": ["user-42", "user-43", "user-44"]
  }'

ユーザーはvendor_data_list、didit_internal_id_list、またはその両方で指定します。または、delete_all: trueを渡すとアプリケーション内のすべてのユーザーを削除します。コンソールのfilter_* 一括パラメーターは、ここでは無視されずに400で拒否されます。そのため、対象を絞り込んだつもりの操作が全件削除になることはありません。レスポンスは項目ごとの結果ではなく、件数{"deleted": <int>}を返します。一致しなかった識別子は通知なくスキップされるため、deletedと送信した識別子の数を比較したい場合は、重複を除いたリストを送信してください。

権限モデル

APIキーは1つのアプリケーションに属します。プライマリーシークレットとフルアクセスキーは、そのアプリケーションのすべての/v3/users/*エンドポイントを呼び出せます(deleteを含む)。スコープ付きAPIキーにはユーザー(users)のアクセス権が必要です。GETエンドポイントには読み取り権限、作成、更新、ステータス変更、削除には書き込み権限が必要です。 send_verification_link: trueを指定してユーザーを作成する場合は、セッションを作成してそのリンクをメールで送信するため、Sessionsの書き込み権限も必要です。必要なアクセス権を持たないキーは403を返します。一部のワークフローや承認済みセッションに限定されたキーは、/v3/users/*エンドポイントに一切アクセスできません。役割はコンソールの概念です。users権限リソースとそのクレームは、チームメンバーがコンソールで何をできるかを決めるもので、APIキーによるリクエストでは評価されません。その一覧表については役割と権限を参照してください。サービスにユーザーを削除させないようにするには、ユーザーの読み取り権限のみを持つキー、またはユーザーのアクセス権を持たないキーを付与してください。

レート制限と冪等性

すべての/v3/users/*エンドポイントには、標準のレート制限が適用されます。
createは冪等ではありません。同じvendor_dataで再試行すると競合エラーが返ります。自社側で重複を排除するか、常に先にGETを実行してください。
deleteは冪等です。すでに削除されたユーザーを削除しても何も行われません。

これらの操作で送信されるWebhook

操作	Webhook
`create`	作成APIの呼び出し自体では送信されません。最初の`user.data.updated`は、セッションまたは更新によってプロフィールに初めてデータが入力された時点で届きます
`update`	`user.data.updated`(`changed_fields`付き)
`update-status`	`user.status.updated`
`delete`	なし。削除に応じて処理を行う必要がある場合は、自社側で削除を記録してください

次のステップ

データモデル

フィールドの完全なリファレンス。

一覧取得API

GET /v3/users/のスキーマ。

作成API

POST /v3/users/create/のスキーマ。

顔のアップロード

インポートした顔画像をユーザープロフィールに紐付けます。

概要

料金

ワークフローと検証

レビューと運用

エンティティ（ユーザーと法人）

設定とカスタマイズ

セキュリティとコンプライアンス

Didit Academy

リソース

ユーザー操作API：ベンダーユーザーのCRUD

ユーザーの一覧取得

ユーザーの取得

ユーザーの作成

インポートした顔画像のアップロード

ユーザーの更新

ステータスの変更

ユーザーの削除(一括)

権限モデル

レート制限と冪等性

これらの操作で送信されるWebhook

次のステップ

データモデル

一覧取得API

作成API

顔のアップロード

​ユーザーの一覧取得

​ユーザーの取得

​ユーザーの作成

​インポートした顔画像のアップロード

​ユーザーの更新

​ステータスの変更

​ユーザーの削除(一括)

​権限モデル

​レート制限と冪等性

​これらの操作で送信されるWebhook

​次のステップ

データモデル

一覧取得API

作成API

顔のアップロード

ユーザーの一覧取得

ユーザーの取得

ユーザーの作成

インポートした顔画像のアップロード

ユーザーの更新

ステータスの変更

ユーザーの削除(一括)

権限モデル

レート制限と冪等性

これらの操作で送信されるWebhook

次のステップ