Authorization: Bearer idv_test_YOUR_KEY_HERE

{
  "id": "vs_abc123",
  "status": "pending",
  "sessionToken": "XYBF...",           // internal — the client uses it via the hostedUrl fragment
  "hostedUrl": "https://…/verify/vs_abc123#XYBF...",  // send the user HERE
  "ageThreshold": 18,
  "expiresAt": "2024-01-01T12:30:00Z"  // session expires after 30 minutes
}

<script src="https://www.verisoar.com/widget.js"></script>
<script>
  document.getElementById("verify-btn").addEventListener("click", async () => {
    const { hostedUrl } = await fetch("/your-api/start-verification", {
      method: "POST",
    }).then((r) => r.json());

    IdVerify.open({
      hostedUrl,
      onComplete: (result) => {
        // result.result: "approved" | "declined"
        // result.ageOverThreshold: boolean
        if (result.result === "approved") grantAccess();
      },
      onClose: () => {
        // User closed via ×, IdVerify.close(), or after the result screen
      },
    });
  });
</script>

{
  "id": "vs_abc123",
  "status": "completed",           // pending | consented | processing | completed | failed | expired
  "result": "approved",            // "approved" | "declined" | null (not yet complete)
  "ageOverThreshold": true,        // true if user passed the age check
  "ageThreshold": 18,
  "method": "age_estimation",      // the method the user attempted first
  "escalated": false,              // true if an inconclusive method escalated to the fallback
  "escalatedTo": null,             // the method it escalated to, if any (e.g. "document_liveness")
  "failureReason": null,           // see Failure reasons below
  "clientRef": "user_12345",
  "createdAt": "2024-01-01T12:00:00Z",
  "completedAt": "2024-01-01T12:05:00Z"
}

{
  "type": "verification.completed",
  "data": {
    "id": "vs_abc123",
    "clientRef": "user_12345",
    "result": "approved",
    "ageOverThreshold": true,
    "ageThreshold": 18,
    "failureReason": null,
    "completedAt": "2024-01-01T12:05:00Z"
  },
  "createdAt": "2024-01-01T12:05:00Z"
}

import { createHmac } from "crypto";

function verifyWebhookSignature(rawBody, signature, secret) {
  const [tPart, v1Part] = signature.split(",");
  const timestamp = tPart.replace("t=", "");
  const received = v1Part.replace("v1=", "");

  const expected = createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  if (expected !== received) {
    throw new Error("Webhook signature mismatch — reject this request");
  }
  return JSON.parse(rawBody);
}

// Express example:
app.post("/webhooks/verify", express.raw({ type: "*/*" }), (req, res) => {
  const event = verifyWebhookSignature(
    req.body.toString(),
    req.headers["x-idverif-signature"],
    process.env.VERIFY_WEBHOOK_SECRET, // the whsec_... from the dashboard
  );

  if (event.data.result === "approved") {
    await db.users.update({ where: { id: event.data.clientRef }, data: { ageVerified: true } });
  }

  res.sendStatus(200);
});

// Access
{ "type": "access", "subjectRef": "user_12345" }
→ { "subjectRef": "user_12345", "records": [{ "id": "vs_...", "result": "approved", ... }] }

// Erasure
{ "type": "erasure", "subjectRef": "user_12345" }
→ { "subjectRef": "user_12345", "erased": 1 }

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key."
  }
}