Trustworthy identity — before the first appointment.

You are integrating Didit into a telehealth platform (Doctolib / Teladoc / Hims & Hers / Ro / Tessa Health archetype). You owe the clinical and pharmacy layers a trustworthy patient identity at onboarding and at every refill of a controlled prescription.

Three obligations at onboarding:

  1. Verify the patient's identity — government ID + liveness + face match.
  2. Confirm age — adult, adolescent, or pediatric — to route to the correct clinical pathway without surfacing date of birth on every downstream call.
  3. Capture consent — HIPAA Notice of Privacy Practices acknowledgement, clinical consent (telemedicine + electronic health record + e-prescription), intake history.

One obligation at every refill or new appointment:

  4. Biometric reauthentication — a 1-second selfie matched to the binding template established at onboarding. Anti-diversion control for US Drug Enforcement Administration (DEA) Schedule II-V medications.

Optional but recommended:

  5. Insurance card capture + payer validation — OCR the card, look up the payer, ping eligibility if your stack supports 270/271 EDI.

Pricing (verified live):
  - Onboarding Know Your Customer (KYC) bundle (ID + Liveness + Face Match + IP + AML): $0.33 per patient
  - Age Estimation: $0.10 per patient
  - Custom Questionnaire (HIPAA + clinical consent): $0.10 per submission
  - Biometric Authentication (refill / new visit): $0.10 per auth
  - First 500 KYC 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 for patient onboarding that bundles ID Verification + Passive Liveness + Face Match 1:1 + Age Estimation + Custom Questionnaire.
  - A workflow_id for biometric reauthentication (selfie + liveness + 1:1 face match against the binding template).

STEP 1 — Create the patient onboarding session

  POST https://verification.didit.me/v3/session/
  Headers:
    x-api-key: <your api key>
    Content-Type: application/json
  Body:
    {
      "workflow_id": "<your patient onboarding workflow id>",
      "vendor_data": "<your patient id, max 256 chars>",
      "callback_url": "https://<your-app>/patients/kyc/callback",
      "metadata": {
        "patient_id": "<your internal id>",
        "scheduling_context": "new_visit"
      }
    }

  Response: 201 Created with the hosted session URL. Send it to the patient through your booking flow; they complete identity + consent on their phone in under five minutes.

STEP 2 — Read the signed webhook on onboarding completion

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

  Body (excerpted):
    {
      "session_id": "<uuid>",
      "vendor_data": "<your patient id>",
      "status": "Approved",
      "id_verification": { "status": "Approved", "document_type": "drivers_license", "country_code": "US" },
      "liveness": { "status": "Approved" },
      "face": { "status": "Approved", "similarity_score": 0.94 },
      "age_estimation": { "status": "Approved", "estimated_age_bucket": "ADULT" },
      "questionnaire": { "status": "Approved", "responses": { "hipaa_ack": true, "telehealth_consent": true } }
    }

  Session 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 — Persist the binding biometric template

  When the onboarding session is Approved, Didit stores a biometric template under the patient's vendor_data automatically. You don't need to fetch or store the raw selfie — it's discarded after the template is generated. The template lives in EU data centres and is used for every future face-match against this patient.

STEP 4 — Biometric reauthentication at refill / new appointment

  POST https://verification.didit.me/v3/session/
  Headers:
    x-api-key: <your api key>
    Content-Type: application/json
  Body:
    {
      "workflow_id": "<your biometric reauth workflow id>",
      "vendor_data": "<the same patient id as onboarding>",
      "callback_url": "https://<your-app>/patients/reauth/callback",
      "metadata": {
        "context": "controlled_substance_refill",
        "prescription_id": "<your rx reference>"
      }
    }

  The reauth workflow runs Passive Liveness + Face Match 1:1 against the binding template. Sub-1-second median verdict. $0.10 per auth. Use this BEFORE every controlled-substance e-prescription fires.

STEP 5 — Decide

  Branch logic on the parent session status:
    Approved    → onboard the patient, allow scheduling.
    In Review   → hold the visit, wait for analyst webhook update.
    Declined    → refuse onboarding, log the decline reason.
    Resubmitted → patient updated something; re-read the decision.

  On the reauth session:
    Approved    → fire the e-prescription / book the visit.
    Declined    → refuse the refill, require in-person identity check.

STEP 6 — Insurance card capture (optional)

  Add a Database Validation node to your onboarding workflow against the US payer database (Aetna, BCBS, UnitedHealthcare, Cigna, Kaiser) or the EU national health-insurance system (ES Seguridad Social, DE GKV, FR CPAM, IT SSN). The patient uploads the card; Didit OCRs the member id, group, and payer name, then validates against the payer database. The card image is discarded after parse — only the validated payload is retained.

WEBHOOK EVENT NAMES
  - status.updated — session status changed.
  - data.updated — session data changed (resubmission, consent re-collection).

  Verify X-Signature-V2 on every payload. The webhook secret is per-environment — sandbox key is separate from production.

CONSTRAINTS
  - Session statuses use Title Case With Spaces (Approved, In Review).
  - The biometric template is the binding identity — once a patient is onboarded, every future reauth references it. If you delete the patient, delete the template too via the Business Console (GDPR / HIPAA right-to-deletion compliance).
  - HIPAA-protected information (PHI) and biometric templates are stored in EU data centres for EU patients; US-specific deployments can request a US tenant.
  - For controlled-substance dispense, run a fresh biometric reauth on every refill — this is the anti-diversion control US DEA Schedule II / III requires under the SUPPORT Act.

Read the docs:
  - https://docs.didit.me/sessions-api/create-session
  - https://docs.didit.me/sessions-api/retrieve-session
  - https://docs.didit.me/core-technology/face-match/overview
  - https://docs.didit.me/core-technology/age-estimation/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.