> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

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

> DiditのManagement APIで、ベンダーのユーザーエンティティを作成、取得、更新、ステータス変更、削除できます。従量課金制で契約は不要です。



ユーザー操作のプロンプト
        プロンプトをクリップボードにコピー



      
      

\<pre>

\````# Goal — full CRUD over Didit User entities

Core CRUD operations sit under `https://verification.didit.me/v3/users/` authenticated with `x-api-key: $DIDIT_API_KEY`. Profile attachment endpoints use the organization/application path and the User's `didit_internal_id`. Each User is keyed by `vendor_data` (case-sensitive, unique per application).

\## Endpoint catalog

\| Action | Method + path |
\|---|---|
\| List users | `GET /v3/users/` |
\| Get one user | `GET /v3/users/{vendor_data}/` |
\| Create user | `POST /v3/users/create/` |
\| Upload profile face | `POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/` |
\| Update profile | `PATCH /v3/users/{vendor_data}/` |
\| Change status | `PATCH /v3/users/{vendor_data}/update-status/` |
\| Batch delete | `POST /v3/users/delete/` |

\## List (with filters)

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

\## Get one user

\```bash
curl https://verification.didit.me/v3/users/user-42/ \
-H "x-api-key: $DIDIT_API_KEY"
\```

\## Create

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

Not idempotent — retrying with the same `vendor_data` returns conflict. `GET` first or PATCH instead.

\## Upload an imported profile face

\```bash
\# First read didit_internal_id from GET /v3/users/{vendor_data}/
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: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"image": "<base64-encoded-jpg-or-png>", "comment": "Imported from previous KYC provider"}'
\```

This attaches a trusted face image to the User profile and enrolls it for duplicate detection and face search. It does not add the face to a blocklist.

\## Update profile

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

Mutable: `display_name`, `metadata`, `tags`. Read-only (verified): `full_name`, `date_of_birth`, `portrait_image`, all aggregate counters, `features` map.

\## Change status

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

Valid statuses: `ACTIVE`, `FLAGGED`, `BLOCKED`. `BLOCKED` users have new sessions auto-declined.

\## Batch delete

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

Idempotent — already-deleted is a no-op. Returns a count, `{"deleted": <int>}`, not a per-item result. The user records and every biometric template retained for them are removed permanently. Verification sessions are not covered by this endpoint; delete those with the session delete endpoints.

\## Webhooks fired

\| Operation | Event |
\|---|---|
\| create | none for the create call itself — the first `user.data.updated` arrives when a session or a PATCH first fills the profile |
\| update (PATCH) | `user.data.updated` with `changed_fields` |
\| update-status | `user.status.updated` |
\| delete | none — record the deletion on your own side if you need to react to it |

\## Failure modes

\- `401` — missing / invalid `x-api-key`.
\- `403` — the API key is not valid for this application.
\- `409` on create — `vendor_data` already exists; switch to PATCH.
\- `404` — no entity for that `vendor_data` (case-sensitive!).
\- `429` — rate-limited; back off using `Retry-After`.

\## Response shape

See /reference/data-models and /entities/users/data-model for the full User schema.

\## Sources of truth

\- /management-api/users/list, /management-api/users/get, /management-api/users/create — per-endpoint reference
\- /entities/users/data-model — field-by-field schema
\- /entities/webhooks — entity event payloads
\- /integration/integration-prompt — canonical end-to-end prompt````

\</pre>



      
      

貼り付け先

ユーザーエンティティの基本的な管理は、`/v3/users/`配下の公開エンドポイントで行います。インポートした顔画像のアップロードなど、プロフィールへの添付データは`didit_internal_id`を用いた組織/アプリケーションのパスを使用します。このページでは概念的な流れを説明します。リクエストとレスポンスの完全なスキーマは[APIリファレンス](https://docs.didit.me/ja/management-api/users/list.md)を参照してください。## ユーザーの一覧取得**`GET /v3/users/`**アプリケーションのユーザーをページネーションされた一覧で返します。ステータス、検索、日付範囲などのフィルターに対応しています。```bash theme={null}
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人のユーザーを取得します。集計カウンターを含む完全な[データモデル](https://docs.didit.me/ja/entities/users/data-model.md)を返します。```bash theme={null}
curl https://verification.didit.me/v3/users/user-42/ \
  -H "x-api-key: YOUR_API_KEY"
```> [!NOTE]
>
> URL内の`vendor_data`は大文字と小文字を区別します。必ずセッション作成時に使用した値をそのまま渡してください。## ユーザーの作成**`POST /v3/users/create/`**セッションが開始される前にユーザーエンティティを作成します。次の用途に役立ちます。- 顧客が認証を行う前に、メタデータやカスタムフィールドを設定しておく。
- 初期ステータスを設定する(例: オンボーディングチームが手動で書類を確認している間は`FLAGGED`にする)。
- 既存のデータベースからユーザーを事前に読み込み、初日から完全な名簿を用意する。```bash theme={null}
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](https://docs.didit.me/ja/management-api/users/create.md#認証リンクを送信する)を参照してください。## インポートした顔画像のアップロード**`POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/`**既存のユーザープロフィールに信頼済みの顔画像を添付します。他のプロバイダーからユーザーをインポートし、Diditでの最初のセッションより前にDiditでその顔画像の証跡を保持したい場合に、次に行う操作として適しています。```bash theme={null}
# 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](https://docs.didit.me/ja/management-api/users/upload-face.md)を参照してください。## ユーザーの更新**`PATCH /v3/users/{vendor_data}/`**変更可能なプロフィールフィールドを更新します。検証済みセッションから導出されたフィールドの大半は読み取り専用で、PATCHで変更しようとすると無視されるか、監査ログにフラグが付けられます。**変更可能なフィールド:** `display_name`、`metadata`、`tags`。
**検証後は読み取り専用:** `full_name`、`date_of_birth`、`portrait_image`、すべての集計カウンター、`features`マップ。```bash theme={null}
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`の間で切り替えます。ステータスの変更は、以降のセッションと取引に反映されます。```bash theme={null}
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人以上のユーザーを削除します。ユーザーレコードは、セッション削除後に保持されていたすべての[生体認証テンプレート](https://docs.didit.me/ja/management-api/biometric-templates/overview.md)とともに完全に削除されます。ユーザーの検証セッションはこのエンドポイントの対象外で、ユーザーとの紐付けが解除された状態で残ります。これらは[Delete Session](https://docs.didit.me/ja/sessions-api/delete-session.md)または[Batch Delete Sessions](https://docs.didit.me/ja/management-api/sessions/batch-delete.md)で削除してください。取引も対象外のため、コンソールから削除してください。```bash theme={null}
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キー](https://docs.didit.me/ja/console/api-keys.md)には**ユーザー**(`users`)のアクセス権が必要です。`GET`エンドポイントには読み取り権限、作成、更新、ステータス変更、削除には書き込み権限が必要です。
`send_verification_link: true`を指定してユーザーを作成する場合は、セッションを作成してそのリンクをメールで送信するため、**Sessions**の書き込み権限も必要です。
必要なアクセス権を持たないキーは`403`を返します。
一部のワークフローや承認済みセッションに限定されたキーは、`/v3/users/*`エンドポイントに一切アクセスできません。役割はコンソールの概念です。`users`権限リソースとそのクレームは、チームメンバーがコンソールで何をできるかを決めるもので、APIキーによるリクエストでは評価されません。
その一覧表については[役割と権限](https://docs.didit.me/ja/console/roles-permissions.md)を参照してください。サービスにユーザーを削除させないようにするには、**ユーザー**の読み取り権限のみを持つキー、または**ユーザー**のアクセス権を持たないキーを付与してください。## レート制限と冪等性- すべての`/v3/users/*`エンドポイントには、標準の[レート制限](https://docs.didit.me/ja/integration/rate-limiting.md)が適用されます。
- `create`は冪等では**ありません**。同じ`vendor_data`で再試行すると競合エラーが返ります。自社側で重複を排除するか、常に先に`GET`を実行してください。
- `delete`は冪等です。すでに削除されたユーザーを削除しても何も行われません。## これらの操作で送信されるWebhook| 操作 | Webhook |
| - | - |
| `create` | 作成APIの呼び出し自体では送信されません。最初の`user.data.updated`は、セッションまたは更新によってプロフィールに初めてデータが入力された時点で届きます |
| `update` | `user.data.updated`(`changed_fields`付き) |
| `update-status` | `user.status.updated` |
| `delete` | なし。削除に応じて処理を行う必要がある場合は、自社側で削除を記録してください |## 次のステップ> [card] [データモデル](https://docs.didit.me/ja/entities/users/data-model.md)
>
> フィールドの完全なリファレンス。> [card] [一覧取得API](https://docs.didit.me/ja/management-api/users/list.md)
>
> GET /v3/users/のスキーマ。> [card] [作成API](https://docs.didit.me/ja/management-api/users/create.md)
>
> POST /v3/users/create/のスキーマ。> [card] [顔のアップロード](https://docs.didit.me/ja/management-api/users/upload-face.md)
>
> インポートした顔画像をユーザープロフィールに紐付けます。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.