> ## 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：供应商用户实体 > 在 KYC 会话运行前，预先创建 Didit 供应商用户实体。可从外部数据库批量导入用户，或为交易监控注册用户。 创建用户提示 将提示词复制到剪贴板 \

\`Goal: Pre-create a Didit User entity by vendor_data before any verification session runs, and optionally email the person a verification link in the same call.

Endpoint: POST https://verification.didit.me/v3/users/create/
Auth header: x-api-key: 
Content-Type: application/json

Request body fields:
\- vendor_data (string, REQUIRED) — your unique identifier for this user. Free-form string, NOT a UUID. Must be unique among non-deleted users in the app. Normalised lowercase + whitespace trim, so "USER-1" and "user-1" collide. Max 2000 bytes (UTF-8 encoded); longer values return a 400.
\- full_name (string, max 512, optional)
\- display_name (string, optional) — friendly label for the Console (takes precedence over full_name for UI).
\- date_of_birth (string YYYY-MM-DD, optional)
\- status (enum, optional) — "ACTIVE" | "FLAGGED" | "BLOCKED" (VendorUserStatusChoices). Defaults to "ACTIVE".
\- metadata (object, optional) — arbitrary JSON you attach to the user.
\- approved_emails (object, optional) — e.g. {"john@example.com": true}.
\- approved_phones (object, optional).
\- issuing_states (object, optional) — e.g. {"USA": 1}.

Contact fields (all optional):
\- first_name, last_name (string, max 255 each): joined with a space into full_name when you don't send full_name.
\- email (string, email): stored in metadata.contact.email.
\- phone_number (string, max 32): stored in metadata.contact.phone_number.
\- country (string): ISO 3166 code, alpha-2 or alpha-3 ("ES" or "ESP"), stored uppercased in metadata.address.country.

Verification link (optional):
\- send_verification_link (boolean, default false): when true, Didit also creates a verification session for the person on workflow_id and emails them the link at email.
\- workflow_id (UUID): REQUIRED with send_verification_link. The workflow must verify a person: a Business Verification (KYB) workflow is refused.
\- language (string, max 10): language of the verification email, a supported language code. English when omitted.
\- The person and the session are created together or not at all. The session runs the same checks as POST /v3/session/ (blocklist, credits).

curl:
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-abc-123", "full_name": "John Doe"}'

curl with a verification link:
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-abc-789", "first_name": "Julia", "last_name": "Martin", "email": "julia.martin@example.com", "send_verification_link": true, "workflow_id": "YOUR_WORKFLOW_ID"}'

Response 201: full UserDetailItem (same shape as GET /v3/users/{vendor_data}/) plus verification_link. Includes didit_internal_id (UUID), session_count, approved_count=0, metadata, comments=[], created_at, updated_at. See /reference/data-models.
\- verification_link is always present: null without a link, otherwise { session_id, session_number, status, url, workflow_id, email }. url is the link Didit emailed.

Failure modes:
\- 400: nothing is written. Most errors are keyed by field. Common cases:
\{ "vendor_data": ["A user with this vendor_data already exists."] }  // conflict, NOT idempotent. Use PATCH /v3/users/{vendor_data}/ to update.
\{ "vendor_data": ["This field is required."] }
\{ "vendor_data": ["Ensure this field has no more than 2000 characters."] }  // oversized vendor_data, rejected before it reaches storage
\{ "metadata": ["Metadata must be a JSON object."] }
\{ "country": ["Use an ISO 3166 country code, like ES or ESP."] }
\{ "email": ["metadata.contact must be a JSON object to store this value."] }  // same on phone_number; metadata.address on country
\{ "email": ["An email address is required to send a verification link."] }
\{ "workflow_id": ["Pick the workflow to send a verification link for."] }
\{ "workflow_id": ["Invalid workflow_id."] }
\{ "workflow_id": ["This workflow verifies a business. Pick a workflow that verifies a person to send them a verification link."] }
\{ "contact_details": { "email_lang": ["Invalid email language. Supported languages are ..."] } }  // unsupported language
\{ "vendor_data": "This user or business has been blocked and cannot create new verification sessions." }
\{ "detail": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" }
\- 401: missing or invalid x-api-key. { "detail": "Authentication credentials were not provided." }
\- 403: the API key is revoked or is not valid for this application. { "detail": "You do not have permission to perform this action." }
\- 403: a scoped key without users write. { "detail": "This API key has no write access to people." }
\- 403: send_verification_link with a scoped key that lacks sessions write. Nothing is written. { "detail": "This API key has no write access to sessions." }
\- 429: rate-limited.

Upsert pattern (this endpoint is NOT idempotent):
GET /v3/users/{vendor_data}/  → on 404, POST /v3/users/create/; on 200, PATCH /v3/users/{vendor_data}/.

Notes:
\- Verified-session-derived identity fields such as full_name and date_of_birth seeded here can be overwritten by the first approved User Verification (KYC) session.
\- If you are migrating from another provider and already have a trusted face image, create the User first, read didit_internal_id from this response, then call POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/.
\- The create itself sends no webhook. Later changes to the user send user.data.updated or user.status.updated. With send_verification_link, the new session updates the user (session_count) in the same call, which sends user.data.updated.
\- API key access: a scoped key needs users write; with send_verification_link it also needs sessions write. Full-access keys can always call it.

For end-to-end Didit integration, paste in the full prompt at /integration/integration-prompt.`

\
粘贴到 ## 概述在运行任何会话之前，显式创建一个[用户实体](https://docs.didit.me/zh/entities/users/overview.md)。 除非另行指定，返回的实体状态为 `ACTIVE`。 您还可以选择在同一次调用中向用户发送验证链接（参见[发送验证链接](#发送验证链接)）。## 适用场景- **预先填充元数据**（等级、注册来源、内部标签），在客户开始验证之前完成。 - **从其他供应商迁移**：在 Didit 中重新创建现有用户名单，使历史数据和分析从已知基线开始。 - **导入可信的用户人脸**：先创建用户，然后使用返回的 `didit_internal_id` 调用[上传用户人脸](https://docs.didit.me/zh/management-api/users/upload-face.md)。 - **仅交易场景**：使用 `vendor_data` 注册用户，无需运行用户验证（KYC）会话即可提交交易。 - **邀请他人验证**：一次调用即可创建用户并通过邮件发送验证链接。## 联系方式您可以在用户资料字段旁一并提供用户的联系方式。 未发送 `full_name` 时，`first_name` 和 `last_name` 之间以空格连接，组成 `full_name`。 `email` 和 `phone_number` 存储在 `metadata.contact` 中，`country` 存储在 `metadata.address` 中。 `country` 接受 alpha-2 或 alpha-3 格式的 ISO 3166 代码（如 `ES` 或 `ESP`），并以大写形式存储。如果您发送的 `metadata` 中，`contact` 或 `address` 已有非 JSON 对象的值，Didit 不会覆盖该值：调用会针对需要写入的那个字段返回 `400`。## 发送验证链接将 `send_verification_link` 设为 `true`，即可在同一次调用中邀请用户进行验证。 Didit 会基于 `workflow_id` 中的工作流为该用户创建验证会话，并将链接发送至 `email`。 使用 `language` 选择邮件的[语言](https://docs.didit.me/zh/integration/supported-languages.md)；省略时默认为英语。```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-abc-789", "first_name": "Julia", "last_name": "Martin", "email": "julia.martin@example.com", "send_verification_link": true, "workflow_id": "YOUR_WORKFLOW_ID", "language": "es" }' ```- 使用链接时必须提供 `email` 和 `workflow_id`，且该工作流必须用于验证个人：企业验证（KYB）工作流会返回 `400`。 - 会话会经过与[创建会话](https://docs.didit.me/zh/sessions-api/create-session.md)相同的检查。 `vendor_data` 位于黑名单中或额度不足时，都会返回 `400`。 - 用户和会话要么同时创建，要么都不创建。 任一检查失败时，不写入任何数据，也不发送邮件。 - 响应中包含 `verification_link`，其中有会话的 `session_id`、`session_number`、`status`、`url`、`workflow_id`，以及链接发送到的 `email`。 未发送链接时，`verification_link` 为 `null`。## 注意事项- `vendor_data` 为必填项，且在每个应用内必须唯一。尝试创建重复项会返回冲突错误。要更新已有用户，请使用 [`PATCH /v3/users/{vendor_data}/`](https://docs.didit.me/zh/management-api/users/update)。 - `vendor_data` 的硬性上限为 2000 字节（UTF-8 编码）。超过该上限的值会返回 400 验证错误，而不会被接受。 - 通常由已验证的会话派生的字段（`full_name`、`date_of_birth`）可以在此预先填充，但可能会被首个已通过的用户验证（KYC）会话**覆盖**。 - 此接口不接受人脸图像。要添加可信的导入人脸，请在此接口返回 `didit_internal_id` 后，使用 [`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)。 - 创建操作本身不发送 webhook。之后对用户的更改会发送 `user.data.updated` 或 `user.status.updated`。 - 使用 `send_verification_link` 时，新会话会在同一次调用中更新用户，并发送 `user.data.updated`。## 权限主密钥和拥有完全访问权限的 [API 密钥](https://docs.didit.me/zh/console/api-keys.md)始终可以调用此接口。 具有自定义访问权限的密钥需要 **用户**（`users`）写入权限。 当 `send_verification_link: true` 时，还需要 **会话** 写入权限，因为该调用会创建会话并分发其链接。 否则调用会返回 `403`，错误信息为 `This API key has no write access to sessions.`，且不写入任何数据。 仅限部分工作流或已通过会话的密钥无法访问此接口。Console 的[角色与权限](https://docs.didit.me/zh/console/roles-permissions.md)决定团队成员在 Console 中可以执行的操作。这些角色和权限不会用于评估 API 密钥请求。## 相关内容- [用户数据模型](https://docs.didit.me/zh/entities/users/data-model.md) - [上传用户人脸](https://docs.didit.me/zh/management-api/users/upload-face.md) - [供应商数据关联](https://docs.didit.me/zh/entities/vendor-data-linking.md) - [用户操作](https://docs.didit.me/zh/entities/users/operations.md) ## OpenAPI ````yaml zh/openapi-25.json POST /v3/users/create/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: 身份证件验证 API。使用 x-api-key 请求头进行身份验证。 servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/users/create/: post: tags: - Users summary: 创建用户 description: >- 在验证会话之前或无需验证会话的情况下，通过 `vendor_data` 创建[用户](/entities/users)。`vendor_data` 在应用的用户中必须唯一（重复将返回 `400`）。非幂等。 **联系方式：**`email` 和 `phone_number` 存储在 `metadata.contact` 中，`country` 存储在 `metadata.address` 中。当您发送 `first_name` 或 `last_name` 但未提供 `full_name` 时，Didit 会将它们拼接为 `full_name`。 **验证链接：**设置 `send_verification_link: true` 时，Didit 还会根据 `workflow_id` 为该人员创建一个验证会话，并通过电子邮件将链接发送至 `email`。该会话运行与[创建会话](/zh/sessions-api/create-session)相同的检查，例如黑名单和您的额度余额。该人员和会话要么同时创建，要么完全不创建：如果有任何检查失败，则不会写入任何内容，也不会发送电子邮件。响应中的 `verification_link` 描述了该会话；当您未请求链接时，其值为 `null`。 **API 密钥访问权限：**作用域 API 密钥需要 `users` 写入权限。在 `send_verification_link: true` 的情况下，它还需要 `sessions` 写入权限，否则调用将在写入任何内容之前返回 `403`。全权限密钥不受影响。参见 [API 密钥](/zh/console/api-keys)。 operationId: create_user requestBody: required: true content: application/json: schema: type: object required: - vendor_data properties: vendor_data: type: string description: 您对此用户的唯一标识符（自由格式字符串，非 UUID）。在该应用的用户之间必须唯一；按发送的内容精确匹配。 full_name: type: string nullable: true maxLength: 512 description: 用户的法定姓名。 display_name: type: string nullable: true description: 控制台中显示的易读显示名称（在界面显示时优先级高于 `full_name`）。 maxLength: 255 date_of_birth: type: string format: date nullable: true description: '`YYYY-MM-DD` 格式的出生日期。' status: type: string enum: - ACTIVE - FLAGGED - BLOCKED default: ACTIVE description: 初始生命周期状态。默认为 `ACTIVE`。 metadata: type: object nullable: true description: 附加到用户的任意 JSON 对象。默认为 `{}`。 approved_emails: type: array items: type: string description: 该用户的预信任邮箱地址，例如 `["john@example.com"]`。 approved_phones: type: array items: type: string description: 该用户的预信任电话号码，例如 `["+14155551234"]`。 issuing_states: type: array items: type: string description: 预先记录的签发国家/地区（ISO 3166-1 alpha-3），例如 `["USA"]`。 first_name: type: string maxLength: 255 description: >- 名字。未发送 `full_name` 时，Didit 会使用空格将 `first_name` 和 `last_name` 拼接为 `full_name`。不作为单独字段返回。 last_name: type: string maxLength: 255 description: >- 姓氏。未发送 `full_name` 时，将与 `first_name` 拼接为 `full_name`。不作为单独字段返回。 email: type: string format: email description: >- 联系邮箱，存储在 `metadata.contact.email` 中（它会替换您在 `metadata.contact` 内发送的 `email`）。当 `send_verification_link` 为 `true` 时必填：验证链接将发送至此地址。如果 `metadata.contact` 不是 JSON 对象，则调用将针对此字段返回 `400`。 phone_number: type: string maxLength: 32 description: >- 联系电话号码，存储在 `metadata.contact.phone_number` 中。如果 `metadata.contact` 不是 JSON 对象，该调用会因该字段返回 `400`。 country: type: string maxLength: 3 description: >- ISO 3166 代码格式的国家/地区，alpha-2 或 alpha-3（`ES` 或 `ESP`）。以大写形式存储在 `metadata.address.country` 中。如果 `metadata.address` 不是 JSON 对象，则该调用针对该字段返回 `400`。 send_verification_link: type: boolean default: false description: >- 为 `true` 时，Didit 会根据 `workflow_id` 为该人员创建验证会话，并通过电子邮件将链接发送至 `email`。需要提供 `email` 和 `workflow_id`。限定权限的 API 密钥还需要具备 `sessions` 写入权限。 workflow_id: type: string format: uuid description: >- 验证会话的工作流。当 `send_verification_link` 为 `true` 时必填。该工作流必须验证个人：企业验证（KYB）工作流将被拒绝。其他情况下忽略。 language: type: string maxLength: 10 description: >- 验证邮件的语言，采用[支持的语言](/zh/integration/supported-languages)代码。省略时为英语。当 `send_verification_link` 不为 `true` 时忽略。 examples: Basic: summary: 使用基本信息创建 value: vendor_data: user-abc-123 full_name: John Doe Full: summary: 所有字段 value: vendor_data: user-abc-456 full_name: Jane Smith display_name: Jane S. date_of_birth: '1990-05-15' status: ACTIVE metadata: tier: premium source: api approved_emails: - jane@example.com Contact details: summary: 姓名、邮箱、电话和国家/地区 value: vendor_data: user-abc-789 first_name: Julia last_name: Martin email: julia.martin@example.com phone_number: '+34600000000' country: ES With verification link: summary: 创建该人员并通过电子邮件向其发送验证链接 value: vendor_data: user-abc-789 first_name: Julia last_name: Martin email: julia.martin@example.com send_verification_link: true workflow_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 language: es responses: '201': description: >- 用户已创建。完整的用户记录（格式与获取用户相同），加上 `verification_link`：当 `send_verification_link` 为 `true` 时为 Didit 发送邮件的验证会话，否则为 `null`。 content: application/json: schema: allOf: - $ref: '#/components/schemas/UserDetailItem' - type: object required: - verification_link properties: verification_link: type: object nullable: true description: >- Didit 创建并通过电子邮件发送给该人员的验证会话。始终存在：当 `send_verification_link` 不为 `true` 时为 `null`。 required: - session_id - session_number - status - url - workflow_id - email properties: session_id: type: string format: uuid description: 验证会话的 ID。 session_number: type: integer description: 您应用内该会话的序号。 status: type: string description: 会话的状态，刚创建的会话为 `Not Started`。 url: type: string format: uri description: Didit 通过电子邮件发送给该人员的验证链接。 workflow_id: type: string format: uuid nullable: true description: 会话运行的工作流。 email: type: string format: email description: 链接发送的目标地址。 examples: Created: value: didit_internal_id: f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418 vendor_data: user-abc-123 display_name: null full_name: John Doe date_of_birth: null effective_name: John Doe status: ACTIVE metadata: {} portrait_image_url: null session_count: 0 approved_count: 0 declined_count: 0 in_review_count: 0 issuing_states: [] approved_emails: [] approved_phones: [] features: {} features_list: [] last_session_at: null last_activity_at: '2025-06-15T10:30:00Z' first_session_at: null tags: [] comments: [] created_at: '2025-06-15T10:30:00Z' updated_at: '2025-06-15T10:30:00Z' verification_link: null Created with verification link: value: didit_internal_id: 9b2f6c1e-3d4a-4e5f-8a7b-1c2d3e4f5a6b vendor_data: user-abc-789 display_name: null full_name: Julia Martin date_of_birth: null effective_name: Julia Martin status: ACTIVE metadata: contact: email: julia.martin@example.com portrait_image_url: null session_count: 1 approved_count: 0 declined_count: 0 in_review_count: 0 issuing_states: [] approved_emails: [] approved_phones: [] features: {} features_list: [] last_session_at: '2025-06-15T10:30:00Z' last_activity_at: '2025-06-15T10:30:00Z' first_session_at: '2025-06-15T10:30:00Z' tags: [] comments: [] created_at: '2025-06-15T10:30:00Z' updated_at: '2025-06-15T10:30:00Z' verification_link: session_id: 3fa85f64-5717-4562-b3fc-2c963f66afa7 session_number: 43762 status: Not Started url: https://verify.didit.me/en/session/3FaJ9wLqX2Mz workflow_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 email: julia.martin@example.com '400': description: >- 无效的请求体，按字段索引：通常是重复的 `vendor_data`、缺少必填字段或格式错误的值。在设置了 `send_verification_link: true` 的情况下，还可能是缺少 `email` 或 `workflow_id`、未知或企业验证（KYB）工作流、不受支持的 `language`（字段键为 `contact_details.email_lang`）、被列入黑名单的 `vendor_data`，或者额度不足以启动会话。未写入任何内容。 content: application/json: examples: Duplicate: value: vendor_data: - A user with this vendor_data already exists. Missing vendor_data: value: vendor_data: - This field is required. Bad metadata: value: metadata: - Metadata must be a JSON object. Bad status: value: status: - >- Invalid status. Valid options are: ACTIVE, FLAGGED, BLOCKED Bad country: value: country: - Use an ISO 3166 country code, like ES or ESP. Contact not an object: value: email: - >- metadata.contact must be a JSON object to store this value. Address not an object: value: country: - >- metadata.address must be a JSON object to store this value. Link without email or workflow: value: email: - >- An email address is required to send a verification link. workflow_id: - Pick the workflow to send a verification link for. Unknown workflow: value: workflow_id: - Invalid workflow_id. Business workflow: value: workflow_id: - >- This workflow verifies a business. Pick a workflow that verifies a person to send them a verification link. Blocklisted vendor_data: value: vendor_data: >- This user or business has been blocked and cannot create new verification sessions. Insufficient credits: value: detail: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me '401': description: >- 未提供凭证。对 `/v3/users/*` 路径的请求如果不包含 `x-api-key` 请求头（或 `Authorization: Bearer` token），将在到达 API 之前被身份验证中间件拒绝。 content: application/json: examples: Missing credentials: value: detail: >- You must be authenticated with a valid access token to access this endpoint. '403': description: >- 无效或已撤销的 API 密钥，或者该密钥无法为此应用创建用户。限定范围的 API 密钥需要 `users` 写入权限，且在 `send_verification_link` 为 `true` 时还需要 `sessions` 写入权限；未写入任何内容。缺少密钥返回 `403`；错误、已撤销或已过期的密钥返回 `401`。 content: application/json: examples: Forbidden: value: detail: You do not have permission to perform this action. No sessions write: summary: 作用域密钥在没有 sessions 写入权限的情况下请求验证链接 value: detail: This API key has no write access to sessions. '429': description: 超出速率限制；请退避并在 `Retry-After` 指定的间隔后重试。 content: application/json: examples: Rate limited: value: detail: Request was throttled. Expected available in 30 seconds. security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: |- 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-abc-123", "full_name": "John Doe"}' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.users.create( vendor_data="user-abc-123", full_name="John Doe", ) print(result) - lang: javascript label: Node.js source: |- import Didit from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.users.create({ vendor_data: "user-abc-123", full_name: "John Doe", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Users.Create(ctx, didit.UsersCreateParams{\n\tVendorData: \"user-abc-123\",\n\tFullName: didit.String(\"John Doe\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: |- import me.didit.Didit; import me.didit.types.UsersCreateParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.users().create(UsersCreateParams.builder() .vendorData("user-abc-123") .fullName("John Doe") .build()); System.out.println(result); - lang: php label: PHP source: |- users->create([ 'vendor_data' => 'user-abc-123', 'full_name' => 'John Doe', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.users.create( vendor_data: "user-abc-123", full_name: "John Doe" ) puts result.to_h - lang: csharp label: .NET source: |- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.Users.CreateAsync(new UsersCreateParams { VendorData = "user-abc-123", FullName = "John Doe", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: UserDetailItem: type: object description: 完整的用户详情。在 UserListItem 基础上扩展了元数据、备注和 updated_at。 allOf: - $ref: '#/components/schemas/UserListItem' - type: object properties: metadata: type: object description: 您附加到此用户的自定义元数据 JSON。默认为 `{}`。 tags: type: array description: >- 标签分配情况。注意：与列表响应中使用的扁平 `{uuid, name, color}` 结构不同，详情响应中的每个条目均为标签*链接*对象（`{uuid, tag: {...}, added_by_email, added_by_name, created_at}`）。 items: type: object properties: uuid: type: string format: uuid description: 标签分配的 UUID（而非标签本身的 UUID）。 tag: type: object properties: uuid: type: string format: uuid name: type: string color: type: string description: type: string nullable: true source: type: string enum: - didit - custom created_at: type: string format: date-time updated_at: type: string format: date-time added_by_email: type: string nullable: true added_by_name: type: string nullable: true created_at: type: string format: date-time comments: type: array items: type: object properties: uuid: type: string format: uuid comment_type: type: string enum: - COMMENT - STATUS_CHANGED - METADATA_UPDATED - TAG_ADDED - TAG_REMOVED - PROFILE_UPDATED comment: type: string nullable: true actor_email: type: string nullable: true actor_name: type: string nullable: true previous_status: type: string nullable: true enum: - ACTIVE - FLAGGED - BLOCKED - null new_status: type: string nullable: true enum: - ACTIVE - FLAGGED - BLOCKED - null previous_value: type: object nullable: true description: PROFILE_UPDATED 条目的先前字段值。 new_value: type: object nullable: true description: PROFILE_UPDATED 条目的新字段值。 changed_fields: type: array items: type: string description: 由 PROFILE_UPDATED 条目更改的字段名称。 metadata: type: object nullable: true mentioned_emails: type: array items: type: string created_at: type: string format: date-time description: 该用户的活动日志和评论（状态变更、资料修改、手动备注）。 updated_at: type: string format: date-time UserListItem: type: object description: 已验证的用户。 properties: didit_internal_id: type: string format: uuid description: Didit 为此用户分配的稳定内部 UUID。 vendor_data: type: string nullable: true description: 您对此用户的唯一标识符（创建会话时传入）。未提供供应商标识符时可为 null。 display_name: type: string nullable: true description: 您设置的自定义显示名称 full_name: type: string nullable: true description: 从已验证证件中提取的姓名 date_of_birth: type: string format: date nullable: true effective_name: type: string nullable: true description: 最佳可用名称：如果已设置则为 display_name，否则为 full_name status: type: string enum: - ACTIVE - FLAGGED - BLOCKED description: >- 用户记录的生命周期状态（并非会话状态）。`ACTIVE` 为默认值，`FLAGGED` 标记该用户需要人工关注，`BLOCKED` 会阻止该 `vendor_data` 创建新会话。 portrait_image_url: type: string nullable: true description: 用户肖像照片的预签名 URL（数小时后过期） session_count: type: integer description: 该用户的验证会话总数 approved_count: type: integer description: 已通过的会话数量 declined_count: type: integer description: 已拒绝的会话数量 in_review_count: type: integer description: 审核中的会话数量 issuing_states: type: array items: type: string description: >- 此用户已通过的身份证件上显示的签发国家/地区的 ISO 3166-1 alpha-3 代码，例如 `["USA", "ESP"]`。无时为空数组。 approved_emails: type: array items: type: string description: 从该用户已通过的会话中收集的已验证邮箱地址，例如 `["john@example.com"]`。 approved_phones: type: array items: type: string description: 从该用户已通过的会话中收集的已验证电话号码，例如 `["+14155551234"]`。 features: type: object description: >- 该用户所有会话的每项功能汇总状态。可选键：`ID_VERIFICATION`、`NFC`、`LIVENESS`、`FACE_MATCH`、`POA`、`QUESTIONNAIRE`、`EMAIL_VERIFICATION`、`PHONE`、`AML`、`IP_ANALYSIS`、`AGE_ESTIMATION`、`DATABASE_VALIDATION`。可选值：`Approved`、`Declined`、`In Review`、`Not Finished`、`Resub Requested`。 features_list: type: array items: type: object properties: feature: type: string status: type: string description: 与 `features` 相同的数据，为 `{feature, status}` 对象的有序数组。 last_session_at: type: string format: date-time nullable: true description: 最近一次会话的时间戳 first_session_at: type: string format: date-time nullable: true description: 首次会话的时间戳 last_activity_at: type: string format: date-time nullable: true description: 该用户最近一次活动的时间戳（会话、交易、状态变更、数据编辑等）。 tags: type: array items: type: object properties: uuid: type: string format: uuid name: type: string color: type: string description: 分配给该用户的标签 created_at: type: string format: date-time securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- 您的应用 API 密钥，可在 Business Console 的“开发者 -> API 密钥”中获取。主密钥拥有完整访问权限。指定名称的密钥可设置作用域：针对每个资源设为无权限、只读或读写，限定于特定工作流或已通过的会话、限定于 IP 地址列表，以及设置到期日期。401 表示密钥错误、已撤销或已过期；403 表示未发送密钥、密钥无权访问该资源或操作，或请求来自其 IP 列表之外的地址；在会话路由上返回 404 表示该会话不在该密钥允许的工作流或状态范围内。没有媒体访问权限的密钥获取到的图片、视频和 PDF URL 将为 null；没有会话写入权限的密钥获取到的会话链接和 token 将为 null。请参阅 https://docs.didit.me/console/api-keys。 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.