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:

•Supported formats: JPEG, PNG, WebP, TIFF
•Maximum file size: 5MB per image
•All document corners must be visible, full-color, no glare/shadows
•Original real-time photos only (no screenshots, scans, or digital copies)

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

Processing pipeline:

•Intelligent capture & document type detection
•OCR text extraction + MRZ/barcode parsing
•Template matching, security feature validation, tamper detection
•Document liveness (detects screen captures, printed copies, portrait manipulation)

API Reference: https://docs.didit.me/reference/id-verification-standalone-api

Authentication

All requests require x-api-key header. Get your key from Didit Business Console → API & Webhooks.

Endpoint

code

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

python

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"},
)

typescript

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)

json

{
  "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": "<base64>",
    "front_document_image": "<base64>",
    "back_document_image": "<base64>",
    "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

code

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

code

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

bash

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