> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Management API (v3)

> Configure workflows, questionnaires, users, billing, and blocklists via API key. Agent-native, MCP-ready. Pay-per-call from $0.30, no contracts.

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

```bash theme={null}
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](/integration/programmatic-registration).

***

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

<ParamField path="GET /v3/workflows/" type="GET">
  List all workflows for your application. Returns each workflow's features, thresholds, and whether it's the default.
</ParamField>

<ParamField path="POST /v3/workflows/" type="POST">
  Create a new workflow. Define which verification features to enable, set thresholds, configure accepted document types, and more.
</ParamField>

<ParamField path="GET /v3/workflows/{uuid}/" type="GET">
  Get full details of a specific workflow, including all feature configurations and thresholds.
</ParamField>

<ParamField path="PATCH /v3/workflows/{uuid}/" type="PATCH">
  Update a workflow configuration. You can modify any feature settings, thresholds, or accepted documents.
</ParamField>

<ParamField path="DELETE /v3/workflows/{uuid}/" type="DELETE">
  Delete a workflow. Sessions already using this workflow are not affected.
</ParamField>

<Warning>
  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.
</Warning>

### Quick Example: Create a Workflow

The `workflow_type` determines the base feature set. Individual features are then toggled with `is_*_enabled` flags.

```bash theme={null}
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:

```bash theme={null}
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.

<ParamField path="GET /v3/questionnaires/" type="GET">
  List all questionnaires.
</ParamField>

<ParamField path="POST /v3/questionnaires/" type="POST">
  Create a new questionnaire with custom questions, branching logic, and translations.
</ParamField>

<ParamField path="GET /v3/questionnaires/{uuid}/" type="GET">
  Get questionnaire details including all questions and form structure.
</ParamField>

<ParamField path="PATCH /v3/questionnaires/{uuid}/" type="PATCH">
  Update a questionnaire.
</ParamField>

<ParamField path="DELETE /v3/questionnaires/{uuid}/" type="DELETE">
  Delete a questionnaire.
</ParamField>

***

## Users

Manage verified individuals (users) in your application. Each user is identified by a `vendor_data` string you provide when creating sessions.

<ParamField path="GET /v3/users/" type="GET">
  List all users for your application, including their verification status and session history.
</ParamField>

<ParamField path="GET /v3/users/{vendor_data}/" type="GET">
  Get user details by your vendor\_data identifier.
</ParamField>

<ParamField path="PATCH /v3/users/{vendor_data}/" type="PATCH">
  Update user metadata.
</ParamField>

<ParamField path="POST /v3/users/delete/" type="POST">
  Batch delete users. Body: `{"vendor_data_list": ["user-1", "user-2"]}` or `{"delete_all": true}`.
</ParamField>

***

## Session Operations

<ParamField path="POST /v3/sessions/delete/" type="POST">
  Batch delete sessions. Requires `delete:sessions`. Body: `{"session_numbers": [1, 2, 3]}` or `{"delete_all": true}`.
</ParamField>

<ParamField path="GET /v3/sessions/{uuid}/reviews/" type="GET">
  List reviews and activity log for a session.
</ParamField>

<ParamField path="POST /v3/sessions/{uuid}/reviews/" type="POST">
  Add a review note or status change to a session.
</ParamField>

***

## Billing

<ParamField path="GET /v3/billing/balance/" type="GET">
  Get current credit balance and auto-refill settings.
</ParamField>

```json theme={null}
{
  "balance": "142.5000",
  "auto_refill_enabled": true,
  "auto_refill_amount": "100.0000",
  "auto_refill_threshold": "10.0000"
}
```

<ParamField path="POST /v3/billing/top-up/" type="POST">
  Create a Stripe checkout session to top up credits. Minimum \$50.
</ParamField>

```json theme={null}
{
  "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](/management-api/lists/overview).

<ParamField path="GET /v3/lists/" type="GET">
  List all lists for the application (blocklists, allowlists, custom).
</ParamField>

<ParamField path="POST /v3/lists/{list_uuid}/entries/" type="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.
</ParamField>

<ParamField path="DELETE /v3/lists/{list_uuid}/entries/{entry_uuid}/" type="DELETE">
  Remove an entry from a list.
</ParamField>

<ParamField path="POST /v3/lists/{list_uuid}/entries/face-upload/" type="POST">
  Upload a face image to a face blocklist (base64).
</ParamField>

***

## Webhook Configuration

<ParamField path="GET /v3/webhook/" type="GET">
  Get current webhook configuration including URL, version, and the secret key for verifying webhook signatures.
</ParamField>

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

<ParamField path="PATCH /v3/webhook/" type="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).
</ParamField>

```json theme={null}
{
  "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                               |