> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.
# Create User
> Pre-create a [user](/entities/users) by `vendor_data` *without* a verification session. `vendor_data` must be unique among non-deleted users for the application (exact match; conflicts return 400). Not idempotent.
export const AgentPromptAccordion = ({prompt, title = "AI Agent Integration Prompt"}) => {
const [copied, setCopied] = React.useState(false);
const handleCopy = e => {
e.stopPropagation();
if (!prompt) return;
navigator.clipboard.writeText(prompt.trim()).then(() => {
setCopied(true);
setTimeout(() => setCopied(false), 2000);
});
};
const agents = ["Claude Code", "Codex", "Cursor", "Devin", "Windsurf", "GitHub Copilot"];
return
{}
{title}
{}
{prompt.trim()}
{}
Paste into
{agents.map(name => {name})}
;
};
Content-Type: application/json
Request body fields:
- vendor_data (string, REQUIRED) — your unique identifier for this user. Free-form string, NOT a UUID. Must be unique among non-deleted users in the app. Normalised lowercase + whitespace trim, so "USER-1" and "user-1" collide.
- full_name (string, max 512, optional)
- display_name (string, optional) — friendly label for the Console (takes precedence over full_name for UI).
- date_of_birth (string YYYY-MM-DD, optional)
- status (enum, optional) — "ACTIVE" | "FLAGGED" | "BLOCKED" (VendorUserStatusChoices). Defaults to "ACTIVE".
- metadata (object, optional) — arbitrary JSON you attach to the user.
- approved_emails (object, optional) — e.g. {"john@example.com": true}.
- approved_phones (object, optional).
- issuing_states (object, optional) — e.g. {"USA": 1}.
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"}'
Response 201: full UserDetailItem (same shape as GET /v3/users/{vendor_data}/). Includes didit_internal_id (UUID), session_count=0, approved_count=0, metadata, comments=[], created_at, updated_at. See /reference/data-models.
Failure modes:
- 400 — validation errors keyed by field. Common cases:
{ "vendor_data": ["A user with this vendor_data already exists."] } // conflict — NOT idempotent. Use PATCH /v3/users/{vendor_data}/ to update.
{ "vendor_data": ["This field is required."] }
{ "metadata": ["Metadata must be a JSON object."] }
- 401 — missing or invalid x-api-key. { "detail": "Authentication credentials were not provided." }
- 403 — key valid but lacks create:users. { "detail": "You do not have permission to perform this action." }
- 429 — rate-limited.
Upsert pattern (this endpoint is NOT idempotent):
GET /v3/users/{vendor_data}/ → on 404, POST /v3/users/create/; on 200, PATCH /v3/users/{vendor_data}/.
Notes:
- Verified-session-derived identity fields such as full_name and date_of_birth seeded here can be overwritten by the first approved User Verification (KYC) session.
- If you are migrating from another provider and already have a trusted face image, create the User first, read didit_internal_id from this response, then call POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/.
- Creating a user emits a user.data.updated webhook.
For end-to-end Didit integration, paste in the full prompt at /integration/integration-prompt.`}
/>
## Overview
Explicitly creates a [User entity](/entities/users/overview) 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](/management-api/users/upload-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}/`](/management-api/users/update) 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/`](/management-api/users/upload-face) after this endpoint returns `didit_internal_id`.
* Creating a user emits a `user.data.updated` webhook.
## Permissions
Role must grant `create:users`.
## Related
* [User data model](/entities/users/data-model)
* [Upload User Face](/management-api/users/upload-face)
* [Vendor data linking](/entities/vendor-data-linking)
* [User operations](/entities/users/operations)
## OpenAPI
````yaml POST /v3/users/create/
openapi: 3.0.0
info:
version: 3.0.0
title: Didit Verification API
description: Identity verification API. Authenticate with x-api-key header.
servers:
- url: https://verification.didit.me
security: []
tags: []
paths:
/v3/users/create/:
post:
tags:
- Users
summary: Create user
description: >-
Pre-create a [user](/entities/users) by `vendor_data` *without* a
verification session. `vendor_data` must be unique among non-deleted
users for the application (exact match; conflicts return 400). Not
idempotent.
operationId: create_user
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- vendor_data
properties:
vendor_data:
type: string
description: >-
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:
type: string
nullable: true
maxLength: 512
description: Full legal name of the user.
display_name:
type: string
nullable: true
description: >-
Friendly display name shown in the console (takes precedence
over `full_name` for UI display).
maxLength: 255
date_of_birth:
type: string
format: date
nullable: true
description: Date of birth in `YYYY-MM-DD` format.
status:
type: string
enum:
- ACTIVE
- FLAGGED
- BLOCKED
default: ACTIVE
description: Initial lifecycle status. Defaults to `ACTIVE`.
metadata:
type: object
nullable: true
description: >-
Arbitrary JSON object you attach to the user. Defaults to
`{}`.
approved_emails:
type: array
items:
type: string
description: >-
Pre-trusted email addresses for this user, e.g.
`["john@example.com"]`.
approved_phones:
type: array
items:
type: string
description: >-
Pre-trusted phone numbers for this user, e.g.
`["+14155551234"]`.
issuing_states:
type: array
items:
type: string
description: >-
Pre-recorded issuing countries (ISO 3166-1 alpha-3), e.g.
`["USA"]`.
examples:
Basic:
summary: Create with basic info
value:
vendor_data: user-abc-123
full_name: John Doe
Full:
summary: All fields
value:
vendor_data: user-abc-456
full_name: Jane Smith
display_name: Jane S.
date_of_birth: '1990-05-15'
status: ACTIVE
metadata:
tier: premium
source: api
approved_emails:
- jane@example.com
responses:
'201':
description: User created. Full user record returned (same shape as Get User).
content:
application/json:
schema:
$ref: '#/components/schemas/UserDetailItem'
examples:
Created:
value:
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
metadata: {}
portrait_image_url: null
session_count: 0
approved_count: 0
declined_count: 0
in_review_count: 0
issuing_states: []
approved_emails: []
approved_phones: []
features: {}
features_list: []
last_session_at: null
last_activity_at: '2025-06-15T10:30:00Z'
first_session_at: null
tags: []
comments: []
created_at: '2025-06-15T10:30:00Z'
updated_at: '2025-06-15T10:30:00Z'
'400':
description: >-
Invalid body — typically a duplicate `vendor_data`, a missing
required field, or a malformed value.
content:
application/json:
examples:
Duplicate:
value:
vendor_data:
- A user with this vendor_data already exists.
Missing vendor_data:
value:
vendor_data:
- This field is required.
Bad metadata:
value:
metadata:
- Metadata must be a JSON object.
Bad status:
value:
status:
- >-
Invalid status. Valid options are: ACTIVE, FLAGGED,
BLOCKED
'401':
description: >-
No credentials supplied. Requests to `/v3/users/*` paths without an
`x-api-key` header (or `Authorization: Bearer` token) are rejected
by the authentication middleware before reaching the API.
content:
application/json:
examples:
Missing credentials:
value:
detail: >-
You must be authenticated with a valid access token to
access this endpoint.
'403':
description: >-
Invalid or revoked API key, or the key cannot create users for this
application. Note: on this endpoint an *invalid* key returns `403`
(not `401`).
content:
application/json:
examples:
Forbidden:
value:
detail: You do not have permission to perform this action.
'429':
description: >-
Rate limit exceeded; back off and retry after the interval indicated
in `Retry-After`.
content:
application/json:
examples:
Rate limited:
value:
detail: Request was throttled. Expected available in 30 seconds.
security:
- ApiKeyAuth: []
x-codeSamples:
- lang: curl
label: curl
source: |-
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"}'
- lang: python
label: Python
source: |-
import requests
resp = requests.post(
'https://verification.didit.me/v3/users/create/',
headers={'x-api-key': 'YOUR_API_KEY', 'Content-Type': 'application/json'},
json={'vendor_data': 'user-abc-123', 'full_name': 'John Doe'},
)
resp.raise_for_status()
user = resp.json()
print(user['didit_internal_id'])
- lang: javascript
label: JavaScript
source: >-
const resp = await
fetch('https://verification.didit.me/v3/users/create/', {
method: 'POST',
headers: { 'x-api-key': process.env.DIDIT_API_KEY, 'Content-Type': 'application/json' },
body: JSON.stringify({ vendor_data: 'user-abc-123', full_name: 'John Doe' }),
});
const user = await resp.json();
console.log(user.didit_internal_id);
components:
schemas:
UserDetailItem:
type: object
description: >-
Full user detail. Extends UserListItem with metadata, comments, and
updated_at.
allOf:
- $ref: '#/components/schemas/UserListItem'
- type: object
properties:
metadata:
type: object
description: >-
Custom metadata JSON you attached to this user. Defaults to
`{}`.
tags:
type: array
description: >-
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.
items:
type: object
properties:
uuid:
type: string
format: uuid
description: UUID of the tag assignment (not the tag itself).
tag:
type: object
properties:
uuid:
type: string
format: uuid
name:
type: string
color:
type: string
description:
type: string
nullable: true
source:
type: string
enum:
- didit
- custom
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
added_by_email:
type: string
nullable: true
added_by_name:
type: string
nullable: true
created_at:
type: string
format: date-time
comments:
type: array
items:
type: object
properties:
uuid:
type: string
format: uuid
comment_type:
type: string
enum:
- COMMENT
- STATUS_CHANGED
- METADATA_UPDATED
- TAG_ADDED
- TAG_REMOVED
- PROFILE_UPDATED
comment:
type: string
nullable: true
actor_email:
type: string
nullable: true
actor_name:
type: string
nullable: true
previous_status:
type: string
nullable: true
enum:
- ACTIVE
- FLAGGED
- BLOCKED
- null
new_status:
type: string
nullable: true
enum:
- ACTIVE
- FLAGGED
- BLOCKED
- null
previous_value:
type: object
nullable: true
description: Previous field values for PROFILE_UPDATED entries.
new_value:
type: object
nullable: true
description: New field values for PROFILE_UPDATED entries.
changed_fields:
type: array
items:
type: string
description: Names of the fields changed by a PROFILE_UPDATED entry.
metadata:
type: object
nullable: true
mentioned_emails:
type: array
items:
type: string
created_at:
type: string
format: date-time
description: >-
Activity log and comments for this user (status changes, profile
edits, manual notes).
updated_at:
type: string
format: date-time
UserListItem:
type: object
description: A verified user.
properties:
didit_internal_id:
type: string
format: uuid
description: Didit's stable internal UUID for this user.
vendor_data:
type: string
nullable: true
description: >-
Your unique identifier for this user (passed when creating
sessions). This can be null when no vendor identifier was supplied.
display_name:
type: string
nullable: true
description: Custom display name set by you
full_name:
type: string
nullable: true
description: Full name extracted from verified documents
date_of_birth:
type: string
format: date
nullable: true
effective_name:
type: string
nullable: true
description: 'Best available name: display_name if set, otherwise full_name'
status:
type: string
enum:
- ACTIVE
- FLAGGED
- BLOCKED
description: >-
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`.
portrait_image_url:
type: string
nullable: true
description: >-
Presigned URL of the user's portrait photo (expires after a few
hours)
session_count:
type: integer
description: Total number of verification sessions for this user
approved_count:
type: integer
description: Number of approved sessions
declined_count:
type: integer
description: Number of declined sessions
in_review_count:
type: integer
description: Number of sessions in review
issuing_states:
type: array
items:
type: string
description: >-
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:
type: array
items:
type: string
description: >-
Verified email addresses collected from this user's approved
sessions, e.g. `["john@example.com"]`.
approved_phones:
type: array
items:
type: string
description: >-
Verified phone numbers collected from this user's approved sessions,
e.g. `["+14155551234"]`.
features:
type: object
description: >-
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:
type: array
items:
type: object
properties:
feature:
type: string
status:
type: string
description: >-
Same data as `features`, as an ordered array of `{feature, status}`
objects.
last_session_at:
type: string
format: date-time
nullable: true
description: Timestamp of the most recent session
first_session_at:
type: string
format: date-time
nullable: true
description: Timestamp of the first session
last_activity_at:
type: string
format: date-time
nullable: true
description: >-
Timestamp of the most recent activity on this user (session,
transaction, status change, data edit, etc.).
tags:
type: array
items:
type: object
properties:
uuid:
type: string
format: uuid
name:
type: string
color:
type: string
description: Tags assigned to this user
created_at:
type: string
format: date-time
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
````