> ## 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：供应商用户增删改查

> 通过 Didit 管理 API（Management API）创建、读取、更新、变更状态和删除 Didit 供应商用户实体。按量付费，无需签约。



用户操作提示
        将提示词复制到剪贴板



      
      

\<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/` 下的公开 endpoint 完成。个人资料附件（例如导入的人脸上传）使用组织/应用路径并传入 `didit_internal_id`。本页提供概念性讲解，完整的请求与响应结构请参见 [API 参考](https://docs.didit.me/zh/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` 获取单个用户。返回完整的[数据模型](https://docs.didit.me/zh/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` 中。要在同一次调用中邀请对方进行验证，请添加 `send_verification_link: true`，并提供 `email` 和 `workflow_id`。
Didit 会为该用户在此工作流上创建验证会话，并通过邮件发送链接。
响应中的 `verification_link` 包含会话的 `session_id`、`session_number`、`status`、`url`、`workflow_id` 和 `email`；未请求链接时为 `null`。
检查项与错误说明请参见 [创建用户](https://docs.didit.me/zh/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"
  }'
```请求字段、限制、列表与删除 endpoint，以及黑名单的区别，请参见 [上传用户人脸](https://docs.didit.me/zh/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/`**删除一个或多个用户。用户记录将被永久删除，同时删除其会话后为其保留的所有[生物特征模板](https://docs.didit.me/zh/management-api/biometric-templates/overview.md)也会被永久删除。此 endpoint 不涵盖其验证会话：这些会话会保留，但与用户的关联将被清除；请使用 [删除会话](https://docs.didit.me/zh/sessions-api/delete-session.md) 或 [批量删除会话](https://docs.didit.me/zh/management-api/sessions/batch-delete.md) 删除它们。交易同样不在此 endpoint 的范围内，请在控制台中删除。```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 密钥属于一个应用。
主密钥和全访问权限密钥可以调用该应用的每个 `/v3/users/*` endpoint，包括 `delete`。[范围受限的 API 密钥](https://docs.didit.me/zh/console/api-keys.md)需要 **People**（`users`）访问权限：`GET` endpoint 需要读取权限，创建、更新、变更状态和删除需要写入权限。
使用 `send_verification_link: true` 创建用户还需要 **会话** 写入权限，因为它会创建会话并发送其链接。
缺少所需访问权限的密钥会返回 `403`。仅限部分工作流或已批准会话的密钥完全无法访问 `/v3/users/*` endpoint。角色是控制台的概念：`users` 权限资源及其声明决定团队成员在控制台中能做什么，对 API 密钥请求则不作评估。角色矩阵请参见 [角色与权限](https://docs.didit.me/zh/console/roles-permissions.md)。要防止某个服务删除用户，请为其分配仅具有 **People** 读取权限的密钥，或完全不具有 **People** 访问权限的密钥。## 速率限制与幂等性- 所有 `/v3/users/*` endpoint 均受标准[速率限制](https://docs.didit.me/zh/integration/rate-limiting.md)约束。
- `create` **不是**幂等的：使用相同 `vendor_data` 重试会返回冲突。请在你的系统中去重，或始终先执行 `GET`。
- `delete` 是幂等的：删除已删除的用户不会产生任何效果。## 这些操作触发的 Webhook| 操作 | Webhook |
| - | - |
| `create` | create 调用本身不触发 Webhook；首次 `user.data.updated` 会在会话或更新首次填充资料时到达 |
| `update` | `user.data.updated`（包含 `changed_fields`） |
| `update-status` | `user.status.updated` |
| `delete` | 无。如需对删除作出响应，请在您自己的系统中记录该删除操作 |## 后续步骤> [card] [数据模型](https://docs.didit.me/zh/entities/users/data-model.md)
>
> 完整的字段参考。> [card] [列表 API](https://docs.didit.me/zh/management-api/users/list.md)
>
> GET /v3/users/ 的架构。> [card] [创建 API](https://docs.didit.me/zh/management-api/users/create.md)
>
> POST /v3/users/create/ 的架构。> [card] [上传人脸](https://docs.didit.me/zh/management-api/users/upload-face.md)
>
> 为用户资料附加导入的人脸图像。


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