User Data Model

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

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.

Status

Field	Type	Values	Description
`status`	enum	`ACTIVE`, `FLAGGED`, `BLOCKED`	Controls enforcement for future sessions and transactions. See 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
`approved_phones[]`	array of strings	Phones verified via Phone Verification
`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:

{
  "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 — filter entries by the user’s identifiers

Example response

{
  "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

Operations

Create, update, change status, delete.

KYC history

Retrieve every session tied to the user.

API reference

GET /v3/users// schema.

Overview

Pricing

Workflows & Verification

Review & Operations

Entities (Users & Businesses)

Settings & Customization

Security & Compliance

Resources

Identity fields

Status

Session aggregate fields

The `features` map

Activity timestamps

Metadata

Relations (not stored on the user row)

Example response

Next steps

Operations

KYC history

API reference

​Identity fields

​Status

​Session aggregate fields

​The features map

​Activity timestamps

​Metadata

​Relations (not stored on the user row)

​Example response

​Next steps

Operations

KYC history

API reference

Identity fields

Status

Session aggregate fields

The `features` map

Activity timestamps

Metadata

Relations (not stored on the user row)

Example response

Next steps