> ## 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 User 엔티티의 모든 필드를 설명합니다. 신원 정보, 상태, KYC 세션 집계, 생체 인증, 활동 타임스탬프, 메타데이터를 포함합니다. Didit 종량제 요금 적용.

이 페이지는 User 엔티티의 모든 필드를 설명합니다. 필드는 신원 정보, 상태, 세션 집계, 활동 타임스탬프, 메타데이터의 다섯 그룹으로 나뉩니다.

## 신원 정보 필드

| 필드 | 유형 | 설명 |
| - | - | - |
| `uuid` | UUID | Didit이 할당한 기본 키입니다. 안정적이며 고유합니다. |
| `didit_internal_id` | string | 사람이 읽을 수 있는 내부 식별자입니다(API 응답에 노출됨). |
| `vendor_data` | string | 사용자를 식별하는 고객사 식별자입니다. 애플리케이션마다 고유합니다. [자세히 보기](https://docs.didit.me/ko/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/ko/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/ko/core-technology/email-verification/overview.md)으로 검증된 이메일 |
| `approved_phones[]` | 문자열 배열 | [전화번호 인증](https://docs.didit.me/ko/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/ko/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/ko/entities/users/operations.md)
>
> 생성, 업데이트, 상태 변경, 삭제.

> [card] [KYC 이력](https://docs.didit.me/ko/entities/users/kyc-history.md)
>
> 사용자와 연결된 모든 세션을 조회합니다.

> [card] [API 레퍼런스](https://docs.didit.me/ko/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.