didit-verification-management

Didit Identity Verification Platform

The single skill for the entire Didit verification platform. Covers account creation, session management, bulk imports, workflow configuration, questionnaires, user (KYC) and business (KYB) management, transaction monitoring, billing, branding customization, lists (block/allow), and webhook configuration — 60+ endpoints across 13 categories.

For standalone verification APIs (ID scan, liveness, face match, AML, etc.), see the individual didit-* skills.

API Reference Links:

• Account Setup: Register | Verify Email | Login | Get Credentials
• Sessions: Create | Retrieve | List | Delete | Update Status | PDF | Share | Import
• Workflows: Create | List | Get | Update | Delete
• Questionnaires: Create | List | Get | Update | Delete
• Users (KYC): List | Create | Get | Update | Update Status | Delete
• Businesses (KYB): List | Create | Get | Update | Update Status | Delete
• Transactions: List | Create | Get
• Billing: Balance | Top Up
• Customization: Get | Update
• Lists (block/allow/custom): List | Create | Get | Update | Delete | Entries | Add Entry | Upload Face | Delete Entry
• Session Operations: Batch Delete | List Reviews | Create Review
• Bulk Import: Import Verifications
• Webhook Destinations: List | Create | Get | Update | Delete
• Guides: Programmatic Registration | Webhooks | AI Agent Integration | API Overview

Getting Started — Zero to Verifying

Go from nothing to a live verification link in 4 API calls, no browser needed:

import requests
 
# 1. Register (any email, no business email required)
requests.post("https://apx.didit.me/auth/v2/programmatic/register/"

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:

Get your api_key via programmatic registration (above) or from Didit Business Console → API & Webhooks.

Account Setup

Base URL: https://apx.didit.me/auth/v2

1. Register

Response (201): {"message": "Registration successful...", "email": "..."}

Rate limit: 5 per IP per hour.

2. Verify Email & Get Credentials

Response (200):

application.api_key is the x-api-key for all subsequent calls.

3. Login (Existing Accounts)

Response (200): {"access_token": "...", "refresh_token": "...", "expires_in": 86400}

Progressive lockout: 5 fails = 15min, 10 = 1hr, 20 = 24hr.

4. List Organizations

Auth: Authorization: Bearer <access_token>

Response (200): Array of {"uuid": "...", "name": "...", "contact_email": "..."}

5. Get Application Credentials

Auth: Authorization: Bearer <access_token>

Response (200): {"uuid": "...", "client_id": "...", "api_key": "..."}

Workflows

Base URL: https://verification.didit.me/v3

Workflows define verification steps, thresholds, and accepted documents. Each has a UUID used as workflow_id when creating sessions. You compose a workflow by listing features in execution order — there is no workflow_type field on the create API (sending one returns 400). KYC vs KYB is determined by which features you include.

Feature values (use the exact uppercase strings in the features array): OCR, NFC, LIVENESS, FACE_MATCH, PROOF_OF_ADDRESS, QUESTIONNAIRE, PHONE_VERIFICATION, EMAIL_VERIFICATION, DATABASE_VALIDATION, AML, IP_ANALYSIS, AGE_ESTIMATION, KYB_REGISTRY, KYB_DOCUMENTS, KYB_KEY_PEOPLE.

Common compositions:

Ordering rule: put dependency features first — OCR before FACE_MATCH, NFC, DATABASE_VALIDATION, or any AML check that relies on document data.

1. List Workflows

Response (200): Array of workflow objects with uuid, workflow_label, workflow_type, is_default, features, total_price.

2. Create Workflow

The body is a strict whitelist — only the fields below are accepted, and any unknown key (including workflow_type or flat is_*_enabled flags) is rejected with 400. The only required field is features.

Per-feature config (see the feature configs reference): e.g. LIVENESS → face_liveness_method ("PASSIVE", "ACTIVE_3D", "FLASHING"), face_liveness_score_decline_threshold; FACE_MATCH → face_match_score_decline_threshold, face_match_score_review_threshold; AML → aml_score_approve_threshold (default 80); OCR → duplicated_user_action (no_action/review/decline), documents_allowed (omit or {} to accept all); QUESTIONNAIRE → questionnaire_uuid.

Response (201): Workflow object with uuid.

3. Get Workflow

4. Update Workflow

Partial update — only send fields to change.

5. Delete Workflow

Response: 204 No Content. Existing sessions are not affected.

Sessions

Base URL: https://verification.didit.me/v3

Sessions are the core unit of verification. Every verification starts by creating a session linked to a workflow.

Lifecycle: Create → User verifies at URL → Webhook/poll decision → Optionally update status

Statuses: Not Started, In Progress, In Review, Approved, Declined, Expired, Abandoned, Kyc Expired, Resubmitted, Awaiting User (there is no Pending status)

Rate limits: generic GET and session creation 600/min; writes 300/min; decision polling 100/min; PDF generation 50/min.

1. Create Session

Response (201):

Send the user to url to complete verification.

2. Retrieve Session (Get Decision)

Returns all verification results. Presigned image URLs expire after 4 hours.

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

Response (200): Paginated list with count, next, previous, results[].

4. Delete Session

Response: 204 No Content. Permanently deletes all associated data.

5. Batch Delete Sessions

6. Update Session Status

Resubmit requires session to be Declined, In Review, or Abandoned.

Reviewer data overrides — correct extracted data on a session (only send fields to change):

• PATCH /v3/session/{sessionId}/update-data/ — KYC/ID fields (document_type, document_number, date_of_birth, first_name, last_name, gender M/F/U, address, nationality, extra_fields, …).
• PATCH /v3/session/{sessionId}/update-poa-data/ — Proof of Address fields (document_type, issuer, issue_date, poa_address, name_on_document, …).

7. Generate PDF Report

Rate limit: 50 req/min.

8. Share Session

Generates a share_token for B2B KYC sharing. Only works for finished sessions.

9. Import Shared Session

A session can only be imported once per partner application.

10. List Session Reviews

Response (200): Array of review activity items:

11. Create Session Review

Response (201): The created review item.

Bulk Import (Migration)

Import historical verifications in bulk — e.g. migrating from another provider — from a hosted CSV or NDJSON file. All imports use Didit's canonical schema regardless of source.

There is no provider request field — all imports use Didit's canonical schema. To label where a record came from, include the optional per-row provider column in the file itself (defaults to generic, stored as metadata.imported_from).

Track and inspect jobs:

Lists (Block / Allow / Custom)

Lists drive automatic enforcement: a blocklist match auto-declines future sessions, an allowlist match fast-tracks/suppresses duplicate actions, and custom lists feed workflow conditions and monitoring rules.

• list_type: blocklist (system, auto-provisioned per entry type, immutable — you can't create or delete these) · allowlist · custom
• entry_type: face, document, phone, email, ip_address, device_fingerprint, wallet_address, bank_account, user, business, country, key

1. List Lists

Filters: list_type, entry_type, limit, offset.

2. Create List

3. Get / Update / Delete List

4. Add an Entry

Blocklist a session's face + document: add one entry to the face blocklist and one to the document blocklist, each with reference_session_id. On future matches Didit raises FACE_IN_BLOCKLIST / ID_DOCUMENT_IN_BLOCKLIST / PHONE_NUMBER_IN_BLOCKLIST / EMAIL_IN_BLOCKLIST and auto-declines.

5. Upload a Face Entry (no session)

For face lists when you have an image but no session. Body: image (base64 JPG/PNG/WebP, no data: prefix), optional comment. Requires a face-type list; returns 400 if no/multiple faces are detected.

6. List / Delete Entries

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

2. Create Questionnaire

Form element:

3. Get Questionnaire

4. Update Questionnaire

5. Delete Questionnaire

Response: 204 No Content.

Users (KYC)

Manage verified individuals identified by vendor_data. A user's status is a monitoring status — ACTIVE, FLAGGED, or BLOCKED (not a verification decision).

1. List Users

Response (200): Paginated list with vendor_data, full_name, status, session_count, issuing_states, approved_emails, approved_phones.

2. Create User

3. Get User

4. Update User

Send only the fields to change: full_name, display_name, date_of_birth, status (ACTIVE/FLAGGED/BLOCKED), metadata, approved_emails, approved_phones, issuing_states.

5. Update User Status

6. Batch Delete Users

Businesses (KYB)

Manage verified businesses identified by vendor_data. Same ACTIVE/FLAGGED/BLOCKED monitoring status as users.

Standalone KYB registry lookup (no session): POST /v3/kyb/search/ with country_code (required) + name/registration_number returns candidates; pass a candidate's kyb_response_id to POST /v3/kyb/select/ to pull the full company record.

Transactions (AML monitoring)

Submit transactions for rule evaluation and ongoing monitoring.

Create body — required: transaction_id, transaction_category (finance, kyc, travel_rule, user_event, audit_trail_event, gambling_bet, gambling_limit_change, gambling_bonus_change), transaction_details (object), subject (object). Optional: counterparty, transaction_at, time_zone, custom_properties (referenced in rules as custom_values.<key>), travel_rule_details, network_snapshot, include_crypto_screening.

Billing

1. Get Credit Balance

Response (200):

2. Top Up Credits

Response (200):

Present checkout_session_url to the user for payment.

Customization (Branding)

Brand the hosted verification UI with your own logos.

Update fields (image files, multipart/form-data): image_square, image_rectangular, image_favicon. Send only the images you want to change.

Webhook Destinations

Configure webhooks programmatically — no console needed. You can register multiple destinations, each with its own URL, payload version, enabled flag, subscribed events, and signing secret.

1. List Destinations

Response (200): Array of destinations, each with uuid, label, url, enabled, webhook_version, subscribed_events, and the signing secret.

2. Create Destination

Response (201): the created destination, including the secret used to verify the X-Signature header. Store it securely.

3. Get / Update / Delete Destination

Example — disable a destination without deleting it:

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

Event types: status.updated (session status change), data.updated (KYC/POA data manually updated), user.created, user.updated, business.created, business.updated, transaction.created, transaction.updated. Subscribe a destination to specific events via subscribed_events, or omit it to receive all.

Idempotency: dedupe on session_id + status + webhook_type (not timestamp). The event_id is stable across retries.

Signature Verification (recommended)

Two headers: X-Signature (HMAC-SHA256 hex) and X-Timestamp (Unix seconds). The canonical string is the JSON body with floats shortened, keys sorted, compact separators, and ensure_ascii=False; the signed message is {timestamp}:{canonical}.

Simple Signature (Fallback)

Header: X-Signature-Simple — HMAC of key fields only.

Error Responses (All Endpoints)

Common Workflows

Full KYC Onboarding

Programmatic Review + Blocklist

B2B KYC Sharing

Check Balance Before Sessions

Questionnaire + Workflow

Utility Scripts

setup_account.py — Register and verify accounts

manage_workflows.py — CRUD workflows

create_session.py — Create verification sessions

All scripts can be imported as libraries: