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: "OCR" }   (UPPERCASE — strict enum; "OCR" is the
         workflows-endpoint value for ID Verification, and the only one
         POST /v3/workflows/ accepts for it)

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: url (the hosted verification link) — 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. X-Signature-V2 signs the CANONICAL JSON, not
  the raw body bytes — that is what makes it survive a proxy or body parser
  that re-encodes the payload. (The legacy X-Signature header is the one
  computed over the raw bytes.) The canonical form is the sender's Python
  json.dumps(sort_keys=True, separators=(",", ":"), ensure_ascii=False)
  after whole-valued floats become ints. Reproduce those bytes EXACTLY —
  do NOT "parse, sort keys, JSON.stringify", which fails in four ways:
    - Numbers come from the wire text, never from parsed doubles: the sender
      signs 1000000000000000129 digit for digit, JSON.parse rounds it. Read
      the body as TEXT (express.text, not express.json()) and re-emit
      integers through BigInt(source). Register the webhook route ABOVE any
      global app.use(express.json()): the first parser to run consumes the
      stream, and the digits are gone before the route sees them.
    - Floats use Python's repr: 1e-05, not 0.00001; 27.0 becomes 27.
    - Keys sort by Unicode CODE POINT, as strings: "10" before "2", and
      U+FF21 before U+1F642 (JavaScript's default .sort() reverses the latter
      because it compares UTF-16 code units).
    - Serialise straight from the sorted entries; never rebuild an object
      first, because JavaScript moves integer-like keys to the front.
  Then HMAC-SHA256 with secret_shared_key, hex-encode, and compare to the
  X-Signature-V2 header in constant time (crypto.timingSafeEqual).
- Freshness comes from the SIGNED body field "timestamp" (Unix seconds):
  reject a delivery whose body timestamp is more than 300 seconds from now,
  and require the X-Timestamp header to equal it. Never check the header
  alone — it is not signed, so a replayed delivery with a rewritten header
  would pass. This is the Node 22 + Express handler, paste it verbatim:

// Your endpoint receives a signed ID Verification payload
const crypto = require("node:crypto"); // ESM: import crypto from "node:crypto"
// X-Signature-V2 = HMAC over the canonical JSON, never the raw bytes. Match the sender byte for
// byte: keys sorted by code point, integers digit for digit, floats in Python's repr.
class Num { constructor(src) { this.src = src; } } // a number as written on the wire, not a double
const num = (s) => { if (/^-?\d+$/.test(s)) return BigInt(s).toString(); const n = +s; // ints stay exact
  if (Number.isInteger(n)) return BigInt(n).toString(); const [m, e] = n.toExponential().split("e"); // 27.0 -> 27
  return +e >= -4 ? String(n) : `${m}e-${String(-e).padStart(2, "0")}`; }; // 1e-05, not 0.00001
const byCodePoint = (a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b)); // UTF-8 order = Python's
const canon = (v) => Array.isArray(v) ? `[${v.map(canon)}]` : v instanceof Num ? num(v.src)
  : v && typeof v === "object" ? `{${Object.keys(v).sort(byCodePoint).map((k) => `${JSON.stringify(k)}:${canon(v[k])}`)}}`
  : JSON.stringify(v);
// Read the body as text: express.json() would round 1000000000000000129 to a double first.
// Register this route ABOVE any global app.use(express.json()): the first parser to run
// consumes the stream, and a body it already parsed has lost the digits the signature covers.
app.post("/webhooks/didit", express.text({ type: "application/json" }), (req, res) => {
  const exact = JSON.parse(req.body, (k, v, c) => typeof v === "number" ? new Num(c.source) : v); // Node 21+
  const body = JSON.parse(req.body);
  const mac = crypto.createHmac("sha256", SECRET).update(canon(exact), "utf8").digest("hex");
  const sig = Buffer.from(String(req.headers["x-signature-v2"] ?? ""));
  // Freshness comes from the signed body timestamp; the header alone is unsigned and replayable.
  const ts = body.timestamp, fresh = String(ts) === req.headers["x-timestamp"]
    && Math.abs(Date.now() / 1000 - ts) <= 300;
  if (!fresh || sig.length !== mac.length
    || !crypto.timingSafeEqual(sig, Buffer.from(mac))) return res.sendStatus(401);
  const { status, decision, vendor_data } = body;
  // status: Approved | Declined | In Review | Expired | Not Finished
  res.sendStatus(200);
});

## 4. Reading the report
Both paths return the same FIELDS, in a different container:
- Path A (session decision + webhook): decision.id_verifications is an ARRAY
  — one entry per ID Verification node in the workflow. Select the entry you
  want by its node_id, never by index and never as a singular object:
      const doc = decision.id_verifications.find(
        (v) => v.node_id === "id_verification_1"
      );
  Every other feature is plural the same way: liveness_checks,
  face_matches, aml_screenings, ip_analyses, nfc_verifications,
  poa_verifications, database_validations.
- Path B (POST /v3/id-verification/): a single id_verification object on the
  response body — this endpoint runs exactly one document.

Each id_verification entry 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: OCR (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), and it signs
  the canonical JSON — never HMAC the raw bytes under that header, and never
  canonicalise a parsed object: read the body as text and serialise the
  sender's bytes (see the handler in section 3).
- Webhook freshness is the signed body "timestamp" (300 s window); the
  X-Timestamp header must equal it and is never checked on its own.
- decision.id_verifications is an array; select the node you want by node_id.
- 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