Create User

curl -X POST 'https://verification.didit.me/v3/users/create/' \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{"vendor_data": "user-abc-123", "full_name": "John Doe"}'

{ "didit_internal_id": "f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418", "vendor_data": "user-abc-123", "display_name": null, "full_name": "John Doe", "date_of_birth": null, "effective_name": "John Doe", "status": "ACTIVE", "session_count": 0, "approved_count": 0, "declined_count": 0, "in_review_count": 0, "metadata": {}, "comments": [], "created_at": "2025-06-15T10:30:00Z", "updated_at": "2025-06-15T10:30:00Z" }

curl -X POST 'https://verification.didit.me/v3/users/create/' \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{"vendor_data": "user-abc-123", "full_name": "John Doe"}'

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

vendor_data is required and must be unique per application. Attempting to create a duplicate returns a conflict error — use PATCH /v3/users/{vendor_data}/ to update an existing user.

Fields that are normally derived from verified sessions (full_name, date_of_birth) can be seeded here but may be overwritten by the first approved User Verification (KYC) session.

Face images are not accepted by this endpoint. To attach a trusted imported face, use

POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/

after this endpoint returns didit_internal_id.

Creating a user emits a user.data.updated webhook.

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; matching is case-insensitive after normalisation.

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

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

Arbitrary JSON object you attach to the user.

approved_emails

object

Pre-trusted emails for this user (e.g. {"john@example.com": true}).

Show child attributes

approved_phones

object

Pre-trusted phone numbers for this user.

Show child attributes

issuing_states

object

Pre-recorded issuing-country counts (ISO 3166-1 alpha-3 keys), e.g. {"USA": 1}.

Show child attributes

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>

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

Show child attributes

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

Overview

User and Business Verifications

Lists

Workflows

Questionnaires

Users

Businesses

Transactions

Session Operations

Webhook

Billing

Management API Overview

Auth API (Programmatic)

Identity & Documents

Database Validation

Biometrics & Face

Compliance & Risk

Email Verification

Phone Verification

Overview

When to use it

Notes

Permissions

Authorizations

Body

Response

Overview

User and Business Verifications

Lists

Workflows

Questionnaires

Users

Businesses

Transactions

Session Operations

Webhook

Billing

Management API Overview

Auth API (Programmatic)

Identity & Documents

Database Validation

Biometrics & Face

Compliance & Risk

Email Verification

Phone Verification

Documentation Index

​Overview

​When to use it

​Notes

​Permissions

​Related

Authorizations

Body

Response

Overview

When to use it

Notes

Permissions

Related