Verify any ID,
anywhere in the world.

# Didit ID Verification — integrate in 5 minutes

You are integrating Didit's ID Verification module into <my_stack>. Follow
these steps exactly. Every URL, header, and enum value below is canonical —
do not paraphrase or "improve" them.

## 1. Provision an account
- Sign up: https://business.didit.me (no credit card required).
- Or provision programmatically: POST https://apx.didit.me/auth/v2/programmatic/register/
  (returns an API key bound to the workspace + application).

## 2. Two integration paths — pick one

### Path A — Workflow Builder (hosted UI)
Best when you want Didit to handle camera, lighting cues, retries,
mobile handoff, and accessibility for you.

1. Create a workflow that contains the ID_VERIFICATION feature:
   POST https://verification.didit.me/v3/workflows/
   Authorization header:  x-api-key: <your-api-key>
   Body: workflow_label, features array with the single entry
         { feature: "ID_VERIFICATION" }   (UPPERCASE — strict enum)

2. Create a verification session for an end user:
   POST https://verification.didit.me/v3/session/
   Body: workflow_id (from step 1), vendor_data (your own user id).
   Response: session_url — redirect the user to it.

3. Listen for webhook callbacks (see "Webhooks" below).

### Path B — Standalone server-to-server API
Best when you already have the document image (mobile SDK capture, native
onboarding app, reseller pipeline).

POST https://verification.didit.me/v3/id-verification/
Content-Type: multipart/form-data
Body fields:
  - front_image  (required, file)
  - back_image   (optional, file)
  - vendor_data  (optional string, your user id)

Response: JSON report with extracted fields, image quality scores,
warnings array, and the verdict.

## 3. Webhooks (Path A only — Path B returns synchronously)
- Register a webhook destination once via
  POST https://verification.didit.me/v3/webhook/destinations/
  Body: url, subscribed_events: ["session.verified", "session.review_started",
                                  "session.declined", "kyc_expired"]
- Response includes secret_shared_key — store it.
- Every webhook delivery carries an X-Signature-V2 header you MUST verify
  before trusting the payload.  HMAC-SHA256 verification MUST run against the raw body bytes (the raw payload as Didit sent it) BEFORE any JSON parsing — re-serialising the parsed body changes whitespace and key order, which invalidates the signature.Algorithm:
    1. sortKeys(payload) recursively
    2. shortenFloats (truncate trailing zeros after the decimal point)
    3. JSON.stringify the result
    4. HMAC-SHA256 with the secret_shared_key
    5. Hex-encode, compare to the X-Signature-V2 header.

## 4. Reading the report (both paths return the same shape)
The id_verification object includes:
- status: "Approved" | "Declined" | "In Review" | "Expired" | "Not Finished"
- document_type: "Passport" | "Identity Card" | "Driver's License" | "Residence Permit" | null
- document_number, personal_number
- front_image, back_image, portrait_image (signed URLs, expire in 1 hour)
- date_of_birth (YYYY-MM-DD), age (number)
- expiration_date, date_of_issue (YYYY-MM-DD)
- issuing_state, issuing_state_name (ISO 3166-1 alpha-3 + display name)
- first_name, last_name, full_name
- gender ("M" | "F" | "U"), nationality (ISO 3166-1 alpha-3)
- address, formatted_address, parsed_address (street_1, street_2, city,
  region, postal_code, geometry { lat, lng })
- front_image_quality_score / back_image_quality_score (focus, brightness,
  resolution, overall, each 0-100)
- warnings: Array<{ risk, log_type, short_description, long_description }>

## 5. Hard rules — do not change
- Base URL for /v3/* endpoints is verification.didit.me (NOT apx.didit.me).
- Feature enum is UPPERCASE: ID_VERIFICATION, LIVENESS, FACE_MATCH, AML, IP_ANALYSIS.
- Auth header is x-api-key (lowercase, hyphenated).
- Webhook signature header is X-Signature-V2 (NOT X-Signature).
- Always verify webhook signatures before trusting payload data.
- Status casing matches exactly: "Approved", "Declined", "In Review",
  "Expired", "Not Finished" (title-cased, space-separated).

## 6. Pricing reference (public)
- Path A bundled in a full KYC workflow: $0.33 per session
- Path B standalone /v3/id-verification/ call: $0.15 per call
- 500 free verifications every month, forever, on every account.

## 7. Verify your integration
- Sandbox starts on signup at https://business.didit.me — no separate flag.
- Test docs: deterministic synthetic IDs returned in sandbox.
- Switch to live: flip the application's environment toggle in console.

When in doubt: https://docs.didit.me/core-technology/id-verification/overview