إنسان واحد. صوت واحد. مثبت، وليس موعودًا.

You are integrating Didit anti-Sybil identity into a voting / governance / survey / airdrop / quadratic-funding platform. The recipe ensures each real human can be counted exactly once — no duplicates, no bots, no farmed accounts.

Two pillars:

  1. Verify the voter is a real human with a real identity. ONE call to POST /v3/session/ with ID Verification + Liveness + Face Match.
  2. Check the voter has not already been enrolled in this cohort. Face Search 1:N runs the voter's face against every previously-enrolled voter and returns a similarity score. Above threshold → duplicate, block.

Cost:
  - Voter Know Your Customer (KYC) bundle: $0.33 per voter (Sessions API)
  - Face Search 1:N: free (included)
  - Re-vote / next round with Reusable KYC: free (the user proves uniqueness without re-doing KYC)
  - First 500 verifications free every month, forever

PRE-REQUISITES
  - Production API key from https://business.didit.me (sandbox key in 60s, no card).
  - Webhook endpoint with HMAC SHA-256 verification using the X-Signature-V2 header and your webhook secret.
  - A workflow_id from the Workflow Builder that bundles ID Verification + Passive Liveness + Face Match 1:1 + Face Search 1:N + your jurisdiction rules (age, country, sanctions).

STEP 1 — Enrol the voter with the Sessions API

  POST https://verification.didit.me/v3/session/
  Headers:
    x-api-key: <your api key>
    Content-Type: application/json
  Body:
    {
      "workflow_id": "<wf id with KYC + Face Search 1:N>",
      "vendor_data": "<your voter id, max 256 chars>",
      "callback": "https://<your-app>/vote/enrolment/callback",
      "metadata": {
        "purpose": "vote_enrolment",
        "cohort_id": "<your election / round / airdrop id>"
      }
    }

  Response: 201 Created with the hosted session URL. Redirect the voter to it. Sub-2-second median verdict on completion.

STEP 2 — Read the signed webhook on enrolment completion

  Didit POSTs to your callback. Session statuses are Title Case With Spaces:

  Body (excerpted):
    {
      "session_id": "<uuid>",
      "vendor_data": "<your voter id>",
      "status": "Approved",
      "id_verification": { "status": "Approved" },
      "liveness": { "status": "Approved" },
      "face": { "status": "Approved", "similarity_score": 0.94 },
      "face_search": { "status": "Approved", "matches": [] }
    }

  Status enum (exact case): Approved | Declined | In Review | Resubmitted | Expired | Not Finished | Kyc Expired | Abandoned.

  Verify the X-Signature-V2 header BEFORE reading the body — HMAC SHA-256 of the raw bytes with your webhook secret.

STEP 3 — Block duplicates

  When face_search.matches is non-empty AND the top match's similarity is above your threshold (typical: 0.85), DO NOT add the voter to the cohort. The voter has likely been enrolled already, possibly under a different document or alias.

  Recommended handling:
    similarity ≥ 0.95  → block automatically, log the match
    similarity 0.85–0.95 → route to manual review
    similarity < 0.85  → enrol normally

STEP 4 — Privacy-preserving storage

  The platform stores ONLY:
    - voter_pid (pseudonymous identifier — a UUID, NOT the raw document number)
    - unique (boolean)
    - age_band (e.g. "18+", "25-34") — never the raw birth date unless your eligibility rule needs it
    - region (e.g. "EU", "ES") — never the raw address

  Documents, biometrics, and full names stay inside Didit, encrypted at rest. Default retention 5 years post-relationship; configurable per workflow.

STEP 5 — Read the decision on demand

  GET https://verification.didit.me/v3/session/{sessionId}/decision/
  Headers:
    x-api-key: <your api key>

  Returns the full decision JSON. Use this when the tally service needs to confirm a voter is still eligible at vote time.

STEP 6 — Reusable KYC for subsequent rounds

  Once a voter is verified, the next vote / round / airdrop can reuse the verification at no extra cost. The user proves uniqueness with a selfie only — no document re-capture. Same workflow, different cohort id.

WEBHOOK EVENT NAMES
  - Sessions: status changes flow through the standard session webhook.
  - Verify X-Signature-V2 on every payload.

CONSTRAINTS
  - Session statuses use Title Case With Spaces (Approved, In Review). Don't transform them.
  - Face Search 1:N is scoped to YOUR cohort by default — Didit doesn't share faces across customers.
  - Always check the duplicate score BEFORE recording the ballot, never after.
  - The platform never sees the raw ID document or the raw face template — only the verdict and the pseudonymous PID.
  - Default record retention is 5 years post-relationship per the EU AML package; extend per your governing body's rules.

Read the docs:
  - https://docs.didit.me/sessions-api/create-session
  - https://docs.didit.me/sessions-api/retrieve-session
  - https://docs.didit.me/integration/webhooks
  - https://docs.didit.me/core-technology/reusable-kyc/overview

Start free at https://business.didit.me — sandbox key in 60 seconds, 500 verifications free every month, no credit card.