Didit Identity Verification Platform
The single skill for the entire Didit verification platform. Covers account creation, session management, workflow configuration, questionnaires, user management, billing, blocklist, and webhook configuration — 45+ endpoints across 9 categories.
For standalone verification APIs (ID scan, liveness, face match, AML, etc.), see the individual didit-* skills.
API Reference Links:
Getting Started — Zero to Verifying
Go from nothing to a live verification link in 4 API calls, no browser needed:
CODEBLOCK0
To add credits: GET /v3/billing/balance/ to check, POST /v3/billing/top-up/ with {"amount_in_dollars": 50} for a Stripe checkout link.
Authentication
Two auth schemes are used across the platform:
| Endpoints | Auth | Header |
|---|
| Register, Verify Email, Login | None | (unauthenticated) |
| List Organizations, Get Credentials |
Bearer |
Authorization: Bearer <access_token> |
| Everything else (sessions, workflows, etc.) |
API Key |
x-api-key: <api_key> |
Get your api_key via programmatic registration (above) or from Didit Business Console → API & Webhooks.
Account Setup
Base URL: INLINECODE7
1. Register
CODEBLOCK1
| Body | Type | Required | Description |
|---|
| INLINECODE8 | string | Yes | Any email address |
| INLINECODE9 |
string |
Yes | Min 8 chars, 1 upper, 1 lower, 1 digit, 1 special |
Response (201): INLINECODE10
Rate limit: 5 per IP per hour.
2. Verify Email & Get Credentials
CODEBLOCK2
| Body | Type | Required | Description |
|---|
| INLINECODE11 | string | Yes | Same email from register |
| INLINECODE12 |
string |
Yes | 6-character alphanumeric OTP from email |
Response (200):
CODEBLOCK3
application.api_key is the x-api-key for all subsequent calls.
3. Login (Existing Accounts)
CODEBLOCK4
| Body | Type | Required | Description |
|---|
| INLINECODE15 | string | Yes | Account email |
| INLINECODE16 |
string |
Yes | Account password |
Response (200): INLINECODE17
Progressive lockout: 5 fails = 15min, 10 = 1hr, 20 = 24hr.
4. List Organizations
CODEBLOCK5
Auth: INLINECODE18
Response (200): Array of INLINECODE19
5. Get Application Credentials
CODEBLOCK6
Auth: INLINECODE20
Response (200): {"uuid": "...", "client_id": "...", "api_key": "..."}
Workflows
Base URL: INLINECODE22
Workflows define verification steps, thresholds, and accepted documents. Each has a UUID used as workflow_id when creating sessions.
Workflow Types:
| Type | Purpose | Typical Features |
|---|
| INLINECODE24 | Full identity verification (ID + selfie) | ID Verification, Liveness, Face Match, AML, NFC |
| INLINECODE25 |
Age gating with ID fallback for borderline cases | Age Estimation, Liveness, per-country age restrictions |
|
biometric_authentication | Re-verify returning users (no document) | Liveness, Face Match against stored portrait |
|
address_verification | Verify proof of address documents | Proof of Address, geocoding, name matching |
|
questionnaire_verification | Custom form/questionnaire verification | Questionnaire, optional ID/liveness add-ons |
|
email_verification | Email OTP verification as a workflow | Email send/check, breach/disposable detection |
|
phone_verification | Phone OTP verification as a workflow | Phone send/check, carrier/VoIP detection |
Features (toggleable per workflow): ID Verification, Liveness, Face Match, NFC, AML, Phone, Email, Proof of Address, Database Validation, IP Analysis, Age Estimation, Questionnaire.
1. List Workflows
CODEBLOCK7
Response (200): Array of workflow objects with uuid, workflow_label, workflow_type, is_default, features, total_price.
2. Create Workflow
CODEBLOCK8
| Body | Type | Default | Description |
|---|
| INLINECODE37 | string | auto | Display name |
| INLINECODE38 |
string |
kyc | Workflow template type |
|
is_default | boolean |
false | Set as default |
|
is_liveness_enabled | boolean |
false | Liveness detection |
|
face_liveness_method | string |
passive |
"passive",
"active_3d",
"flashing" |
|
face_liveness_score_decline_threshold | integer |
50 | Below this → auto-decline |
|
is_face_match_enabled | boolean |
false | Selfie-to-document match |
|
face_match_score_decline_threshold | integer |
50 | Below this → auto-decline |
|
face_match_score_review_threshold | integer |
70 | Below this → manual review |
|
is_aml_enabled | boolean |
false | AML/PEP/sanctions screening |
|
aml_decline_threshold | integer |
80 | Above this → auto-decline |
|
is_phone_verification_enabled | boolean |
false | Phone verification step |
|
is_email_verification_enabled | boolean |
false | Email verification step |
|
is_database_validation_enabled | boolean |
false | Gov database validation |
|
is_ip_analysis_enabled | boolean |
false | IP risk analysis |
|
is_nfc_enabled | boolean |
false | NFC chip reading (mobile only, ePassports) |
|
is_age_restrictions_enabled | boolean |
false | Enable per-country age restrictions (for
adaptive_age_verification) |
|
documents_allowed | object |
{} | Restrict accepted countries/doc types (empty = accept all) |
|
duplicated_user_action | string |
no_action |
no_action,
review,
decline (set after creation via update) |
|
max_retry_attempts | integer |
3 | Max retries per session |
|
retry_window_days | integer |
7 | Days within which retries are allowed |
Response (201): Workflow object with uuid.
CODEBLOCK9
3. Get Workflow
CODEBLOCK10
4. Update Workflow
CODEBLOCK11
Partial update — only send fields to change.
5. Delete Workflow
CODEBLOCK12
Response: 204 No Content. Existing sessions are not affected.
Sessions
Base URL: INLINECODE87
Sessions are the core unit of verification. Every verification starts by creating a session linked to a workflow.
Lifecycle: INLINECODE88
Statuses: Not Started, In Progress, In Review, Approved, Declined, Abandoned, Expired, INLINECODE96
Rate limits: 300 req/min per method. Session creation: 600/min. Decision polling: 100/min.
1. Create Session
CODEBLOCK13
| Body | Type | Required | Description |
|---|
| INLINECODE97 | uuid | Yes | Workflow UUID |
| INLINECODE98 |
string | No | Your user identifier |
|
callback | url | No | Redirect URL (Didit appends
verificationSessionId +
status) |
|
callback_method | string | No |
"initiator",
"completer", or
"both" |
|
metadata | JSON string | No | Custom data stored with session |
|
language | string | No | ISO 639-1 UI language |
|
contact_details.email | string | No | Pre-fill email for email verification step |
|
contact_details.phone | string | No | Pre-fill phone (E.164) for phone verification step |
|
contact_details.send_notification_emails | boolean | No | Send status update emails to user |
|
contact_details.email_lang | string | No | Language for email notifications (ISO 639-1) |
|
expected_details.first_name | string | No | Triggers mismatch warning if different (fuzzy match) |
|
expected_details.last_name | string | No | Expected last name (fuzzy match) |
|
expected_details.date_of_birth | string | No |
YYYY-MM-DD |
|
expected_details.gender | string | No |
"M",
"F", or
null |
|
expected_details.nationality | string | No | ISO 3166-1 alpha-3 country code |
|
expected_details.id_country | string | No | ISO alpha-3 for expected ID document country (overrides nationality) |
|
expected_details.poa_country | string | No | ISO alpha-3 for expected PoA document country |
|
expected_details.address | string | No | Expected address (human-readable, for PoA matching) |
|
expected_details.identification_number | string | No | Expected document/personal/tax number |
|
expected_details.ip_address | string | No | Expected IP address (logs warning if different) |
|
portrait_image | base64 | No | Reference portrait for Biometric Auth (max 1MB) |
Response (201):
CODEBLOCK14
Send the user to url to complete verification.
2. Retrieve Session (Get Decision)
CODEBLOCK15
Returns all verification results. Image URLs expire after 60 minutes.
Response (200): Full decision with status, features, id_verifications, liveness_checks, face_matches, aml_screenings, phone_verifications, email_verifications, poa_verifications, database_validations, ip_analyses, reviews.
3. List Sessions
CODEBLOCK16
| Query | Type | Default | Description |
|---|
| INLINECODE140 | string | — | Filter by your user identifier |
| INLINECODE141 |
string | — | Filter by status (e.g.
Approved,
Declined,
In Review) |
|
country | string | — | Filter by ISO 3166-1 alpha-3 country code |
|
workflow_id | string | — | Filter by workflow UUID |
|
offset | integer |
0 | Number of items to skip |
|
limit | integer |
20 | Max items to return |
Response (200): Paginated list with count, next, previous, results[].
4. Delete Session
CODEBLOCK17
Response: 204 No Content. Permanently deletes all associated data.
5. Batch Delete Sessions
CODEBLOCK18
| Body | Type | Description |
|---|
| INLINECODE156 | array | List of session numbers to delete |
| INLINECODE157 |
boolean | Delete all sessions (use with caution) |
6. Update Session Status
CODEBLOCK19
| Body | Type | Required | Description |
|---|
| INLINECODE158 | string | Yes | INLINECODE159 , "Declined", or INLINECODE161 |
| INLINECODE162 |
string | No | Reason for change |
|
send_email | boolean | No | Send notification email |
|
email_address | string | Conditional | Required when
send_email is
true |
|
email_language | string | No | Email language (default:
"en") |
|
nodes_to_resubmit | array | No | For Resubmitted:
[{"node_id": "feature_ocr", "feature": "OCR"}] |
Resubmit requires session to be Declined, In Review, or Abandoned.
7. Generate PDF Report
CODEBLOCK20
Rate limit: 100 req/min.
8. Share Session
CODEBLOCK21
Generates a share_token for B2B KYC sharing. Only works for finished sessions.
9. Import Shared Session
CODEBLOCK22
| Body | Type | Required | Description |
|---|
| INLINECODE172 | string | Yes | Token from sharing partner |
| INLINECODE173 |
boolean |
Yes |
true: keep original status;
false: set to "In Review" |
|
workflow_id | string |
Yes | Your workflow ID |
|
vendor_data | string | No | Your user identifier |
A session can only be imported once per partner application.
10. List Session Reviews
CODEBLOCK23
Response (200): Array of review activity items:
CODEBLOCK24
11. Create Session Review
CODEBLOCK25
| Body | Type | Required | Description |
|---|
| INLINECODE178 | string | Yes | INLINECODE179 , "Declined", or INLINECODE181 |
| INLINECODE182 |
string | No | Review note |
Response (201): The created review item.
Blocklist
Block entities from a session to auto-decline future matches.
1. Add to Blocklist
CODEBLOCK26
| Body | Type | Required | Description |
|---|
| INLINECODE183 | uuid | Yes | Session to blocklist items from |
| INLINECODE184 |
boolean | No | Block biometric face template |
|
blocklist_document | boolean | No | Block document fingerprint |
|
blocklist_phone | boolean | No | Block phone number |
|
blocklist_email | boolean | No | Block email address |
Warning tags on match: FACE_IN_BLOCKLIST, ID_DOCUMENT_IN_BLOCKLIST, PHONE_NUMBER_IN_BLOCKLIST, INLINECODE191
2. Remove from Blocklist
CODEBLOCK27
Same structure with unblock_face, unblock_document, unblock_phone, unblock_email.
3. List Blocklist
CODEBLOCK28
| Query | Type | Description |
|---|
| INLINECODE196 | string | INLINECODE197 , "document", "phone", "email". Omit for all. |
Questionnaires
Custom forms attached to verification workflows. Support 7 element types: short_text, long_text, multiple_choice, checkbox, file_upload, date, number.
1. List Questionnaires
CODEBLOCK29
2. Create Questionnaire
CODEBLOCK30
| Body | Type | Required | Description |
|---|
| INLINECODE208 | string | Yes | Display title |
| INLINECODE209 |
string | No | Description shown to users |
|
default_language | string | No | Default language code |
|
languages | array | No | Supported languages |
|
form_elements | array |
Yes | Question objects |
Form element:
| Field | Type | Required | Description |
|---|
| INLINECODE213 | string | Yes | One of the 7 types above |
| INLINECODE214 |
object |
Yes | Translations:
{"en": "Question?", "es": "¿Pregunta?"} |
|
is_required | boolean | No | Mandatory answer |
|
options | array | Conditional | Required for
multiple_choice/
checkbox |
CODEBLOCK31
3. Get Questionnaire
CODEBLOCK32
4. Update Questionnaire
CODEBLOCK33
5. Delete Questionnaire
CODEBLOCK34
Response: 204 No Content.
Users
Manage verified individuals identified by vendor_data.
1. List Users
CODEBLOCK35
| Query | Type | Description |
|---|
| INLINECODE222 | string | INLINECODE223 , Declined, In Review, INLINECODE226 |
| INLINECODE227 |
string | Search by name or identifier |
|
country | string | ISO 3166-1 alpha-3 |
|
limit | integer | Results per page (max 200) |
|
offset | integer | Pagination offset |
Response (200): Paginated list with vendor_data, full_name, status, session_count, issuing_states, approved_emails, approved_phones.
2. Get User
CODEBLOCK36
3. Update User
CODEBLOCK37
| Body | Type | Description |
|---|
| INLINECODE238 | string | Custom display name |
| INLINECODE239 |
string | Manual override:
Approved,
Declined,
In Review |
|
metadata | object | Custom JSON metadata |
4. Batch Delete Users
CODEBLOCK38
| Body | Type | Description |
|---|
| INLINECODE244 | array | List of vendor_data strings |
| INLINECODE245 |
boolean | Delete all users |
Billing
1. Get Credit Balance
CODEBLOCK39
Response (200):
CODEBLOCK40
2. Top Up Credits
CODEBLOCK41
| Body | Type | Required | Description |
|---|
| INLINECODE246 | number | Yes | Minimum $50 |
| INLINECODE247 |
string | No | Redirect after payment |
|
cancel_url | string | No | Redirect on cancel |
Response (200):
CODEBLOCK42
Present checkout_session_url to the user for payment.
Webhook Configuration
Set up webhooks programmatically — no console needed.
1. Get Webhook Configuration
CODEBLOCK43
Response (200):
CODEBLOCK44
| Field | Type | Description |
|---|
| INLINECODE250 | string/null | URL where notifications are sent (null if not configured) |
| INLINECODE252 |
string |
"v1",
"v2", or
"v3" (v3 recommended) |
|
secret_shared_key | string | HMAC secret for verifying webhook signatures |
|
capture_method | string |
"mobile",
"desktop", or
"both" |
|
data_retention_months | integer/null | Months to retain session data (
null = unlimited) |
2. Update Webhook Configuration
CODEBLOCK45
| Body | Type | Required | Description |
|---|
| INLINECODE263 | string/null | No | URL for notifications (set null to disable) |
| INLINECODE265 |
string | No |
"v1",
"v2", or
"v3" |
|
rotate_secret_key | boolean | No |
true to generate a new secret (old one immediately invalidated) |
|
capture_method | string | No |
"mobile",
"desktop", or
"both" |
|
data_retention_months | integer/null | No | 1–120 months, or
null for unlimited |
Example — set webhook URL:
CODEBLOCK46
Example — rotate secret:
CODEBLOCK47
Example — disable webhooks:
CODEBLOCK48
Response (200): Same shape as GET — returns the updated configuration.
Webhook Events & Signatures
Didit sends POST requests to your webhook URL when session status changes. Retries up to 2 times with exponential backoff (1 min, 4 min).
Payload
CODEBLOCK49
Event types: status.updated (status change), data.updated (KYC/POA data manually updated).
Signature Verification (V2 — recommended)
Two headers: X-Signature-V2 (HMAC-SHA256 hex) and X-Timestamp (Unix seconds).
CODEBLOCK50
Simple Signature (Fallback)
Header: X-Signature-Simple — HMAC of key fields only.
CODEBLOCK51
Error Responses (All Endpoints)
| Code | Meaning | Action |
|---|
| INLINECODE283 | Invalid request | Check required fields and formats |
| INLINECODE284 |
Invalid or missing API key | Verify
x-api-key header |
|
403 | Insufficient credits or no permission | Check balance, API key permissions |
|
404 | Resource not found | Verify IDs |
|
429 | Rate limited | Check
Retry-After header, exponential backoff |
Common Workflows
Full KYC Onboarding
CODEBLOCK52
Programmatic Review + Blocklist
CODEBLOCK53
B2B KYC Sharing
CODEBLOCK54
Check Balance Before Sessions
CODEBLOCK55
Questionnaire + Workflow
CODEBLOCK56
Utility Scripts
setup_account.py — Register and verify accounts
CODEBLOCK57
manage_workflows.py — CRUD workflows
CODEBLOCK58
create_session.py — Create verification sessions
CODEBLOCK59
All scripts can be imported as libraries:
CODEBLOCK60
