Didit Id Document Verification

Verifies identity documents via the Didit standalone API. Use when verifying a passport, ID card, driver's license, or residence permit, performing OCR extra...

Security Scan

The skill's code, instructions, and required credential (DIDIT_API_KEY) are consistent with its stated purpose of calling Didit's ID verification API; nothing in the package requests unrelated credentials, installs, or hidden endpoints.

Purpose & Capability

Name/description match the actual behavior: the SKILL.md and included script submit ID images to Didit's verification endpoints and use a single API key (DIDIT_API_KEY). No unrelated services, binaries, or credentials are requested.

Instruction Scope

Runtime instructions and the Python script only read the DIDIT_API_KEY env var and user-specified image files, then POST multipart/form-data to Didit endpoints (verification.didit.me, apx.didit.me, business.didit.me). There are no directives to read other system files, harvest environment variables, or send data to unexpected hosts.

Install Mechanism

No install step or third-party download is specified; the skill is instruction-only with a small included script, so nothing is written to disk beyond the provided files. Low installation risk.

Credentials

Only a single credential (DIDIT_API_KEY) is required and is used directly by the script to authenticate requests. The number and type of environment variables are proportional to the skill's function.

Persistence & Privilege

always is false and the skill does not request persistent system privileges or modify other skill configs. It does not attempt to enable itself or store credentials beyond using the environment variable at runtime.

Assessment

This skill will upload sensitive personal ID images and extracted PII to Didit's servers using the DIDIT_API_KEY you supply. Before installing: (1) confirm you trust Didit and review their privacy, retention, and billing policies; (2) store the DIDIT_API_KEY securely (don’t paste a production key into an untrusted agent UI); (3) be aware that by default requests are saved in the Business Console (save_api_request defaults to true; the script has a --no-save flag); (4) ensure sending ID images to an external vendor complies with your legal/regulatory and privacy requirements (GDPR, etc.); and (5) consider using a scoped/test API key for experimentation. The package itself is coherent with its claimed purpose.

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:

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": "[e-mail]", "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": "[e-mail]", "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": "<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

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