# Didit Programmatic API Access - Agent Instructions

> Machine-readable instructions for AI agents to register for Didit, retrieve API credentials, create questionnaires and workflows, top up credits, create verification sessions, and install Didit agent tooling.

## Quick Reference

| Requirement               | Value                                                           |
| ------------------------- | --------------------------------------------------------------- |
| Browser required          | No                                                              |
| Signup flow               | 2 API calls plus a user-provided email code                     |
| Auth base URL             | `https://apx.didit.me/auth/v2`                                  |
| Verification API base URL | `https://verification.didit.me/v3`                              |
| API auth header           | `x-api-key: DIDIT_API_KEY`                                      |
| Management auth header    | `Authorization: Bearer ACCESS_TOKEN` for auth-service endpoints |
| API key source            | `application.api_key` from programmatic email verification      |
| Top-up minimum            | 50 USD                                                          |
| Main docs                 | `https://docs.didit.me`                                         |

## Complete Flow

### Step 1: Register an API Account

```bash
curl -X POST "https://apx.didit.me/auth/v2/programmatic/register/" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "developer@example.com",
    "password": "StrongP@ss1"
  }'
```

Success response:

```json
{
  "message": "Registration successful. Check your email for the verification code.",
  "email": "developer@example.com"
}
```

The user receives a 6-character alphanumeric email code such as `A3K9F2`.

### Step 2: Verify Email and Extract Credentials

```bash
curl -X POST "https://apx.didit.me/auth/v2/programmatic/verify-email/" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "developer@example.com",
    "code": "A3K9F2"
  }'
```

Success response:

```json
{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "expires_in": 86400,
  "organization": {
    "uuid": "organization-uuid",
    "name": "developer"
  },
  "application": {
    "uuid": "application-uuid",
    "name": "developer",
    "client_id": "client-id",
    "api_key": "didit-api-key"
  }
}
```

Extract and store:

```bash
export DIDIT_API_KEY="didit-api-key"
export DIDIT_ACCESS_TOKEN="eyJ..."
export DIDIT_ORGANIZATION_ID="organization-uuid"
export DIDIT_APPLICATION_ID="application-uuid"
```

Use `DIDIT_API_KEY` as the `x-api-key` header for verification, management, billing, questionnaire, workflow, session, list, and transaction APIs.

### Step 3: Log In Later

If the API account already exists, log in with email and password:

```bash
curl -X POST "https://apx.didit.me/auth/v2/programmatic/login/" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "developer@example.com",
    "password": "StrongP@ss1"
  }'
```

Success response:

```json
{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "expires_in": 86400,
  "message": "Login successful"
}
```

If you need to re-fetch application credentials after login:

```bash
curl "https://apx.didit.me/auth/v2/organizations/me/" \
  -H "Authorization: Bearer DIDIT_ACCESS_TOKEN"

curl "https://apx.didit.me/auth/v2/organizations/me/{org_id}/applications/{app_id}/" \
  -H "Authorization: Bearer DIDIT_ACCESS_TOKEN"
```

The application response includes `client_id` and `api_key`.

## Create a Questionnaire

Use questionnaires when the verification flow should collect custom answers, source-of-funds information, files, dates, emails, or other business-specific fields.

```bash
curl -X POST "https://verification.didit.me/v3/questionnaires/" \
  -H "x-api-key: DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Customer Onboarding",
    "languages": ["en"],
    "default_language": "en",
    "form_elements": [
      {
        "id": "occupation",
        "element_type": "short_text",
        "label": { "en": "What is your occupation?" },
        "is_required": true
      },
      {
        "id": "source_of_funds",
        "element_type": "multiple_choice",
        "label": { "en": "Source of funds" },
        "is_required": true,
        "options": [
          { "value": "employment", "label": { "en": "Employment" } },
          { "value": "business", "label": { "en": "Business" } },
          { "value": "investments", "label": { "en": "Investments" } }
        ]
      }
    ]
  }'
```

Store `questionnaire_id` from the response. Use it later as `config.questionnaire_uuid` in workflows.

Rules for agents:

- Use the simple `form_elements` API shape.
- Include `languages` with `en` and `default_language` set to `en`.
- Use element types such as `short_text`, `multiple_choice`, `single_choice`, `dropdown`, `email`, `file_upload`, or `date_picker`.
- Do not send `graph`, `branches`, `next`, `required_if`, or conditional rules to this endpoint.

## Create a Workflow

Workflows define the verification steps that users or businesses complete. Send features in the exact order users should complete them.

### Standard KYC Workflow

```bash
curl -X POST "https://verification.didit.me/v3/workflows/" \
  -H "x-api-key: DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_label": "Standard KYC",
    "features": [
      {
        "feature": "OCR",
        "config": {
          "duplicated_user_action": "review"
        }
      },
      {
        "feature": "LIVENESS",
        "config": {
          "face_liveness_method": "passive"
        }
      },
      {
        "feature": "FACE_MATCH"
      }
    ]
  }'
```

### Questionnaire Workflow

```bash
curl -X POST "https://verification.didit.me/v3/workflows/" \
  -H "x-api-key: DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_label": "Source of Funds",
    "features": [
      {
        "feature": "QUESTIONNAIRE",
        "config": {
          "questionnaire_uuid": "questionnaire-id-from-create-questionnaire",
          "review_questionnaire_manually": true
        }
      }
    ]
  }'
```

Store the workflow `uuid` from the response. Use it as:

- `workflow_id` when creating sessions.
- `settings_uuid` when retrieving or updating the workflow.

Rules for agents:

- Use uppercase feature values such as `OCR`, `LIVENESS`, `FACE_MATCH`, `AML`, `QUESTIONNAIRE`, `EMAIL_VERIFICATION`, `PHONE_VERIFICATION`, `PROOF_OF_ADDRESS`, `NFC`, or `DATABASE_VALIDATION`.
- Put dependency features first. For example, put `OCR` before `FACE_MATCH`, `NFC`, `DATABASE_VALIDATION`, or user AML checks that depend on document data.
- Do not send workflow graphs, branches, action nodes, webhook nodes, or conditional logic to the simple v3 workflow endpoint.

## List Existing Workflows

```bash
curl "https://verification.didit.me/v3/workflows/" \
  -H "x-api-key: DIDIT_API_KEY"
```

Use this before creating a duplicate workflow. If a suitable workflow already exists, store its `uuid` as `DIDIT_WORKFLOW_ID`.

## Create a Verification Session

Use a single endpoint for User Verification (KYC) and Business Verification (KYB). The workflow type determines the session kind.

```bash
curl -X POST "https://verification.didit.me/v3/session/" \
  -H "x-api-key: DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "DIDIT_WORKFLOW_ID",
    "vendor_data": "user-123",
    "callback": "https://example.com/verification-complete",
    "metadata": {
      "plan": "premium",
      "signup_source": "agent"
    },
    "contact_details": {
      "email": "user@example.com",
      "email_lang": "en",
      "send_notification_emails": true,
      "phone": "+14155552671"
    },
    "expected_details": {
      "first_name": "Jane",
      "last_name": "Doe",
      "date_of_birth": "1990-01-15",
      "expected_document_types": ["P", "ID", "DL"]
    }
  }'
```

Important response fields:

```json
{
  "session_id": "session-uuid",
  "session_kind": "user",
  "session_token": "session-token",
  "url": "https://verify.didit.me/session/...",
  "verification_url": "https://verify.didit.me/session/...",
  "status": "Not Started",
  "workflow_id": "DIDIT_WORKFLOW_ID",
  "vendor_data": "user-123"
}
```

Use `url` or `verification_url` to send the end user into the hosted Didit flow. Use `session_token` for SDK-based integrations.

Before sending a user into a session, your product should show required notices and collect any required consent for identity verification, biometrics, document capture, liveness, and data processing.

## Retrieve Session Results

Prefer webhooks for production. To fetch the decision directly:

```bash
curl "https://verification.didit.me/v3/session/{session_id}/decision/" \
  -H "x-api-key: DIDIT_API_KEY"
```

Common statuses:

| Status        | Meaning                             |
| ------------- | ----------------------------------- |
| `Not Started` | Session created, user has not begun |
| `In Progress` | User is completing verification     |
| `In Review`   | Manual review is needed             |
| `Approved`    | Verification succeeded              |
| `Declined`    | Verification failed                 |
| `Abandoned`   | User left before completion         |
| `Expired`     | Session expired                     |

## Billing: Check Balance and Top Up

### Check Balance

```bash
curl "https://verification.didit.me/v3/billing/balance/" \
  -H "x-api-key: DIDIT_API_KEY"
```

Success response:

```json
{
  "balance": "125.00",
  "auto_refill_enabled": false,
  "auto_refill_amount": null,
  "auto_refill_threshold": null
}
```

### Create a Top-Up Checkout

```bash
curl -X POST "https://verification.didit.me/v3/billing/top-up/" \
  -H "x-api-key: DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_in_dollars": 50,
    "success_url": "https://example.com/billing/success",
    "cancel_url": "https://example.com/billing/cancel"
  }'
```

Success response:

```json
{
  "checkout_session_id": "cs_...",
  "checkout_session_url": "https://checkout.stripe.com/..."
}
```

Redirect the user to `checkout_session_url` to complete payment. Agents should not enter payment credentials. If payment is required, hand the URL to the user and wait for confirmation before retrying paid API calls.

## Agent Tooling

### MCP Server

Add Didit to an MCP-capable agent such as Cursor or Claude Desktop:

```json
{
  "mcpServers": {
    "didit": {
      "command": "npx",
      "args": ["@didit-protocol/mcp-server"],
      "env": {
        "DIDIT_API_KEY": "didit-api-key"
      }
    }
  }
}
```

Useful MCP tools include:

| Tool                         | Purpose                              |
| ---------------------------- | ------------------------------------ |
| `didit_register`             | Register a new API account           |
| `didit_verify_email`         | Verify email and get API credentials |
| `didit_login`                | Log in to an existing API account    |
| `didit_create_questionnaire` | Create a questionnaire               |
| `didit_create_workflow`      | Create a workflow                    |
| `didit_create_session`       | Create a verification session        |
| `didit_get_session_decision` | Fetch verification results           |
| `didit_get_balance`          | Check credit balance                 |
| `didit_top_up`               | Create a top-up checkout             |

### Agent Skills

Install Didit skills for coding agents:

```bash
npx clawhub@latest install didit-sessions didit-id-verification didit-passive-liveness didit-face-match didit-aml-screening
```

Required environment:

```bash
export DIDIT_API_KEY="didit-api-key"
export DIDIT_WORKFLOW_ID="workflow-uuid"
export DIDIT_WEBHOOK_SECRET="webhook-secret"
```

## Error Handling

| Status             | Meaning                                 | Action                                              |
| ------------------ | --------------------------------------- | --------------------------------------------------- |
| `400`              | Validation error                        | Read the response body and fix request fields       |
| `401`              | Missing, invalid, or expired credential | Check `x-api-key` or bearer token                   |
| `403`              | Credential lacks access                 | Use the API key for the correct application         |
| `429`              | Rate limited or account locked          | Back off and retry after `wait` seconds if provided |
| Not enough credits | Paid operation cannot run               | Check balance and create a top-up checkout          |

Programmatic registration limits:

- Register: 5 attempts per IP per hour.
- Login: 20 attempts per IP per minute, 100 per hour, with progressive account lockout after repeated failures.

## Agent Implementation Pseudocode

```text
1. If DIDIT_API_KEY exists, verify it with GET /v3/billing/balance/.
2. If no API key exists, call /auth/v2/programmatic/register/.
3. Ask the user for the 6-character email code.
4. Call /auth/v2/programmatic/verify-email/ and store application.api_key.
5. List workflows with GET /v3/workflows/.
6. If no suitable workflow exists:
   a. Create a questionnaire if custom questions are needed.
   b. Create a workflow with ordered features.
7. Check billing balance.
8. If balance is too low, create a top-up checkout and ask the user to complete payment.
9. Create a session with POST /v3/session/.
10. Return the verification URL or session token to the application.
11. Configure webhooks or poll /v3/session/{session_id}/decision/ for results.
```

## References

- Docs: `https://docs.didit.me`
- Business Console: `https://business.didit.me`
- Programmatic registration: `https://docs.didit.me/integration/programmatic-registration`
- AI agent integration: `https://docs.didit.me/integration/ai-agent-integration`
- API authentication: `https://docs.didit.me/getting-started/api-authentication`
- Create session: `https://docs.didit.me/sessions-api/create-session`
- Create questionnaire: `https://docs.didit.me/management-api/questionnaires/create`
- Create workflow: `https://docs.didit.me/management-api/workflows/create`