Skip to main content
PATCH
/
v3
/
users
/
{vendor_data}
/
update-status
curl --request PATCH \
  --url https://verification.didit.me/v3/users/{vendor_data}/update-status/ \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "status": "Approved"
}
'
{
  "didit_internal_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "vendor_data": "<string>",
  "display_name": "<string>",
  "full_name": "<string>",
  "date_of_birth": "2023-12-25",
  "effective_name": "<string>",
  "status": "Approved",
  "portrait_image_url": "<string>",
  "session_count": 123,
  "approved_count": 123,
  "declined_count": 123,
  "in_review_count": 123,
  "issuing_states": {},
  "approved_emails": {},
  "approved_phones": {},
  "features": {},
  "features_list": [
    {
      "feature": "<string>",
      "status": "<string>"
    }
  ],
  "last_session_at": "2023-11-07T05:31:56Z",
  "first_session_at": "2023-11-07T05:31:56Z",
  "tags": [
    {
      "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "color": "<string>"
    }
  ],
  "created_at": "2023-11-07T05:31:56Z",
  "metadata": {},
  "comments": [
    {
      "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "comment_type": "<string>",
      "comment": "<string>",
      "actor_email": "<string>",
      "actor_name": "<string>",
      "previous_status": "<string>",
      "new_status": "<string>",
      "created_at": "2023-11-07T05:31:56Z"
    }
  ],
  "updated_at": "2023-11-07T05:31:56Z"
}

​
Overview

Moves a User entity between ACTIVE, FLAGGED, and BLOCKED. See entity lifecycle for the full state machine.

​
When to use it

  • Block a user after confirming fraud or a compliance breach.
  • Flag a user pending manual review without hard-blocking them.
  • Unblock a user after successful remediation.
  • Propagate external signals — e.g. when your own fraud engine scores a user above a threshold, move them to FLAGGED via this endpoint.

​
Notes

  • Valid values: ACTIVE, FLAGGED, BLOCKED. Invalid values return 400.
  • Passing a reason string is recommended — it is persisted and surfaced in the audit log and webhook payload.
  • BLOCKED users have all new sessions auto-declined and all new transactions auto-declined.
  • Emits a user.status.updated webhook with previous_status, status, and reason.

​
Enforcement

StatusEffect on new sessionsEffect on new transactions
ACTIVENormal flowNormal flow
FLAGGEDPermitted but routed to IN_REVIEWPermitted; may auto-escalate depending on rules
BLOCKEDAuto-declinedAuto-declined

​
Permissions

Role must grant update-status:users.

Authorizations

​
x-api-key
string
header
required

Path Parameters

​
vendor_data
string
required

Your unique identifier for the user.

Body

application/json
​
status
enum<string>
required

New status for the user

Available options:
Approved,
Declined,
In Review

Response

200 - application/json

User status updated.

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>

Overall verification status of this user

Available options:
Approved,
Declined,
In Review,
Pending
​
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
object

Map of ISO3 country codes from approved documents, e.g. {"USA": 2, "ESP": 1}

​
approved_emails
object

Verified email addresses, e.g. {"john@example.com": true}

​
approved_phones
object

Verified phone numbers

​
features
object

Map of feature name to latest status, e.g. {"OCR": "Approved", "LIVENESS": "Approved", "AML": "In Review"}

​
features_list
object[]

Same as features but as an 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

​
tags
object[]

Tags assigned to this user

​
created_at
string<date-time>
​
metadata
object

Custom metadata JSON you attached to this user

​
comments
object[]

Activity log and comments for this user

​
updated_at
string<date-time>