Skip to main content
POST
curl

Overview

Explicitly creates a User entity before any session is run. The returned entity lands in ACTIVE status unless you specify otherwise.

When to use it

  • Pre-seed metadata (tier, signup source, internal tags) before the customer verifies.
  • Migrate from another vendor — recreate your existing user roster in Didit so history and analytics start from a known baseline.
  • Import trusted profile faces — create the User first, then call Upload User Face with the returned didit_internal_id.
  • Transaction-only use cases — register a User with vendor_data so you can submit transactions without ever running a User Verification (KYC) session.

Notes

Permissions

Role must grant create:users.

Authorizations

x-api-key
string
header
required

Body

application/json
vendor_data
string
required

Your unique identifier for this user (free-form string, NOT a UUID). Must be unique among non-deleted users for the application; matched exactly as sent.

full_name
string | null

Full legal name of the user.

Maximum string length: 512
display_name
string | null

Friendly display name shown in the console (takes precedence over full_name for UI display).

Maximum string length: 255
date_of_birth
string<date> | null

Date of birth in YYYY-MM-DD format.

status
enum<string>
default:ACTIVE

Initial lifecycle status. Defaults to ACTIVE.

Available options:
ACTIVE,
FLAGGED,
BLOCKED
metadata
object | null

Arbitrary JSON object you attach to the user. Defaults to {}.

approved_emails
string[]

Pre-trusted email addresses for this user, e.g. ["john@example.com"].

approved_phones
string[]

Pre-trusted phone numbers for this user, e.g. ["+14155551234"].

issuing_states
string[]

Pre-recorded issuing countries (ISO 3166-1 alpha-3), e.g. ["USA"].

Response

User created. Full user record returned (same shape as Get User).

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>