Skip to main content
PATCH
/
v3
/
users
/
{vendor_data}
/
curl
curl -X PATCH 'https://verification.didit.me/v3/users/user-abc-123/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"display_name": "Jane S.", "status": "FLAGGED"}'
{
  "didit_internal_id": "f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418",
  "vendor_data": "user-abc-123",
  "display_name": "Jane S.",
  "full_name": "Jane Elizabeth Smith",
  "date_of_birth": "1985-11-22",
  "effective_name": "Jane S.",
  "status": "FLAGGED",
  "metadata": {
    "tier": "premium"
  },
  "portrait_image_url": "https://<media-host>/...",
  "session_count": 3,
  "approved_count": 2,
  "declined_count": 0,
  "in_review_count": 1,
  "issuing_states": [
    "USA"
  ],
  "approved_emails": [
    "john@example.com"
  ],
  "approved_phones": [
    "+14155551234"
  ],
  "features": {
    "ID_VERIFICATION": "Approved",
    "LIVENESS": "Approved",
    "FACE_MATCH": "Approved",
    "AML": "Approved"
  },
  "features_list": [
    {
      "feature": "ID_VERIFICATION",
      "status": "Approved"
    },
    {
      "feature": "LIVENESS",
      "status": "Approved"
    },
    {
      "feature": "FACE_MATCH",
      "status": "Approved"
    },
    {
      "feature": "AML",
      "status": "Approved"
    }
  ],
  "last_session_at": "2025-06-15T10:30:00Z",
  "last_activity_at": "2025-06-15T10:30:00Z",
  "first_session_at": "2025-06-01T08:00:00Z",
  "tags": [
    {
      "uuid": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
      "tag": {
        "uuid": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
        "name": "VIP",
        "color": "#2567FF",
        "description": null,
        "source": "custom",
        "created_at": "2025-05-01T09:00:00Z",
        "updated_at": "2025-05-01T09:00:00Z"
      },
      "added_by_email": "analyst@acme.com",
      "added_by_name": "Jane Analyst",
      "created_at": "2025-06-02T11:00:00Z"
    }
  ],
  "comments": [],
  "created_at": "2025-06-01T08:00:00Z",
  "updated_at": "2025-06-15T10:30:00Z"
}

​
Overview

Updates mutable fields on a User entity. Fields propagated from verified User Verification (KYC) sessions (full_name, date_of_birth, portrait_image, aggregate counters, features) are read-only.

​
When to use it

  • Update your own metadata — move a user between tiers, change tags, record an internal note.
  • Rename — set a better display_name for internal-facing console views.
  • Override verified data (with caution) — manual overrides are allowed but logged to the audit trail.

​
Notes

  • vendor_data in the URL cannot be changed via this endpoint. Create a new user and delete the old one if you need to rekey.
  • Emits a user.data.updated webhook with a changed_fields array so consumers can sync efficiently.
  • If you PATCH a field that is currently managed by a verified session, the override will be accepted but flagged in the audit log.

​
Permissions

Role must grant update:users.

Authorizations

​
x-api-key
string
header
required

Path Parameters

​
vendor_data
string
required

Your unique identifier for the user (free-form string, NOT a UUID).

Body

application/json
​
full_name
string | null

Full name of the user

Maximum string length: 512
​
display_name
string | null

Custom display name for this user

​
date_of_birth
string<date> | null

Date of birth in YYYY-MM-DD format

​
status
enum<string>

User lifecycle status. Changing it via this generic PATCH does NOT sync the system blocklist or record a status-change activity; prefer the update-status endpoint.

Available options:
ACTIVE,
FLAGGED,
BLOCKED
​
metadata
object

Arbitrary JSON object you attach to the user. Fully replaces the existing metadata on update — merge client-side if you only want to add keys.

​
approved_emails
string[]

Verified email addresses for this user, e.g. ["john@example.com"]. Fully replaces the stored list.

​
approved_phones
string[]

Verified phone numbers for this user. Fully replaces the stored list.

​
issuing_states
string[]

Issuing countries (ISO 3166-1 alpha-3), e.g. ["USA"]. Fully replaces the stored list.

Response

User updated. The full updated user record (same shape as Get User) is returned.

Full user detail. Extends UserListItem with metadata, comments, and updated_at.

​
didit_internal_id
string<uuid>

Didit's stable internal UUID for this user.

​
vendor_data
string | null

Your unique identifier for this user (passed when creating sessions). This can be null when no vendor identifier was supplied.

​
display_name
string | null

Custom display name set by you

​
full_name
string | null

Full name extracted from verified documents

​
date_of_birth
string<date> | null
​
effective_name
string | null

Best available name: display_name if set, otherwise full_name

​
status
enum<string>

Lifecycle status of the user record (NOT a session status). ACTIVE is the default, FLAGGED marks the user for manual attention, BLOCKED prevents new sessions for this vendor_data.

Available options:
ACTIVE,
FLAGGED,
BLOCKED
​
portrait_image_url
string | null

Presigned URL of the user's portrait photo (expires after a few hours)

​
session_count
integer

Total number of verification sessions for this user

​
approved_count
integer

Number of approved sessions

​
declined_count
integer

Number of declined sessions

​
in_review_count
integer

Number of sessions in review

​
issuing_states
string[]

ISO 3166-1 alpha-3 codes of issuing countries seen on this user's approved ID documents, e.g. ["USA", "ESP"]. Empty array when none.

​
approved_emails
string[]

Verified email addresses collected from this user's approved sessions, e.g. ["john@example.com"].

​
approved_phones
string[]

Verified phone numbers collected from this user's approved sessions, e.g. ["+14155551234"].

​
features
object

Aggregated per-feature status across all of this user's sessions. Possible keys: ID_VERIFICATION, NFC, LIVENESS, FACE_MATCH, POA, QUESTIONNAIRE, EMAIL_VERIFICATION, PHONE, AML, IP_ANALYSIS, AGE_ESTIMATION, DATABASE_VALIDATION. Possible values: Approved, Declined, In Review, Not Finished, Resub Requested.

​
features_list
object[]

Same data as features, as an ordered array of {feature, status} objects.

​
last_session_at
string<date-time> | null

Timestamp of the most recent session

​
first_session_at
string<date-time> | null

Timestamp of the first session

​
last_activity_at
string<date-time> | null

Timestamp of the most recent activity on this user (session, transaction, status change, data edit, etc.).

​
tags
object[]

Tag assignments. NOTE: on detail responses each entry is a tag link object ({uuid, tag: {...}, added_by_email, added_by_name, created_at}), unlike the flat {uuid, name, color} shape used on list responses.

​
created_at
string<date-time>
​
metadata
object

Custom metadata JSON you attached to this user. Defaults to {}.

​
comments
object[]

Activity log and comments for this user (status changes, profile edits, manual notes).

​
updated_at
string<date-time>