Verifiqueu una vegada. Reutilitzeu per sempre. Mateixa marca. Soci de confiança. Mateixa identitat.

You are integrating Didit reusable identity. Your users get verified once with full KYC and then re-present that verification on every subsequent service — your own platforms (same-platform reuse via Reusable KYC) and trusted partner platforms (cross-partner Share Session API).

Three pillars:

  1. Verify once with full KYC ($0.33 bundle) via POST /v3/session/.
  2. On the SAME platform, returning users re-prove identity with a selfie only — free, via the Reusable KYC workflow.
  3. To a TRUSTED PARTNER, the first platform generates a short-lived share token (POST /v3/session/{id}/share/); the partner imports it (POST /v3/session/import-shared/) and the user lands fully onboarded.

Cost:
  - First verification: $0.33 (Sessions API)
  - Same-platform selfie-only reauth: free (Reusable KYC workflow)
  - Cross-partner import: priced per call, from $0.30 — Partner B pays the import fee
  - 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.
  - Two workflows in the Workflow Builder:
      wf_first_verification    — ID Verification + Passive Liveness + Face Match 1:1 + Device & IP Analysis + Anti-Money Laundering (AML) Screening
      wf_reusable_kyc          — Reusable KYC (selfie-only reauth)
  - For cross-partner: a pre-arranged backend channel with the partner (a webhook, a queue, or even an authenticated REST call between your services) so the share token can be transmitted out-of-band.

STEP 1 — First verification (Sessions API)

  POST https://verification.didit.me/v3/session/
  Headers:
    x-api-key: <your api key>
    Content-Type: application/json
  Body:
    {
      "workflow_id": "<wf_first_verification>",
      "vendor_data": "<your user id, max 256 chars>",
      "callback": "https://<your-app>/identity/callback"
    }

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

STEP 2 — Read the signed webhook on verification completion

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

  Body (excerpted):
    {
      "session_id": "<uuid>",
      "vendor_data": "<your user id>",
      "status": "Approved",
      "id_verification": { "status": "Approved" },
      "liveness": { "status": "Approved" },
      "face": { "status": "Approved", "similarity_score": 0.94 }
    }

  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.

  Store the (user_id, session_id, status) tuple. session_id is the handle you reuse for shares.

STEP 3 — Same-platform reuse (Reusable KYC selfie-only reauth)

  When the same user returns for a new flow:

  POST https://verification.didit.me/v3/session/
  Body:
    {
      "workflow_id": "<wf_reusable_kyc>",
      "vendor_data": "<your user id>",
      "callback": "https://<your-app>/identity/reauth-callback"
    }

  The hosted UI prompts the user for a selfie only — no document re-capture. Didit matches the selfie against the original verified template, returns Approved in under two seconds, free.

STEP 4 — Cross-partner share (Partner A generates a share token)

  Only finished sessions (Approved / Declined / In Review) can be shared.

  POST https://verification.didit.me/v3/session/{sessionId}/share/
  Headers:
    x-api-key: <Partner A's api key>
    Content-Type: application/json
  Body:
    {
      "audience": "<partner_b_identifier>",
      "expires_in": 900
    }

  Response (excerpted):
    {
      "share_token": "eyJhbGciOiJIUzI1NiJ9...",
      "session_kind": "kyc",
      "expires_at": "<ISO8601>"
    }

  Transmit the share_token to Partner B via your pre-arranged backend channel.

STEP 5 — Cross-partner import (Partner B imports the session)

  POST https://verification.didit.me/v3/session/import-shared/
  Headers:
    x-api-key: <Partner B's api key>
    Content-Type: application/json
  Body:
    {
      "share_token": "eyJhbGciOiJIUzI1NiJ9...",
      "workflow_id": "<Partner B's workflow id>",
      "vendor_data": "<Partner B's internal user id>",
      "trust_review": true
    }

  trust_review options:
    true  — Partner B trusts Partner A's verdict (Approved / Declined). The imported session keeps the original status.
    false — Partner B copies the data but sets status to "In Review" so Partner B's compliance team can apply their own thresholds.

  Constraints (verified against mintlify-docs/core-technology/reusable-kyc/share-kyc-via-api.mdx):
    - A specific session can be imported only ONCE into a given partner application.
    - The share_token is short-lived (defaults to 15 minutes).
    - End-to-end encrypted; only the named audience can import.

STEP 6 — Audit the consent + the share

  Log every share + every import with:
    - user_pid (the pseudonymous user identifier)
    - audience (which partner)
    - purpose (onboarding, lending, payments, etc.)
    - scope (kyc, kyc + aml, kyc + kyb)
    - share_token id + expiry
    - import status
  Default retention 5 years post-relationship per the EU AML package; longer under your supervisor's guidance.

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.
  - Share tokens are scoped to the named audience and the named purpose — they're not bearer tokens for free reuse.
  - The user must consent before a share happens. Capture explicit consent in your UI; Didit logs the consent against the session.
  - Reusable KYC selfie-only reauth is free; cross-partner imports are priced at Partner B's account.
  - 200+ fraud signals are evaluated on every fresh session at no extra cost.

Read the docs:
  - https://docs.didit.me/sessions-api/create-session
  - https://docs.didit.me/sessions-api/share-session/share
  - https://docs.didit.me/sessions-api/share-session/import
  - https://docs.didit.me/core-technology/reusable-kyc/overview
  - https://docs.didit.me/core-technology/reusable-kyc/share-kyc-via-api
  - 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.