Didit Verification Management

Full Didit identity verification platform management — account creation, API keys, sessions, workflows, questionnaires, users, billing, blocklist, and webhooks. Use when someone needs to create a Didit account, get API keys, set up verification workflows, create or retrieve verification sessions, approve or decline sessions, manage users, check credit balance, top up credits, configure blocklists, configure webhooks programmatically, handle webhook signatures, or perform any platform administration. 45+ endpoints across 9 categories.

# 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](https://docs.didit.me/auth-api/register) | [Verify Email](https://docs.didit.me/auth-api/verify-email) | [Login](https://docs.didit.me/auth-api/login) | [Get Credentials](https://docs.didit.me/auth-api/get-credentials)
- **Sessions:** [Create](https://docs.didit.me/sessions-api/create-session) | [Retrieve](https://docs.didit.me/sessions-api/retrieve-session) | [List](https://docs.didit.me/sessions-api/list-sessions) | [Delete](https://docs.didit.me/sessions-api/delete-session) | [Update Status](https://docs.didit.me/sessions-api/update-status) | [PDF](https://docs.didit.me/sessions-api/generate-pdf) | [Share](https://docs.didit.me/sessions-api/share-session/share) | [Import](https://docs.didit.me/sessions-api/share-session/import)
- **Workflows:** [Create](https://docs.didit.me/management-api/workflows/create) | [List](https://docs.didit.me/management-api/workflows/list) | [Get](https://docs.didit.me/management-api/workflows/get) | [Update](https://docs.didit.me/management-api/workflows/update) | [Delete](https://docs.didit.me/management-api/workflows/delete)
- **Questionnaires:** [Create](https://docs.didit.me/management-api/questionnaires/create) | [List](https://docs.didit.me/management-api/questionnaires/list) | [Get](https://docs.didit.me/management-api/questionnaires/get) | [Update](https://docs.didit.me/management-api/questionnaires/update) | [Delete](https://docs.didit.me/management-api/questionnaires/delete)
- **Users:** [List](https://docs.didit.me/management-api/users/list) | [Get](https://docs.didit.me/management-api/users/get) | [Update](https://docs.didit.me/management-api/users/update) | [Delete](https://docs.didit.me/management-api/users/delete)
- **Billing:** [Balance](https://docs.didit.me/management-api/billing/balance) | [Top Up](https://docs.didit.me/management-api/billing/top-up)
- **Blocklist:** [Add](https://docs.didit.me/sessions-api/blocklist/add) | [Remove](https://docs.didit.me/sessions-api/blocklist/remove) | [List](https://docs.didit.me/sessions-api/blocklist/list)
- **Session Operations:** [Batch Delete](https://docs.didit.me/management-api/sessions/batch-delete) | [List Reviews](https://docs.didit.me/management-api/sessions/list-reviews) | [Create Review](https://docs.didit.me/management-api/sessions/create-review)
- **Webhook Config:** [Get](https://docs.didit.me/management-api/webhook/get) | [Update](https://docs.didit.me/management-api/webhook/update)
- **Guides:** [Programmatic Registration](https://docs.didit.me/integration/programmatic-registration) | [Webhooks](https://docs.didit.me/integration/webhooks) | [AI Agent Integration](https://docs.didit.me/integration/ai-agent-integration) | [API Overview](https://docs.didit.me/sessions-api/management-api)

---

## Getting Started — Zero to Verifying

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

```python
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 <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](https://business.didit.me) → 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):**

```json
{
  "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 <access_token>`

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

### 5. Get Application Credentials

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

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

**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, Fa