Didit Id Document Verification

Didit ID Verification API

Overview

Verifies identity documents by submitting images of the front and back sides. Performs OCR extraction, MRZ parsing, authenticity checks, and document liveness detection.

Key constraints:

Coverage: 4,000+ document types, 220+ countries, 130+ languages. Supports passports, national ID cards, driver's licenses, and residence permits.

Processing pipeline: 1. Intelligent capture & document type detection 2. OCR text extraction + MRZ/barcode parsing 3. Template matching, security feature validation, tamper detection 4. Document liveness (detects screen captures, printed copies, portrait manipulation)

API Reference: https://docs.didit.me/standalone-apis/id-verification Feature Guide: https://docs.didit.me/core-technology/id-verification/overview Supported Documents: https://docs.didit.me/core-technology/id-verification/supported-documents-id-verification

Authentication

All requests require x-api-key header. Get your key from Didit Business Console → API & Webhooks, or via programmatic registration (see below).

Getting Started (No Account Yet?)

If you don't have a Didit API key, create one in 2 API calls:

1. Register: POST https://apx.didit.me/auth/v2/programmatic/register/ with {"email": "you@gmail.com", "password": "MyStr0ng!Pass"} 2. Check email for a 6-character OTP code 3. Verify: POST https://apx.didit.me/auth/v2/programmatic/verify-email/ with {"email": "you@gmail.com", "code": "A3K9F2"} → response includes api_key

To add credits: GET /v3/billing/balance/ to check, POST /v3/billing/top-up/ with {"amount_in_dollars": 50} for a Stripe checkout link.

See the didit-verification-management skill for full platform management (workflows, sessions, users, billing).

Endpoint

POST https://verification.didit.me/v3/id-verification/

Headers

| Header | Value | Required | |---|---|---| | x-api-key | Your API key | Yes | | Content-Type | multipart/form-data | Yes |

Request Parameters (multipart/form-data)

| Parameter | Type | Required | Default | Constraints | Description | |---|---|---|---|---|---| | front_image | file | Yes | — | JPEG/PNG/WebP/TIFF, max 5MB | Front image of ID document | | back_image | file | No | — | Same as above | Back image (when applicable) | | save_api_request | boolean | No | true | — | Save in Business Console Manual Checks | | vendor_data | string | No | — | — | Your identifier for session tracking |

Example

import requests
response = requests.post(
    "https://verification.didit.me/v3/id-verification/",
    headers={"x-api-key": "YOUR_API_KEY"},
    files={
        "front_image": ("front.jpg", open("front.jpg", "rb"), "image/jpeg"),
        "back_image": ("back.jpg", open("back.jpg", "rb"), "image/jpeg"),
    },
    data={"vendor_data": "user-123"},
)

const formData = new FormData();
formData.append("front_image", frontImageFile);
formData.append("back_image", backImageFile);
formData.append("vendor_data", "user-123");
const response = await fetch("https://verification.didit.me/v3/id-verification/", {
  method: "POST",
  headers: { "x-api-key": "YOUR_API_KEY" },
  body: formData,
});

Response (200 OK)

{
  "request_id": "a1b2c3d4-...",
  "id_verification": {
    "status": "Approved",
    "document_type": "Identity Card",
    "document_number": "YZA123456",
    "personal_number": "X9876543L",
    "first_name": "Elena",
    "last_name": "Martínez Sánchez",
    "full_name": "Elena Martínez Sánchez",
    "date_of_birth": "1985-03-15",
    "age": 40,
    "gender": "F",
    "nationality": "ESP",
    "issuing_state": "ESP",
    "issuing_state_name": "Spain",
    "expiration_date": "2030-08-21",
    "date_of_issue": "2020-08-21",
    "address": "Calle Mayor 10, Madrid",
    "formatted_address": "Calle Mayor 10, 28013 Madrid, Spain",
    "place_of_birth": "Valencia",
    "portrait_image": "",
    "front_document_image": "",
    "back_document_image": "",
    "mrz": {
      "surname": "MARTINEZ SANCHEZ",
      "given_name": "ELENA",
      "document_type": "I",
      "document_number": "YZA123456",
      "country": "ESP",
      "nationality": "ESP",
      "birth_date": "850315",
      "expiry_date": "300821",
      "sex": "F"
    },
    "parsed_address": {"city": "Madrid", "region": "...", "postal_code": "28013", "country": "ES"},
    "warnings": []
  },
  "created_at": "2025-05-01T13:11:07.977806Z"
}

Status Values

| Status | Meaning | |---|---| | "Approved" | Document verified successfully | | "Declined" | Verification failed (see warnings) | | "In Review" | Requires manual review |

Error Responses

| Code | Meaning | Action | |---|---|---| | 400 | Invalid request | Check file format, size, parameters | | 401 | Invalid API key | Verify x-api-key header | | 403 | Insufficient credits | Top up at business.didit.me |

Response Field Reference

| Field | Type | Description | |---|---|---| | status | string | "Approved", "Declined", "In Review" | | document_type | string | "Passport", "Identity Card", "Driver's License", "Residence Permit" | | document_number | string | Document ID number | | personal_number | string | Personal/national ID number | | first_name, last_name, full_name | string | Extracted name fields | | date_of_birth | string | YYYY-MM-DD | | age | integer | Calculated age | | gender | string | "M", "F", "U" | | nationality, issuing_state | string | ISO 3166-1 alpha-3 | | expiration_date, date_of_issue | string | YYYY-MM-DD | | portrait_image | string | Base64-encoded portrait from document | | mrz | object | Machine Readable Zone data | | parsed_address | object | Geocoded address: {city, region, postal_code, country, street_1} | | warnings | array | {risk, log_type, short_description, long_description} |

Warning Tags

Auto-Decline (always)

| Tag | Description | |---|---| | ID_DOCUMENT_IN_BLOCKLIST | Document in blocklist (previously flagged) | | PORTRAIT_IMAGE_NOT_DETECTED | No portrait found on document | | DOCUMENT_EXPIRED | Document expiration date has passed | | DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION | Document type not accepted |

Configurable (Decline / Review / Approve)

| Category | Tags | |---|---| | Document liveness | SCREEN_CAPTURE_DETECTED, PRINTED_COPY_DETECTED, PORTRAIT_MANIPULATION_DETECTED | | MRZ issues | MRZ_NOT_DETECTED, MRZ_VALIDATION_FAILED, MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME | | Data issues | NAME_NOT_DETECTED, DATE_OF_BIRTH_NOT_DETECTED, DOCUMENT_NUMBER_NOT_DETECTED, DATA_INCONSISTENT | | Duplicates | POSSIBLE_DUPLICATED_USER | | Expected mismatch | FULL_NAME_MISMATCH_WITH_PROVIDED, DOB_MISMATCH_WITH_PROVIDED, GENDER_MISMATCH_WITH_PROVIDED | | Geolocation | DOCUMENT_COUNTRY_MISMATCH |

Common Workflows

Basic ID Verification

1. POST /v3/id-verification/ → front_image (+ back_image if applicable)
2. If "Approved" → extract first_name, last_name, date_of_birth, document_number
   If "Declined" → check warnings:
     DOCUMENT_EXPIRED → ask for valid document
     SCREEN_CAPTURE_DETECTED → ask for real photo of physical document
     MRZ_VALIDATION_FAILED → ask for clearer image

Full Identity Verification Pipeline

1. POST /v3/id-verification/ → verify document
2. POST /v3/passive-liveness/ → verify real person
3. POST /v3/face-match/ → compare selfie to document portrait
4. POST /v3/aml/ → screen extracted name/DOB/nationality
5. All Approved → fully verified identity

Utility Scripts

export DIDIT_API_KEY="your_api_key"
python scripts/verify_id.py front.jpg
python scripts/verify_id.py front.jpg back.jpg --vendor-data user-123

import requests
response = requests.post(
    "https://verification.didit.me/v3/id-verification/",
    headers={"x-api-key": "YOUR_API_KEY"},
    files={
        "front_image": ("front.jpg", open("front.jpg", "rb"), "image/jpeg"),
        "back_image": ("back.jpg", open("back.jpg", "rb"), "image/jpeg"),
    },
    data={"vendor_data": "user-123"},
)

const formData = new FormData();
formData.append("front_image", frontImageFile);
formData.append("back_image", backImageFile);
formData.append("vendor_data", "user-123");
const response = await fetch("https://verification.didit.me/v3/id-verification/", {
  method: "POST",
  headers: { "x-api-key": "YOUR_API_KEY" },
  body: formData,
});

Response (200 OK)

{
  "request_id": "a1b2c3d4-...",
  "id_verification": {
    "status": "Approved",
    "document_type": "Identity Card",
    "document_number": "YZA123456",
    "personal_number": "X9876543L",
    "first_name": "Elena",
    "last_name": "Martínez Sánchez",
    "full_name": "Elena Martínez Sánchez",
    "date_of_birth": "1985-03-15",
    "age": 40,
    "gender": "F",
    "nationality": "ESP",
    "issuing_state": "ESP",
    "issuing_state_name": "Spain",
    "expiration_date": "2030-08-21",
    "date_of_issue": "2020-08-21",
    "address": "Calle Mayor 10, Madrid",
    "formatted_address": "Calle Mayor 10, 28013 Madrid, Spain",
    "place_of_birth": "Valencia",
    "portrait_image": "",
    "front_document_image": "",
    "back_document_image": "",
    "mrz": {
      "surname": "MARTINEZ SANCHEZ",
      "given_name": "ELENA",
      "document_type": "I",
      "document_number": "YZA123456",
      "country": "ESP",
      "nationality": "ESP",
      "birth_date": "850315",
      "expiry_date": "300821",
      "sex": "F"
    },
    "parsed_address": {"city": "Madrid", "region": "...", "postal_code": "28013", "country": "ES"},
    "warnings": []
  },
  "created_at": "2025-05-01T13:11:07.977806Z"
}

Status Values

| Status | Meaning | |---|---| | "Approved" | Document verified successfully | | "Declined" | Verification failed (see warnings) | | "In Review" | Requires manual review |

Error Responses

| Code | Meaning | Action | |---|---|---| | 400 | Invalid request | Check file format, size, parameters | | 401 | Invalid API key | Verify x-api-key header | | 403 | Insufficient credits | Top up at business.didit.me |