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 /v3/workflows/

GET

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

POST /v3/workflows/

POST

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

GET /v3/workflows/{uuid}/

GET

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

PATCH /v3/workflows/{uuid}/

PATCH

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

DELETE /v3/workflows/{uuid}/

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 /v3/questionnaires/

GET

List all questionnaires.

POST /v3/questionnaires/

POST

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

GET /v3/questionnaires/{uuid}/

GET

Get questionnaire details including all questions and form structure.

PATCH /v3/questionnaires/{uuid}/

PATCH

Update a questionnaire.

DELETE /v3/questionnaires/{uuid}/

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 /v3/users/

GET

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

GET /v3/users/{vendor_data}/

GET

Get user details by your vendor_data identifier.

PATCH /v3/users/{vendor_data}/

PATCH

Update user metadata.

POST /v3/users/delete/

POST

Batch delete users. Body: {"vendor_data_list": ["user-1", "user-2"]} or {"delete_all": true}.

Session Operations

POST /v3/sessions/delete/

POST

Batch delete sessions. Requires delete:sessions. Body: {"session_numbers": [1, 2, 3]} or {"delete_all": true}.

GET /v3/sessions/{uuid}/reviews/

GET

List reviews and activity log for a session.

POST /v3/sessions/{uuid}/reviews/

POST

Add a review note or status change to a session.

Billing

GET /v3/billing/balance/

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 /v3/billing/top-up/

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 /v3/lists/

GET

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

POST /v3/lists/{list_uuid}/entries/

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 /v3/lists/{list_uuid}/entries/{entry_uuid}/

DELETE

Remove an entry from a list.

POST /v3/lists/{list_uuid}/entries/face-upload/

POST

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

Webhook Configuration

GET /v3/webhook/

GET

Get current webhook configuration including URL, version, and the secret key for verifying webhook signatures.

{
  "webhook_url": "https://myapp.com/webhooks/didit",
  "webhook_version": "v3",
  "secret_shared_key": "whsec_a1b2c3d4e5f6...",
  "capture_method": "both",
  "data_retention_months": null
}

PATCH /v3/webhook/

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).

{
  "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/{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
`/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)
`/v3/billing/balance/`	GET	Check credit balance
`/v3/billing/top-up/`	POST	Top up credits

Top Up Credits Register Account

⌘I

​Authentication

​Workflows

​Quick Example: Create a Workflow

​Questionnaires

​Users

​Session Operations

​Billing

​Lists (Blocklists, Allowlists & Custom)

​Webhook Configuration

​Complete API Endpoint Summary

Authentication

Workflows

Quick Example: Create a Workflow

Questionnaires

Users

Session Operations

Billing

Lists (Blocklists, Allowlists & Custom)

Webhook Configuration

Complete API Endpoint Summary