Management API (v3) - Didit Documentation

Authentication

All management API endpoints use your application API key. No org/app UUIDs are needed in URLs — the application is identified from your key.

curl -H "x-api-key: YOUR_API_KEY" https://verification.didit.me/v3/...

Don’t have an API key yet? Register programmatically in 2 API calls.

Workflows

Workflows define what verification steps your users go through (ID scan, liveness, face match, AML screening, etc.). Each workflow is a reusable configuration you attach to sessions.

GET

List all workflows for your application. Returns each workflow’s features, thresholds, and whether it’s the default.

POST

Create a new workflow. Define which verification features to enable, set thresholds, configure accepted document types, and more.

GET

Get full details of a specific workflow, including all feature configurations and thresholds.

PATCH

Update a workflow configuration. You can modify any feature settings, thresholds, or accepted documents.

DELETE

Delete a workflow. Sessions already using this workflow are not affected.

We strongly recommend using the Business Console to create and configure workflows. The visual workflow builder provides templates, drag-and-drop feature configuration, document settings, threshold tuning, and preview — all without writing code. Use the API only for automation or programmatic management of workflows.

Quick Example: Create a Workflow

The workflow_type determines the base feature set. Individual features are then toggled with is_*_enabled flags.

curl -X POST https://verification.didit.me/v3/workflows/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_label": "Standard KYC",
    "workflow_type": "kyc",
    "is_default": true,
    "is_face_match_enabled": true,
    "is_liveness_enabled": true,
    "is_aml_enabled": false
  }'

Available workflow_type values: kyc, kyb, adaptive_age_verification, biometric_authentication, address_verification, questionnaire_verification, email_verification, phone_verification. For kyc workflows, ID verification is automatically included — you don’t need a separate flag for it. Use the is_*_enabled flags to add or remove optional features like face match, liveness, AML, NFC, phone, email, proof of address, Device & IP Analysis, and more. Then use the workflow when creating sessions:

curl -X POST https://verification.didit.me/v3/session/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "callback_url": "https://myapp.com/callback",
    "workflow_id": "WORKFLOW_UUID_FROM_ABOVE"
  }'

Questionnaires

Custom forms you can add to verification workflows to collect additional information from users.

GET

List all questionnaires.

POST

Create a new questionnaire with custom questions, branching logic, and translations.

GET

Get questionnaire details including all questions and form structure.

PATCH

Update a questionnaire.

DELETE

Delete a questionnaire.

Users

Manage verified individuals (users) in your application. Each user is identified by a vendor_data string you provide when creating sessions.

GET

List all users for your application, including their verification status and session history.

GET

Get user details by your vendor_data identifier.

PATCH

Update user metadata.

POST

Batch delete users. Body: {"vendor_data_list": ["user-1", "user-2"]} or {"delete_all": true}. Also purges every biometric template retained for those users.

Biometric Templates

Image-free face biometric templates an opted-in application retains after deleting sessions. See Biometric templates.

GET

Paginated list with filters (vendor_data, vendor_user_uuid, status, source_type, retained_from, retained_to, ordering).

GET

Count with the same filters.

GET

One template: owning User, provenance reference, expiry, instruction, status.

DELETE

Purge one template. Returns {"uuid": "...", "outcome": "purged" | "already_purged"}.

POST

Bulk purge. Body: {"template_uuids": [...]} or {"delete_all": true} plus optional filters.

Session Operations

POST

Batch delete sessions. Requires delete:sessions. Body: {"session_numbers": ["1", "2", "3"]} or {"delete_all": true}, plus optional retain_face_embeddings, face_retention_days, face_retention_deadline, deletion_instruction, and instruction_id. Up to 20 matching sessions return 200 with a per-session face_retention_outcome; more return 202 with a deletion job.

GET

Progress and outcome counts of a bulk session deletion that returned 202.

GET

List reviews and activity log for a session.

POST

Add a review note or status change to a session.

Billing

GET

Get current credit balance and auto-refill settings.

{
  "balance": "142.5000",
  "auto_refill_enabled": true,
  "auto_refill_amount": "100.0000",
  "auto_refill_threshold": "10.0000"
}

POST

Create a Stripe checkout session to top up credits. Minimum $50.

{
  "amount_in_dollars": 100,
  "success_url": "https://myapp.com/billing/success",
  "cancel_url": "https://myapp.com/billing/cancel"
}

Lists (Blocklists, Allowlists & Custom)

Manage typed lists for blocklisting, allowlisting, and custom workflow conditions. See the full Lists API documentation.

GET

List all lists for the application (blocklists, allowlists, custom).

POST

Add an entry to a list. Supports reference_session_id to auto-extract data from a session, and reference_object_uuid for traceability to transactions/users/businesses.

DELETE

Remove an entry from a list.

POST

Upload a face image to a face blocklist (base64).

Webhook Configuration

GET

Get current webhook configuration including URL, version, the secret key for verifying webhook signatures, and the application’s data-retention and biometric-template retention policy.

{
  "webhook_url": "https://myapp.com/webhooks/didit",
  "webhook_version": "v3",
  "secret_shared_key": "whsec_a1b2c3d4e5f6...",
  "capture_method": "both",
  "data_retention_months": null,
  "face_retention_policy": "delete_with_session",
  "face_retention_days": null,
  "allowed_return_hosts": ["app.example.com"]
}

PATCH

Update webhook URL, version, or rotate the secret key. Set rotate_secret_key: true to generate a new webhook secret (old one immediately invalidated). Also sets the application’s retention policy: data_retention_months, and face_retention_policy (delete_with_session default, or retain_until_user_deleted) together with a required finite face_retention_days (1-3650) when retention is enabled. See Biometric template retention. Also registers allowed_return_hosts: up to 20 bare hostnames (for example app.example.com, without a scheme, port, path or wildcard) that a Digital ID wallet API verification may send the person back to over HTTPS. A new list replaces the registered one, and your application’s white-label domain is always allowed.

{
  "webhook_url": "https://myapp.com/webhooks/didit",
  "webhook_version": "v3"
}

Complete API Endpoint Summary

Endpoint	Method	Description
`/v3/session/`	POST	Create a verification session
`/v3/sessions/`	GET	List all sessions
`/v3/session/{id}/decision/`	GET	Get session verification result
`/v3/session/{id}/update-status/`	PATCH	Approve or decline a session
`/v3/session/{id}/delete/`	DELETE	Delete a single session
`/v3/sessions/delete/`	POST	Batch delete sessions
`/v3/sessions/delete/{job_id}/`	GET	Bulk session deletion job status
`/v3/sessions/{id}/reviews/`	GET, POST	Session activity/reviews
`/v3/workflows/`	GET, POST	List/create workflows
`/v3/workflows/{id}/`	GET, PATCH, DELETE	Workflow detail/update/delete
`/v3/questionnaires/`	GET, POST	List/create questionnaires
`/v3/questionnaires/{id}/`	GET, PATCH, DELETE	Questionnaire detail
`/v3/users/`	GET	List verified users
`/v3/users/{vendor_data}/`	GET, PATCH	User detail/update
`/v3/users/delete/`	POST	Batch delete users (also purges their retained biometric templates)
`/v3/biometric-templates/`	GET	List retained biometric templates
`/v3/biometric-templates/count/`	GET	Count retained biometric templates
`/v3/biometric-templates/{id}/`	GET, DELETE	Template detail / purge
`/v3/biometric-templates/delete/`	POST	Bulk purge templates
`/v3/lists/`	GET, POST	List all lists / create list
`/v3/lists/{id}/`	GET, PATCH, DELETE	List detail / update / delete
`/v3/lists/{id}/entries/`	GET, POST	List entries / add entry
`/v3/lists/{id}/entries/{eid}/`	DELETE	Remove entry
`/v3/lists/{id}/entries/face-upload/`	POST	Upload face to blocklist
`/v3/webhook/`	GET, PATCH	Webhook configuration (URL, secret, version), retention policy and wallet return hosts
`/v3/billing/balance/`	GET	Check credit balance
`/v3/billing/top-up/`	POST	Top up credits

​Authentication

​Workflows

​Quick Example: Create a Workflow

​Questionnaires

​Users

​Biometric Templates

​Session Operations

​Billing

​Lists (Blocklists, Allowlists & Custom)

​Webhook Configuration

​Complete API Endpoint Summary

Authentication

Workflows

Quick Example: Create a Workflow

Questionnaires

Users

Biometric Templates

Session Operations

Billing

Lists (Blocklists, Allowlists & Custom)

Webhook Configuration

Complete API Endpoint Summary