> ## 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.

# 用户导入导出：CSV 批量操作

> 通过 CSV 批量导入 Didit 供应商用户实体，并导出完整用户表，供外部合规工具使用。可从 Didit 企业控制台访问此功能。



批量导入/导出用户提示
        将提示词复制到剪贴板



      
      

\<pre>

\````# Goal — bulk-load (or extract) Didit User entities programmatically

CSV import / export is a console-only UI feature. For programmatic bulk operations, loop `POST /v3/users/create/` for imports, optionally upload trusted profile faces with `POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/`, and paginate `GET /v3/users/` for exports. There is no public CSV API endpoint.

\## Bulk import — loop the create endpoint

\```bash
\# users.json — array of records you want to seed into Didit
\# [{"vendor_data":"user-1","display_name":"Alice"}, ...]

jq -c '.[]' users.json | while read user; do
curl -X POST https://verification.didit.me/v3/users/create/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d "$user"
sleep 0.1   # respect rate limits — see /integration/rate-limiting
done
\```

Record shape (matches `POST /v3/users/create/`):

\```json
\{
"vendor_data": "user-42",          // required, unique per app
"display_name": "Jane Doe",        // optional
"metadata": {"tier": "premium"},   // free-form JSON
"tags": ["promo-2026"]             // optional array of strings
}
\```

\`create` is **not** idempotent — a duplicate `vendor_data` returns conflict. Branch on existence:

\```bash
\# Idempotent upsert pattern
if curl -s -o /dev/null -w "%{http_code}" \
 https://verification.didit.me/v3/users/$VD/ \
 -H "x-api-key: $DIDIT_API_KEY" | grep -q 200; then
curl -X PATCH https://verification.didit.me/v3/users/$VD/ \
-H "x-api-key: $DIDIT_API_KEY" -H "Content-Type: application/json" \
-d "$BODY"
else
curl -X POST https://verification.didit.me/v3/users/create/ \
-H "x-api-key: $DIDIT_API_KEY" -H "Content-Type: application/json" \
-d "$BODY"
fi
\```

\## Import faces from another provider

If each imported user has a trusted face image, upload it after the User exists:

\```bash
\# GET /v3/users/{vendor_data}/ or POST /v3/users/create/ first.
\# Use the returned didit_internal_id for the profile attachment endpoint.
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 stores the face on the User profile and enrolls it for duplicate detection and face search. It does not blocklist the face; use /management-api/lists/upload-face for blocklists.

\## Bulk export — paginate the list endpoint

\```bash
PAGE=1
while :; do
RESP=$(curl -sG https://verification.didit.me/v3/users/ \
-H "x-api-key: $DIDIT_API_KEY" \
\--data-urlencode "page=$PAGE" \
\--data-urlencode "page_size=100")
echo "$RESP" | jq -c '.results[]' >> users.ndjson
HAS_NEXT=$(echo "$RESP" | jq -r '.next // empty')
\[ -z "$HAS_NEXT" ] && break
PAGE=$((PAGE+1))
done
\```

Filter with the same query params as `GET /v3/users/` (`status`, `search`, date ranges, etc).

\## What survives on update vs what stays

\| Field | Behaviour |
\|---|---|
\| `display_name`, `metadata`, `tags` | Overwritten by PATCH |
\| `full_name`, `date_of_birth`, `portrait_image` | Read-only after a verified session (you can override via PATCH but it's logged as a manual override) |
\| Aggregate counters (`session_count`, `approved_count`, etc.) | Computed by Didit — never accept writes |
\| `features` map | Computed — never accept writes |

\## Failure modes

\- `409` on create — `vendor_data` exists; switch to PATCH.
\- `429` — rate limit; back off using `Retry-After`. Don't slam the API; insert 100ms+ between calls.
\- `400` — bad JSON or invalid country/status enum. Log the row and continue.
\- Partial failures: track `vendor_data` → status per row and retry only failures.

\## Console fallback

For one-off migrations bigger than 100K rows, the Business Console CSV import/export (Users → Import / Export) is fast and skips writing your own loop. The console runs the same validations and produces an error report.

\## Sources of truth

\- /management-api/users/create — POST /v3/users/create/ schema
\- /management-api/users/list — GET /v3/users/ pagination + filters
\- /entities/users/data-model — mutable vs read-only fields
\- /integration/rate-limiting — rate limits and Retry-After
\- /integration/integration-prompt — canonical end-to-end prompt````

\</pre>



      
      

粘贴到

Business Console 让您的团队无需编写代码即可批量管理用户实体。支持两种流程：**CSV 导入**（批量创建或更新用户）和 **CSV 导出**（提取用户表供外部工具使用）。> [!NOTE]
>
> 此处的批量导入/导出仅创建或更新用户档案。它不会重建历史 KYC 会话、证件警告、活体证据或服务商决策。如需从 Sumsub、MetaMap、Veriff、Onfido、Persona 或其他服务商完整迁移，请参阅[从其他服务商导入数据](https://docs.didit.me/zh/sessions-api/import-verifications.md)。## 从 CSV 导入用户### 适用场景- **首日迁移**：从其他 KYC 供应商迁移，导入您现有的用户名单。
- **服务商人脸迁移**：在行创建后，将可信人脸图像关联到已导入的用户档案。
- **批量入驻**：导入合作伙伴的客户名单。
- **元数据回填**：批量更新大量用户的标签、等级或内部标识符。### 模板列在 *Users → Import → Download template* 下载模板。列如下：| 列 | 必填 | 说明 |
| - | - | - |
| `vendor_data` | 是 | 您为该用户设置的标识符。在同一应用内必须唯一。 |
| `display_name` | 否 | 在控制台中显示的可读名称。 |
| `full_name` | 否 | 法定姓名。将被已验证的会话数据覆盖。 |
| `email` | 否 | 已知的联系邮箱。 |
| `phone` | 否 | 已知的联系电话（E.164 格式）。 |
| `country` | 否 | ISO 3166-1 alpha-3 国家/地区代码。 |
| `status` | 否 | `ACTIVE`、`FLAGGED` 或 `BLOCKED`。默认为 `ACTIVE`。 |
| `tags` | 否 | 以逗号分隔的标签。 |
| `metadata_json` | 否 | 自定义元数据的 JSON 字符串。 |### 运行导入**1. 上传 CSV**进入 *Users → Import → Upload CSV*，选择您的文件。**2. 查看预览**控制台会逐行验证。无效行会高亮显示，并附带错误原因（例如 `vendor_data` 重复、国家代码无效）。**3. 开始导入**Didit 异步处理各行。您可以关闭标签页，进度可在 *Users → Import history* 中查看。**4. 查看结果**导入完成后，历史视图会显示已创建、已更新和已跳过的行数，并提供可下载的错误报告。### 更新与创建- 如果某个 `vendor_data` 不存在，则创建新用户。
- 如果某个 `vendor_data` 已存在，则该行会更新现有用户（档案字段和元数据）。
- 汇总计数器和已验证字段（来自已通过会话的 `full_name`、`date_of_birth`）**绝不会被导入覆盖**。### 用户创建后导入人脸CSV 导入只会创建或更新用户行，CSV 中不包含人脸图像。如需从其他服务商迁移人脸生物特征，请在目标用户存在后逐个上传人脸：**1. 创建或导入用户**使用控制台 CSV 导入，或循环调用 [`POST /v3/users/create/`](https://docs.didit.me/zh/management-api/users/create)。**2. 读取 didit\_internal\_id**使用 [`GET /v3/users/{vendor_data}/`](https://docs.didit.me/zh/management-api/users/get) 获取用户。响应中包含 `didit_internal_id`。**3. 上传人脸**使用原始 base64 人脸图像调用 [`POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/`](https://docs.didit.me/zh/management-api/users/upload-face)。```bash theme={null}
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"
  }'
```人脸必须是有效图像，解码后最大 2 MB，并且包含可检测到的人脸。Didit 会将其存储在用户档案中，并建立索引，用于重复检测和人脸搜索。除非您另外使用 [上传人脸到名单](https://docs.didit.me/zh/management-api/lists/upload-face.md) endpoint，否则它不会被添加到人脸黑名单。## 将用户导出为 CSV### 适用场景- **合规审计**：向审计人员交付完整用户表。
- **数据仓库同步**：定期导出到您的商业智能（BI）工具。
- **SAR 或监管机构请求**：提取筛选后的用户子集。### 运行导出1. 进入 *Users → Export*。
2. 应用筛选条件（状态、国家/地区、日期范围、搜索）。
3. 选择列（默认包含所有字段；您可以去掉不需要的列）。
4. 提交。Didit 异步生成导出文件，并将带签名的下载链接发送到发起请求的操作员邮箱。> [!NOTE]
>
> 导出仅包含您的角色有权读取的数据。COMPLIANCE\_OFFICER 及更高角色可以导出完整用户表；DEVELOPER 和 READER 角色的导出受到限制。## 性能特征| 操作 | 典型规模 | 说明 |
| - | - | - |
| 导入 | 最多 100,000 行 | 较大的文件会在服务端分块处理；界面会轮询进度 |
| 导出 | 最多 1,000,000 行 | 较大的导出会流式写入 S3，并通过带签名的 URL 交付 |## 审计追踪每次导入和导出都会记录在[审计日志](https://docs.didit.me/zh/console/audit-logs.md)中：- 触发该操作的操作员。
- 行数（导入）或筛选条件快照（导出）。
- 时间戳以及成功或失败状态。## 后续步骤> [card] [创建用户 API](https://docs.didit.me/zh/management-api/users/create.md)
>
> 用于脚本化导入的程序化创建。> [card] [上传用户人脸](https://docs.didit.me/zh/management-api/users/upload-face.md)
>
> 将导入的人脸图像关联到用户档案。> [card] [数据保留](https://docs.didit.me/zh/console/data-retention.md)
>
> 导入的数据保存多长时间。> [card] [审计日志](https://docs.didit.me/zh/console/audit-logs.md)
>
> 查看导入和导出历史。


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