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

# 用户数据模型：Didit 用户架构

> Didit 用户实体的全部字段，包括身份信息、状态、KYC 会话汇总、生物识别数据、活动时间戳和元数据。采用按量计费的定价方式。

此页面记录 User 实体中的每个字段。字段分为五组：身份、状态、会话汇总、活动时间戳和元数据。

## 身份字段

| 字段 | 类型 | 说明 |
| - | - | - |
| `uuid` | UUID | Didit 分配的主键。稳定且唯一。 |
| `didit_internal_id` | string | 便于阅读的内部标识符（会出现在 API 响应中）。 |
| `vendor_data` | string | 您为该用户设置的标识符。在每个应用内唯一。[了解更多](https://docs.didit.me/zh/entities/vendor-data-linking.md)。 |
| `display_name` | string | 控制台中显示的覆盖名称。未设置时，默认使用 `full_name` 或 `vendor_data`。 |
| `full_name` | string | 来自最新一次已通过的用户验证（KYC）会话中证件的完整法定姓名。 |
| `date_of_birth` | date (ISO 8601) | 来自最新一次已通过的用户验证（KYC）会话。 |
| `portrait_image` | URL | 来自最新一次已通过的活体检测中自拍照的已签名 S3 URL。 |

> [!NOTE]
>
> 当 `full_name`、`date_of_birth` 和 `portrait_image` 来自已验证的会话时，这些字段为只读字段。您可以通过控制台或 `PATCH /v3/users/{vendor_data}/` 覆盖这些字段，但手动覆盖会在审计日志中被标记。

## 状态

| 字段 | 类型 | 取值 | 说明 |
| - | - | - | - |
| `status` | enum | `ACTIVE`、`FLAGGED`、`BLOCKED` | 控制后续会话和交易的执行。参见[生命周期](https://docs.didit.me/zh/entities/lifecycle.md)。 |

## 会话汇总字段

这些字段由 Didit 计算，并在会话完成时实时更新。

| 字段 | 类型 | 说明 |
| - | - | - |
| `session_count` | int | 为该用户创建过的会话总数 |
| `approved_count` | int | 以 `APPROVED` 结束的会话数 |
| `declined_count` | int | 以 `DECLINED` 结束的会话数 |
| `in_review_count` | int | 当前为 `IN_REVIEW` 的会话数 |
| `issuing_states[]` | ISO 国家/地区代码数组 | 所有会话中已验证证件的签发国家/地区 |
| `approved_emails[]` | 字符串数组 | 通过[邮箱验证](https://docs.didit.me/zh/core-technology/email-verification/overview.md)验证的邮箱 |
| `approved_phones[]` | 字符串数组 | 通过[电话验证](https://docs.didit.me/zh/core-technology/phone-verification/overview.md)验证的电话号码 |
| `features` | object | 所有会话中每项功能的最新状态 |

### `features` 映射

每个会话都会运行一项或多项功能（身份证件验证、活体检测、人脸比对、AML、POA、NFC 等）。`features` 映射保存该用户每项功能的**最新**状态：

```json theme={null}
{
  "id_verification": "APPROVED",
  "liveness": "APPROVED",
  "face_match": "APPROVED",
  "aml": "IN_REVIEW",
  "proof_of_address": "APPROVED",
  "nfc_verification": "NOT_FINISHED"
}
```

功能状态：`NOT_FINISHED`、`APPROVED`、`DECLINED`、`IN_REVIEW`、`EXPIRED`、`ABANDONED`、`RESUB_REQUESTED`。

如果您想快速判断"该用户当前是否已完成全部验证"，可以直接使用 `features` 映射，无需遍历所有会话。

## 活动时间戳

| 字段 | 类型 | 更新时机 |
| - | - | - |
| `first_session_at` | ISO 时间戳 | 创建第一个会话时 |
| `last_session_at` | ISO 时间戳 | 最近一个会话被创建或更新时 |
| `last_activity_at` | ISO 时间戳 | 任何变更时，包括会话、交易、状态、资料、备注和标签 |
| `created_at` | ISO 时间戳 | 实体记录创建时 |
| `updated_at` | ISO 时间戳 | 实体记录最近一次更新时 |

## 元数据

| 字段 | 类型 | 说明 |
| - | - | - |
| `metadata` | object (JSON) | 由您控制的自由格式 JSON。可用于内部标签、等级、注册来源等。 |
| `tags[]` | array | 在控制台或 API 中管理的标签，用于筛选和分组 |

元数据没有固定结构，Didit 会保存您写入的任何内容。

## 关联关系（不存储在用户记录中）

| 关联 | 访问方式 |
| - | - |
| 会话 | `GET /v3/sessions?vendor_data=<value>` |
| 交易（作为申请人） | `GET /v3/transactions/?vendor_data=<value>` |
| 交易（作为交易对手） | 在控制台中按交易对手的 vendor\_data 筛选交易列表 |
| 关联企业（董事 / UBO） | 显示在控制台的用户详情页上 |
| 人脸生物特征 | 控制台和 Lists API |
| 黑名单条目 | [Lists API](https://docs.didit.me/zh/management-api/lists/overview.md)，按用户的标识符筛选条目 |

## 响应示例

```json theme={null}
{
  "uuid": "9c7d2a30-2f98-4d4f-9d2d-1a7c4b1e5b6a",
  "didit_internal_id": "U-2026-00042",
  "vendor_data": "user-42",
  "display_name": "Jane Doe",
  "full_name": "John Doe",
  "date_of_birth": "1990-01-01",
  "portrait_image": "https://<media-host>/...",
  "status": "ACTIVE",
  "session_count": 3,
  "approved_count": 2,
  "declined_count": 0,
  "in_review_count": 1,
  "issuing_states": ["US", "ES"],
  "approved_emails": ["jane@example.com"],
  "approved_phones": ["+14155550123"],
  "features": {
    "id_verification": "APPROVED",
    "liveness": "APPROVED",
    "face_match": "APPROVED",
    "aml": "IN_REVIEW"
  },
  "first_session_at": "2025-03-01T12:00:00Z",
  "last_session_at": "2026-04-10T09:00:00Z",
  "last_activity_at": "2026-04-16T10:00:00Z",
  "metadata": { "tier": "premium" }
}
```

## 后续步骤

> [card] [操作](https://docs.didit.me/zh/entities/users/operations.md)
>
> 创建、更新、变更状态、删除。

> [card] [KYC 历史](https://docs.didit.me/zh/entities/users/kyc-history.md)
>
> 获取与该用户关联的所有会话。

> [card] [API 参考](https://docs.didit.me/zh/management-api/users/get.md)
>
> GET /v3/users/{vendor_data}/ 架构。


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