User Operations

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 → to	Common trigger
`ACTIVE` → `FLAGGED`	Transaction rule, analyst review, ongoing AML hit
`ACTIVE` → `BLOCKED`	Confirmed fraud, session declined with auto-block, blocklist match
`FLAGGED` → `ACTIVE`	Analyst cleared review
`BLOCKED` → `ACTIVE`	Manual unblock by an analyst

Emits a user.status.updated webhook.

Delete users (batch)

POST /v3/users/delete/ Delete one or more users. The user records are removed permanently, together with every biometric template retained for them after session deletion. Their verification sessions are not covered by this endpoint and survive with their link to the user cleared; delete them with Delete Session or Batch Delete Sessions. Transactions are not covered either; delete those from the Console.

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_list": ["user-42", "user-43", "user-44"]
  }'

Returns a count, {"deleted": <int>}, not a per-item result. Identifiers that matched nothing are skipped silently, so send a de-duplicated list if you want to compare deleted against the number of identifiers you sent.

Permission model

All /v3/users/* endpoints are scoped by the users permission resource. Your API key’s role determines which operations are allowed:

Role	list	get	create	update	update-status	delete
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

Operation	Webhook
`create`	none for the create call itself — the first `user.data.updated` arrives when a session or an update first fills the profile
`update`	`user.data.updated` (with `changed_fields`)
`update-status`	`user.status.updated`
`delete`	none — record the deletion on your own side if you need to react to it

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.

Overview

Pricing

Workflows & Verification

Review & Operations

Entities (Users & Businesses)

Settings & Customization

Security & Compliance

Didit Academy

Resources

List users

Get a user

Create a user

Upload an imported face

Update a user

Change status

Delete users (batch)

Permission model

Rate limits and idempotency

Webhooks fired by these operations

Next steps

Data model

List API

Create API

Upload face

​List users

​Get a user

​Create a user

​Upload an imported face

​Update a user

​Change status

​Delete users (batch)

​Permission model

​Rate limits and idempotency

​Webhooks fired by these operations

​Next steps

Data model

List API

Create API

Upload face

List users

Get a user

Create a user

Upload an imported face

Update a user

Change status

Delete users (batch)

Permission model

Rate limits and idempotency

Webhooks fired by these operations

Next steps