Create User - Didit Documentation

curl

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

POST

users

create

curl

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

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

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.

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; 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

​When to use it

​Notes

​Permissions

​Related

Authorizations

Body

Response

Overview

When to use it

Notes

Permissions

Related