使用 Face Search 1:N 识别女巫攻击。一人一账户。

You are integrating Didit Face Search 1:N to catch the same human opening many accounts on your platform — sybil airdrops, referral payout cycles, sign-up bonus stacking, iGaming multi-accounting that bypasses self-exclusion, marketplace fake-review clusters. One API call. One signed webhook. One decision.

WHY THIS SHAPE
  - Email, phone, device, IP can all be rotated cheaply. A human face cannot.
  - Every new sign-up captures one Passive Liveness selfie. Didit searches that selfie against the gallery of prior approved selfies under your account. A high-similarity match means the same person already has an account.
  - Face Search 1:N itself is FREE on every session — no per-search fee. Only the surrounding bundle (ID + Passive Liveness + AML) carries the usual cost. Use the full Know Your Customer (KYC) bundle on sign-up or the Passive Liveness + Face Search subset, depending on what the product needs.

PRE-REQUISITES
  - Production API key from https://business.didit.me (sandbox key in 60 seconds, no credit card).
  - A webhook endpoint with HMAC SHA-256 verification of the X-Signature-V2 header using your webhook secret.
  - A Workflow Builder workflow that contains the Face Search 1:N module. Compose it with Passive Liveness so an attacker cannot upload a still photo of the target.
  - Define what a "match" means for your product. Default: similarity ≥ 0.85 = Declined. 0.75–0.85 = In Review. < 0.75 = Approved.

STEP 1 — Open the sign-up session
  POST https://verification.didit.me/v3/session/
  Headers:
    x-api-key: <your api key>
    Content-Type: application/json
  Body:
    {
      "workflow_id": "<wf id with Face Search 1:N + Passive Liveness>",
      "vendor_data": "<your new-account id, max 256 chars>",
      "callback": "https://<your-app>/sybil-gate/callback",
      "metadata": {
        "surface": "airdrop_claim",
        "campaign": "<your campaign id>"
      }
    }

  Response: 201 Created with a hosted session URL. Redirect inline (web) or open in a Software Development Kit (SDK) webview (mobile). The new account stays UNCREATED on your side until the signed webhook lands.

STEP 2 — Read the signed webhook
  Didit POSTs the verdict. Verify X-Signature-V2 (HMAC SHA-256 of the raw body) BEFORE reading the JSON.

  Payload (excerpted, match case):
    {
      "session_id": "<uuid>",
      "vendor_data": "<your new-account id>",
      "status": "Declined",
      "face_search": {
        "matches": [
          { "session_id": "sess-9182", "similarity": 0.96, "vendor_data": "user-A1" },
          { "session_id": "sess-7733", "similarity": 0.94, "vendor_data": "user-A2" }
        ]
      }
    }

  Session status enum (exact case, Title Case With Spaces): Approved | Declined | In Review | Resubmitted | Expired | Not Finished | Kyc Expired | Abandoned.

STEP 3 — Branch the sign-up
  Approved   → no gallery match. Create the account.
  In Review  → soft match (similarity in your grey-zone band). Queue for human review.
  Declined   → hard match (similarity above your hard threshold). Block, log the matched session_id list as the audit trail.

STEP 4 — Cross-account link signals (optional but cheap)
  Compose Device & IP Analysis ($0.03 / call) in the same workflow. The decision payload surfaces device fingerprint, IP, Autonomous System Number (ASN), country, and city. Combine with your own payment-instrument hash and you can cluster sybils even before the face search confirms.

STEP 5 — Reusable KYC for legitimate cross-product re-entry
  If the user is supposed to reuse one identity across multiple products you own, Reusable KYC lets them replay a previously verified credential at no cost. That is different from sybil abuse — reuse is intentional and you control the issuance.

WEBHOOK EVENT NAMES
  - Sessions: standard session webhook. One endpoint, status field tells you the lifecycle.
  - Verify X-Signature-V2 (HMAC SHA-256) on every payload.

WHAT IT BLOCKS
  - Sybil airdrop / token claims (one person · many wallets)
  - Self-referral payout cycles (sign-up bonus farms)
  - iGaming multi-accounting that bypasses self-exclusion
  - Marketplace fake-review clusters from a single human
  - DAO and community-vote stuffing
  - Welcome-bonus stacking on neobank / brokerage sign-ups

CONSTRAINTS
  - Session statuses use Title Case With Spaces. Never UPPER_SNAKE_CASE for session verdicts — that's the Transactions API.
  - Face Search 1:N WITHOUT Passive Liveness lets an attacker upload a still photo of the target. Always compose them together.
  - Thresholds are tunable per workflow. Start at 0.85 hard / 0.75 soft and adjust based on your false-positive tolerance.
  - The gallery is scoped to your account — no cross-customer leakage by design.

Read the docs:
  - https://docs.didit.me/sessions-api/create-session
  - https://docs.didit.me/core-technology/face-search/overview
  - https://docs.didit.me/core-technology/liveness/overview
  - https://docs.didit.me/integration/webhooks

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