Skip to main content
Core User entity management happens through public endpoints under /v3/users/. Profile attachments, such as imported face upload, use the organization/application path with didit_internal_id. This page gives you the conceptual walkthrough — see the API reference for full request / response schemas.

​
List users

GET /v3/users/ Returns a paginated list of users for your application. Supports filters on status, search, date range, and more. 
curl -G https://verification.didit.me/v3/users/ \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "status=ACTIVE" \
  --data-urlencode "search=jane" \
  --data-urlencode "page_size=50"
Use-cases:
  • Sync a subset of users to your data warehouse each day.
  • Find flagged users for an analyst queue.
  • Search users by display name.

​
Get a user

GET /v3/users/{vendor_data}/ Retrieve a single user by vendor_data. Returns the full data model including aggregated counters. 
curl https://verification.didit.me/v3/users/user-42/ \
  -H "x-api-key: YOUR_API_KEY"
vendor_data in the URL is case-sensitive. Always pass the exact value you used on session creation.

​
Create a user

POST /v3/users/create/ Create a User entity before any session runs. Useful for:
  • Seeding metadata or custom fields before the customer verifies.
  • Setting an initial status (e.g. FLAGGED while your onboarding team reviews manual documents).
  • Pre-loading users from an existing database so you have a complete roster from day one.
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-42",
    "display_name": "Jane Doe",
    "metadata": { "tier": "premium", "signup_source": "web" }
  }'
If a user with that vendor_data already exists, the call returns a conflict error — use PATCH to update instead.

​
Upload an imported face

POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/ Attach a trusted face image to an existing User profile. This is the right follow-up when you import users from another provider and want Didit to carry their face evidence before the first Didit session. 
# First create or retrieve the User and read didit_internal_id from the response.
curl -X POST https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/$DIDIT_INTERNAL_ID/faces/upload/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "<base64-encoded-jpg-or-png>",
    "comment": "Imported from previous KYC provider"
  }'
See Upload User Face for request fields, limits, list/delete endpoints, and the blocklist distinction.

​
Update a user

PATCH /v3/users/{vendor_data}/ Update mutable profile fields. Most fields derived from verified sessions are read-only — attempting to change them via PATCH will either be ignored or flagged in the audit log. Mutable fields: display_name, metadata, tags. Read-only after verification: full_name, date_of_birth, portrait_image, all aggregate counters, features map. 
curl -X PATCH https://verification.didit.me/v3/users/user-42/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "tier": "enterprise" } }'
Emits a user.data.updated webhook with the changed_fields array.

​
Change status

PATCH /v3/users/{vendor_data}/update-status/ Move a user between ACTIVE, FLAGGED, and BLOCKED. Status changes propagate to future sessions and transactions. 
curl -X PATCH https://verification.didit.me/v3/users/user-42/update-status/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "BLOCKED",
    "reason": "Chargeback fraud pattern detected"
  }'
From → toCommon trigger
ACTIVE → FLAGGEDTransaction rule, analyst review, ongoing AML hit
ACTIVE → BLOCKEDConfirmed fraud, session declined with auto-block, blocklist match
FLAGGED → ACTIVEAnalyst cleared review
BLOCKED → ACTIVEManual unblock by an analyst
Emits a user.status.updated webhook.

​
Delete users (batch)

POST /v3/users/delete/ Delete one or more users. History (sessions, transactions, audit trail) is retained for your configured data retention period, then hard-deleted. 
curl -X POST https://verification.didit.me/v3/users/delete/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data": ["user-42", "user-43", "user-44"]
  }'
Returns a per-item result so you can detect which items did not exist or could not be deleted.

​
Permission model

All /v3/users/* endpoints are scoped by the users permission resource. Your API key’s role determines which operations are allowed:
Rolelistgetcreateupdateupdate-statusdelete
OWNER✅✅✅✅✅✅
ADMIN✅✅✅✅✅✅
COMPLIANCE_OFFICER✅✅❌✅✅❌
DEVELOPER✅✅✅❌❌❌
READER✅✅❌❌❌❌
See Roles & permissions for the full matrix.

​
Rate limits and idempotency

  • All /v3/users/* endpoints are subject to the standard rate limits.
  • create is not idempotent — retrying with the same vendor_data returns a conflict. De-dupe on your side, or always GET first.
  • delete is idempotent — deleting an already-deleted user is a no-op.

​
Webhooks fired by these operations

OperationWebhook
createuser.data.updated
updateuser.data.updated (with changed_fields)
update-statususer.status.updated
deleteuser.data.updated (with deleted_at set)

​
Next steps

Data model

Full field reference.

List API

GET /v3/users/ schema.

Create API

POST /v3/users/create/ schema.

Upload face

Attach imported face images to User profiles.