Didit Verification Management

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:

• 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: List | Get | Update | Delete
• Billing: Balance | Top Up
• Blocklist: Add | Remove | List
• Session Operations: Batch Delete | List Reviews | Create Review
• Webhook Config: Get | Update
• 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/",
    json={"email": "you@gmail.com", "password": "MyStr0ng!Pass"})

# 2. Check email for 6-char OTP, then verify → get api_key
resp = requests.post("https://apx.didit.me/auth/v2/programmatic/verify-email/",
    json={"email": "you@gmail.com", "code": "A3K9F2"})
api_key = resp.json()["application"]["api_key"]
headers = {"x-api-key": api_key, "Content-Type": "application/json"}

# 3. Create a KYC workflow
wf = requests.post("https://verification.didit.me/v3/workflows/",
    headers=headers,
    json={"workflow_label": "My KYC", "workflow_type": "kyc",
          "is_liveness_enabled": True, "is_face_match_enabled": True}).json()

# 4. Create a session → send user to the URL
session = requests.post("https://verification.didit.me/v3/session/",
    headers=headers,
    json={"workflow_id": wf["uuid"], "vendor_data": "user-123"}).json()
print(f"Send user to: {session['url']}")

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 | | Everything else (sessions, workflows, etc.) | API Key | x-api-key: |

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

POST /programmatic/register/

| Body | Type | Required | Description | |---|---|---|---| | email | string | Yes | Any email address | | password | string | Yes | Min 8 chars, 1 upper, 1 lower, 1 digit, 1 special |

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

Rate limit: 5 per IP per hour.

2. Verify Email & Get Credentials

POST /programmatic/verify-email/

| Body | Type | Required | Description | |---|---|---|---| | email | string | Yes | Same email from register | | code | string | Yes | 6-character alphanumeric OTP from email |

Response (200):

{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "expires_in": 86400,
  "organization": {"uuid": "...", "name": "..."},
  "application": {"uuid": "...", "client_id": "...", "api_key": "YOUR_KEY_HERE"}
}

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

3. Login (Existing Accounts)

POST /programmatic/login/

| Body | Type | Required | Description | |---|---|---|---| | email | string | Yes | Account email | | password | string | Yes | Account password |

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

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

4. List Organizations

GET /organizations/me/

Auth: Authorization: Bearer

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

5. Get Application Credentials

GET /organizations/me/{org_id}/applications/{app_id}/

Auth: Authorization: Bearer

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.

Workflow Types:

| Type | Purpose | Typical Features | |---|---|---| | kyc | Full identity verification (ID + selfie) | ID Verification, Liveness, Face Match, AML, NFC | | adaptive_age_verification | 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

GET /v3/workflows/

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

2. Create Workflow

POST /v3/workflows/

| Body | Type | Default | Description | |---|---|---|---| | workflow_label | string | auto | Display name | | workflow_type | 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.

wf = requests.post("https://verification.didit.me/v3/workflows/",
    headers={"x-api-key": API_KEY, "Content-Type": "application/json"},
    json={"workflow_label": "KYC + AML", "workflow_type": "kyc",
          "is_liveness_enabled": True, "is_face_match_enabled": True,
          "is_aml_enabled": True}).json()

3. Get Workflow

GET /v3/workflows/{settings_uuid}/

4. Update Workflow

PATCH /v3/workflows/{settings_uuid}/

Partial update — only send fields to change.

5. Delete Workflow

DELETE /v3/workflows/{settings_uuid}/

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, Abandoned, Expired, Resubmitted

Rate limits: 300 req/min per method. Session creation: 600/min. Decision polling: 100/min.

1. Create Session

POST /v3/session/

| Body | Type | Required | Description | |---|---|---|---| | workflow_id | uuid | Yes | Workflow UUID | | vendor_data | 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):

{
  "session_id": "...",
  "session_number": 1234,
  "session_token": "abcdef123456",
  "url": "https://verify.didit.me/session/abcdef123456",
  "status": "Not Started",
  "workflow_id": "..."
}

Send the user to url to complete verification.

2. Retrieve Session (Get Decision)

GET /v3/session/{sessionId}/decision/

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

GET /v3/sessions/

| Query | Type | Default | Description | |---|---|---|---| | vendor_data | string | — | Filter by your user identifier | | status | 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

DELETE /v3/session/{sessionId}/delete/

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

5. Batch Delete Sessions

POST /v3/sessions/delete/

| Body | Type | Description | |---|---|---| | session_numbers | array | List of session numbers to delete | | delete_all | boolean | Delete all sessions (use with caution) |

6. Update Session Status

PATCH /v3/session/{sessionId}/update-status/

| Body | Type | Required | Description | |---|---|---|---| | new_status | string | Yes | "Approved", "Declined", or "Resubmitted" | | comment | 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

GET /v3/session/{sessionId}/generate-pdf

Rate limit: 100 req/min.

8. Share Session

POST /v3/session/{sessionId}/share/

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

9. Import Shared Session

POST /v3/session/import-shared/

| Body | Type | Required | Description | |---|---|---|---| | share_token | string | Yes | Token from sharing partner | | trust_review | boolean | Yes | true: keep original status; false: set to "

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: didit-protocol
• Source: didit-protocol/skills
• License: MIT

Install and usage instructions live in the source repository linked above.