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

# User Data Model

> Every field on a Didit User entity — identity, status, KYC session aggregates, biometrics, activity timestamps, and metadata. Pay-per-call from $0.30.

This page documents every field on a User entity. Fields fall into five groups: identity, status, session aggregates, activity timestamps, and metadata.

## Identity fields

| Field               | Type            | Description                                                                                        |
| ------------------- | --------------- | -------------------------------------------------------------------------------------------------- |
| `uuid`              | UUID            | Didit-assigned primary key. Stable and unique.                                                     |
| `didit_internal_id` | string          | Human-readable internal identifier (surfaced in API responses).                                    |
| `vendor_data`       | string          | Your identifier for the user. Unique per application. [Read more](/entities/vendor-data-linking).  |
| `display_name`      | string          | Override name shown in the console. Defaults to `full_name` or `vendor_data` when unset.           |
| `full_name`         | string          | Full legal name propagated from the latest approved User Verification (KYC) session's ID document. |
| `date_of_birth`     | date (ISO 8601) | Propagated from the latest approved User Verification (KYC) session.                               |
| `portrait_image`    | URL             | Signed S3 URL for the selfie from the latest approved liveness check.                              |

<Note>
  `full_name`, `date_of_birth`, and `portrait_image` are read-only when derived from a verified session. You can override them via the console or via `PATCH /v3/users/{vendor_data}/`, but manual overrides are flagged in the audit log.
</Note>

## Status

| Field    | Type | Values                         | Description                                                                                      |
| -------- | ---- | ------------------------------ | ------------------------------------------------------------------------------------------------ |
| `status` | enum | `ACTIVE`, `FLAGGED`, `BLOCKED` | Controls enforcement for future sessions and transactions. See [lifecycle](/entities/lifecycle). |

## Session aggregate fields

These fields are computed by Didit and update in real time as sessions complete.

| Field               | Type                       | Description                                                                            |
| ------------------- | -------------------------- | -------------------------------------------------------------------------------------- |
| `session_count`     | int                        | Total sessions ever created for this user                                              |
| `approved_count`    | int                        | Sessions that finished with `APPROVED`                                                 |
| `declined_count`    | int                        | Sessions that finished with `DECLINED`                                                 |
| `in_review_count`   | int                        | Sessions currently `IN_REVIEW`                                                         |
| `issuing_states[]`  | array of ISO country codes | Countries of all ID documents verified across sessions                                 |
| `approved_emails[]` | array of strings           | Emails verified via [Email Verification](/core-technology/email-verification/overview) |
| `approved_phones[]` | array of strings           | Phones verified via [Phone Verification](/core-technology/phone-verification/overview) |
| `features`          | object                     | Latest status of each feature across all sessions                                      |

### The `features` map

Every session runs one or more features (ID verification, liveness, face match, AML, POA, NFC, etc.). The `features` map holds the **latest** status of each feature for this user:

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

Feature statuses: `NOT_FINISHED`, `APPROVED`, `DECLINED`, `IN_REVIEW`, `EXPIRED`, `ABANDONED`, `RESUB_REQUESTED`.

Use the `features` map as the fast path to answer "is this user fully verified right now?" without iterating all sessions.

## Activity timestamps

| Field              | Type          | Updated when                                                    |
| ------------------ | ------------- | --------------------------------------------------------------- |
| `first_session_at` | ISO timestamp | First session was created                                       |
| `last_session_at`  | ISO timestamp | Most recent session was created or updated                      |
| `last_activity_at` | ISO timestamp | Any change — session, transaction, status, profile, notes, tags |
| `created_at`       | ISO timestamp | Entity row was created                                          |
| `updated_at`       | ISO timestamp | Entity row was last updated                                     |

## Metadata

| Field      | Type          | Description                                                                  |
| ---------- | ------------- | ---------------------------------------------------------------------------- |
| `metadata` | object (JSON) | Free-form JSON you control. Use for internal tags, tier, signup source, etc. |
| `tags[]`   | array         | Console/API-managed tags for filtering and grouping                          |

Metadata has no schema — Didit persists whatever you write.

## Relations (not stored on the user row)

| Relation                           | How to access                                                                          |
| ---------------------------------- | -------------------------------------------------------------------------------------- |
| Sessions                           | `GET /v3/sessions?vendor_data=<value>`                                                 |
| Transactions (as applicant)        | `GET /v3/transactions/?vendor_data=<value>`                                            |
| Transactions (as counterparty)     | Filter transaction list by counterparty vendor\_data in console                        |
| Linked businesses (director / UBO) | Surfaced on the user detail page in the console                                        |
| Face biometrics                    | Console + Lists API                                                                    |
| Blocklist entries                  | [Lists API](/management-api/lists/overview) — filter entries by the user's identifiers |

## Example response

```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" }
}
```

## Next steps

<CardGroup cols={3}>
  <Card title="Operations" icon="gear" href="/entities/users/operations">
    Create, update, change status, delete.
  </Card>

  <Card title="KYC history" icon="clock-rotate-left" href="/entities/users/kyc-history">
    Retrieve every session tied to the user.
  </Card>

  <Card title="API reference" icon="code" href="/management-api/users/get">
    GET /v3/users/{vendor_data}/ schema.
  </Card>
</CardGroup>