Adhere Web SDK

The Adhere Web SDK enables you to rapidly and securely verify user identities and perform facial liveness checks directly in your web applications. The SDK mounts a drop-in widget over your application, handling document capture, identity verification, and liveness detection — all in one seamless flow.

Features

Drop-in UI Modal — Responsive, animated widget that overlays your app via SmartComplyFlow.open().
CDN & npm Support — Install via npm/yarn or load directly from a CDN with zero build steps.
Dynamic Routing — Automatically adapts document and verification requirements from your dashboard configuration.
Single-Use Sessions — clientId is your permanent integration key (from your SDK Config) and is reused for every session. Each createSession() call issues a fresh, single-use session token — that token, not the clientId, is what’s scoped to one verification.
Multi-Country Identity — Supports data and document channels across Nigeria (BVN, NIN, passports, driver’s licenses, voter’s cards, and more), Ghana, Kenya, South Africa, and Cote d’Ivoire, with generic passport verification available for other countries and country-agnostic liveness/face-match checks — exact channels depend on what’s enabled in your dashboard.
Two-Sided Document Capture — Front is always required; back is required, optional, or not offered depending on the document type (e.g. NIN is optional-back, since not every physical NIN document has a usable reverse side).
Hardware Agnostic Liveness — Uses native webcam and MediaRecorder API for cross-platform compatibility. A single passive scan (blink + natural head movement) — no discrete step-by-step prompts.

Installation

Option 1 — CDN (No build step required, recommended)

Add the script tag to your HTML:

<script src="https://cdn.jsdelivr.net/npm/smartcomply-web-sdk@1/dist/smartcomply.browser.js"></script>

The SDK is available globally as window.SmartComplySDK:

const { SmartComplyFlow, SmartComply } = window.SmartComplySDK;

@1 always resolves to the latest 1.x.x release — bug fixes and new features reach your site automatically the moment we publish them, with no code change on your end, ever. We commit to never shipping a breaking change as a 1.x release; if a breaking change is ever needed, it ships as 2.0.0, and @1 keeps serving the last safe 1.x release until you deliberately opt in. This is the same versioning model used by most public JS SDKs (Stripe.js, Google Maps, etc.).

Other CDN options:

<!-- Always use the newest release, including any future major version — for
     prototyping, or if you specifically want every change instantly -->
<script src="https://cdn.jsdelivr.net/npm/smartcomply-web-sdk@latest/dist/smartcomply.browser.js"></script>

<!-- Pin to one exact version — only if you need manual control over
     updates. Replace X.Y.Z with the version you've tested against. -->
<script src="https://cdn.jsdelivr.net/npm/smartcomply-web-sdk@X.Y.Z/dist/smartcomply.browser.js"></script>

@1/@latest re-resolve on every page load — that’s what makes them self-updating, with no rebuild or redeploy needed on your side. An exact @X.Y.Z pin never moves until you manually change the number in your script tag. See npmjs.com/package/smartcomply-web-sdk for release history.

Option 2 — npm / yarn

npm install smartcomply-web-sdk
# or
yarn add smartcomply-web-sdk

import { SmartComplyFlow } from 'smartcomply-web-sdk';

Unlike the CDN, npm has no auto-updating option — this is true for every npm package, not specific to ours. npm install resolves to the latest version at the moment you run it, then locks that exact version in package-lock.json (or yarn.lock); it will not change again on its own. Run npm update smartcomply-web-sdk periodically (or before each deploy) to pick up new fixes — this stays within the ^1.0.x range already set in your package.json, and we commit to never shipping a breaking change within 1.x, so it’s always safe to run. Check npmjs.com/package/smartcomply-web-sdk for the current version number.

The easiest way to integrate is the drop-in widget. It handles the complete verification flow automatically.

SmartComplyFlow.open({
  apiKey: "your_api_key_here",
  clientId: "your_client_id_here",
  environment: "production", // sandbox is not currently available

  onComplete: (result) => {
    console.log("Verification complete:", result);
    // result = { entryId, sessionId, status, submittedAt }
  },
  onError: (error) => {
    console.error("Verification failed:", error);
  },
  onClose: () => {
    console.log("Widget closed.");
  }
});

Get your API Key and Client ID from your Adhere Dashboard — both come from your SDK Config and are permanent; reuse the same values for every session. What’s single-use is the session token the SDK obtains internally via createSession() (30-minute expiry, revoked after submission) — you never see or manage that token directly through the drop-in widget.The widget warns the user 2 minutes before this 30-minute expiry, then automatically shows a “session expired” message and closes itself (firing onClose) once the deadline actually passes — with a brief grace period if the user is mid-scan, so an active capture is never torn down mid-flow. If you need a fresh verification after that, call SmartComplyFlow.open() again to start a new session (available from smartcomply-web-sdk@1.0.76).

Configuration Parameters

Parameter	Type	Required	Description
`apiKey`	string	✅ Yes	Your API key from the Adhere Dashboard
`clientId`	string	✅ Yes	Your permanent client ID from the Adhere Dashboard (SDK Config) — the same value for every session
`environment`	string	No	`"production"` (default)
`onComplete`	function	No	Callback fired when verification completes successfully
`onError`	function	No	Callback fired on error
`onClose`	function	No	Callback fired when the widget is closed

sandbox is not currently available — use "production" for all integration and testing today. This section will be updated once sandbox is back.

Environment URLs

Environment	Base URL
`production`	`https://adhere-api.smartcomply.com`

Branding

The SDK Config on your Dashboard supplies the brand name, description and theme colour that initializeConfig() returns, and the widget renders them.

The logo uploaded under Settings → Integrations → SDK → Brand Details is rendered by the Android and iOS SDKs only. The Web SDK does not show it yet, so a config used by both carries your mark on mobile and the default on web.

Framework Examples

React

import { SmartComplyFlow } from 'smartcomply-web-sdk';

export default function VerifyButton() {
  const handleVerify = () => {
    SmartComplyFlow.open({
      apiKey: process.env.REACT_APP_API_KEY,
      clientId: process.env.REACT_APP_CLIENT_ID,
      environment: "production",
      onComplete: (result) => console.log("Done:", result),
      onError: (err) => console.error("Error:", err),
    });
  };

  return <button onClick={handleVerify}>Verify Identity</button>;
}

Vue

<template>
  <button @click="handleVerify">Verify Identity</button>
</template>

<script setup>
import { SmartComplyFlow } from 'smartcomply-web-sdk';

const handleVerify = () => {
  SmartComplyFlow.open({
    apiKey: import.meta.env.VITE_API_KEY,
    clientId: import.meta.env.VITE_CLIENT_ID,
    environment: "production",
    onComplete: (result) => console.log("Done:", result),
    onError: (err) => console.error("Error:", err),
  });
};
</script>

Plain HTML (CDN)

<!DOCTYPE html>
<html>
<head>
  <!-- @1 always serves the latest 1.x release — no code change needed
       when we ship fixes. See Installation above for other options. -->
  <script src="https://cdn.jsdelivr.net/npm/smartcomply-web-sdk@1/dist/smartcomply.browser.js"></script>
</head>
<body>
  <button onclick="startVerification()">Verify Identity</button>

  <script>
    const { SmartComplyFlow } = window.SmartComplySDK;

    function startVerification() {
      SmartComplyFlow.open({
        apiKey: "your_api_key_here",
        clientId: "your_client_id_here",
        environment: "production",
        onComplete: (result) => console.log("Done:", result),
        onError: (err) => console.error("Error:", err),
      });
    }
  </script>
</body>
</html>

Headless API (Advanced)

For full control over the UI, use the SmartComply class directly without the modal.

import { SmartComply } from 'smartcomply-web-sdk';

const sdk = new SmartComply({
  apiKey: "your_api_key_here",
  clientId: "your_client_id_here",
  environment: "production",
});

const run = async () => {
  // 1. Create a session — sessions last 30 minutes and are single-use
  //    (revoked as soon as liveness is submitted)
  await sdk.createSession();

  // 2. Fetch SDK configuration — brand, theme, and available channels per country
  const config = await sdk.initializeConfig();
  console.log("Verification type:", config.verification_type);
  console.log("Channels:", config.channels);
  // config.channels["nigeria"] is an array of:
  //   { id, name, code?, requires_back_side?: boolean | "optional", fields: [...] }

  // 3a. Data verification (BVN/NIN/etc.) — validates against the government database
  const verifyResult = await sdk.onboarding.verify({
    identity_type_id: 1,  // channel id from config.channels
    fields: { bank_verification_number: "12345678901" }
  });
  const identityCheckId = verifyResult.data?.identity_check_id;

  // 3b. Document verification — capture front (and back, if the channel's
  //     requires_back_side is true or "optional") instead of step 3a.
  // const documentFront: Blob = /* from a file input or camera capture */;
  // const documentBack: Blob | undefined = /* only if the channel needs/offers one */;

  // 4. Run liveness check — requires an HTMLElement container for the camera.
  //    Runs a single passive scan (blink + natural head movement); the
  //    3rd argument is a descriptive tag for your dashboard, not a live
  //    prompt sequence the UI steps through.
  const container = document.getElementById("camera-container") as HTMLElement;
  const liveness = await sdk.liveness.startCheck(
    container,
    {
      identifier: "12345678901",
      identifier_type: "bvn",
      country: "NG",
      identity_check: identityCheckId,   // link to the data-verification result above
      // document: documentFront,        // for document verification instead
      // document_back: documentBack,
    },
    ["BLINK", "TURN_HEAD"]
  );
  console.log("Liveness status:", liveness.status); // "processing" — final
  // pass/fail result arrives via webhook, not this return value.
};

run();

The liveness scan itself has its own 12-second capture window, separate from the 30-minute session TTL above. This timer starts only when active recording begins — right after the camera has centered on the user’s face and briefly re-stabilized (autofocus/exposure) — not from when the camera first opens. From that point, the widget shows a countdown ring around the face oval; the scan must detect the passive liveness signal (blink + natural head movement) within those 12 seconds or it fails with a “Time’s Up” screen and a Try Again button that restarts the scan using the same liveness entry (no re-charge).This timer is entirely local to the browser tab and only runs during the active scan — it is cleared the moment the scan resolves (success or timeout) and does not persist, run in the background, or resume if the user leaves and returns. In practice this means: if the user has already completed the liveness/face step and moved on to another part of the flow (e.g. reviewing their submission), the 12-second window is long finished and irrelevant — nothing about that step can time out again. The only clock still running at that point is the 30-minute session TTL, which governs the SDK’s API calls generally, not the completed scan.

onComplete Payload

onComplete fires as soon as the user finishes their part of the flow (the “Verification Submitted” screen renders) — it is a submission receipt, not a verification verdict. Backend processing (face match, document read, government DB check) continues after this fires, and status is always "processing" here regardless of the eventual outcome. The real pass/fail result only ever arrives via webhook.

{
  "entryId": 365,
  "sessionId": "da7623bd-9158-4b56-a9e4-4bccf3c0133f",
  "status": "processing",
  "submittedAt": "2026-06-05T23:11:22.873161+00:00",
  "verificationResult": {
    "status": "success",
    "code": "VERIFICATION_COMPLETE",
    "data": { "first_name": "Amara", "last_name": "Okafor", "identity_check_id": 123 }
  }
}

verificationResult is only present for data verification (BVN/NIN) — it’s the immediate government-database lookup result confirming the ID number matched a real record. It says nothing about the face match, which is still pending. It’s absent for document verification flows.

Receiving Results (Webhook)

The backend delivers exactly one liveness.completed webhook per verification, to the URL configured in your SDK Config, once face matching (and OCR / government DB check, depending on the flow) has finished.

This is the SDK’s own webhook — configured per SDK Config and specific to liveness.completed. It’s separate from the platform-wide webhook system described in Webhooks (transaction monitoring, general KYC module events, {success, module, event, data} shape). Both currently sign with HMAC-SHA256 and a sha256=-prefixed header, hex-encoded — verify against the raw request body either way.

Payload shape

POST https://your-server.com/webhook
Content-Type: application/json
X-Adhere-Signature: sha256=<hmac-sha256-hex>

{
  "event": "liveness.completed",
  "verification_id": 42,
  "verification_type": "data_verification",
  "status": "passed",
  "failure_reason": null,
  "timestamp": "2026-08-08T10:15:00.000Z",
  "subject": {
    "identifier": "12345678901",
    "identifier_type": "National Identity Number (NIN)",
    "country": "nigeria"
  },
  "biometrics": {
    "liveness_verified": true,
    "face_match": {
      "attempted": true,
      "verified": true,
      "confidence_percentage": 70.0,
      "decision": "MATCH"
    },
    "selfie_url": "https://.../autoshot.jpg",
    "face_analysis": {
      "gender": "Female",
      "dominant_emotion": "neutral",
      "face_quality": {
        "face_detected": true,
        "face_confidence": 0.98,
        "blur_score": 142.3,
        "is_blurry": false
      }
    }
  },
  "activity": {
    "session_id": "da7623bd-9158-4b56-a9e4-4bccf3c0133f",
    "started_at": "2026-08-08T10:12:00.000Z",
    "submitted_at": "2026-08-08T10:14:30.000Z",
    "completed_at": "2026-08-08T10:15:00.000Z",
    "duration_seconds": 180
  },
  "request_context": {
    "ip": { "address": "102.67.1.66", "city": "Lagos", "country_code": "NG" },
    "device": { "user_agent": "Mozilla/5.0 ...", "type": "desktop", "os": "Windows" }
  },
  "customer_profile": {
    "first_name": "AMARA",
    "last_name": "OKAFOR",
    "other_name": null,
    "date_of_birth": "01-Jan-1997",
    "age": 29,
    "gender": "Female",
    "id_number": "12345678901",
    "serial_number": null,
    "occupation": null,
    "place_of_birth": null,
    "place_of_live": "...",
    "date_of_issue": null,
    "photo_url": null
  }
}

For document verification, the same top-level shape applies, with verification_type: "document_verification" and a document block (OCR fields + document-to-selfie face match) instead of customer_profile:

"document": {
  "status": "verified",
  "document_type": "passport",
  "is_expired": false,
  "first_name": "AMARA",
  "last_name": "OKAFOR",
  "date_of_birth": "1997-01-01",
  "age": 29,
  "gender": "Female",
  "nationality": "NGA",
  "document_number": "A12345678",
  "expiry_date": "2030-06-15",
  "issue_date": "2020-06-15",
  "issuing_authority": "...",
  "document_url": "https://.../document.jpg",
  "document_back_url": null,
  "face_match": {
    "attempted": true,
    "verified": true,
    "confidence_percentage": 55.0,
    "reason": null,
    "selfie_url": "https://.../autoshot.jpg",
    "document_face_url": "https://.../document_face.jpg"
  }
}

document also carries place_of_birth, place_of_issue, address, district, division, location, sub_location, serial_number, and barcode_number — null unless the specific document type carries that field (e.g. serial/barcode numbers mainly apply to newer Kenyan ID cards). face_match.reason is populated with a user-facing explanation when verified is false or the match was skipped.

face_match.decision ("MATCH", "NO_MATCH", or "REJECTED") is what verified is actually derived from — read decision rather than comparing confidence_percentage against a threshold of your own, since our internal match threshold isn’t part of this payload and may change over time. "REJECTED" means liveness/anti-spoofing failed before any comparison ran, so confidence_percentage can be absent or 0 alongside verified: false for a reason unrelated to how similar the faces looked.

status: "passed" means the check ran to completion — not that the person matched. A face mismatch, low confidence score, or expired document still reports status: "passed", with the real outcome recorded in biometrics.face_match.verified (and document.is_expired for document verification). status: "failed" is reserved for cases where the check itself couldn’t run (service error, no selfie captured, government DB rejection). Never gate access on status alone — always check face_match.verified.

verification_id matches the entryId your onComplete callback received.

Verify the signature

The signature header is X-Adhere-Signature: sha256=<hex> — note the sha256= prefix. It’s computed over the exact compact-JSON bytes of the request body, so your handler must verify against the raw body, not a re-serialized copy of the parsed JSON (re-stringifying can produce different bytes and the signature will never match).

const crypto = require("crypto");

app.post(
  "/webhook/smartcomply",
  express.json({ verify: (req, res, buf) => { req.rawBody = buf; } }),
  (req, res) => {
    const signature = (req.headers["x-adhere-signature"] || "").replace(/^sha256=/, "");
    const secret = process.env.WEBHOOK_SECRET.replace(/-/g, "");
    const expected = crypto.createHmac("sha256", secret).update(req.rawBody).digest("hex");

    const isValid =
      signature.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(signature, "hex"), Buffer.from(expected, "hex"));

    if (!isValid) return res.status(401).send("Bad signature");

    const { event, verification_id, status, biometrics, document } = req.body;

    // status === "passed" only means the check ran to completion — check
    // the real outcome before treating the user as verified:
    const faceMatched = biometrics?.face_match?.attempted
      ? biometrics.face_match.verified === true
      : true; // not attempted (e.g. NIN slip, CAC) — nothing to fail here
    const documentOk = document ? document.is_expired === false : true;

    if (event === "liveness.completed" && status === "passed" && faceMatched && documentOk) {
      markUserAsVerified(verification_id);
    } else if (event === "liveness.completed") {
      recordVerificationOutcome(verification_id, req.body);
    }

    res.json({ received: true });
  }
);

Security Notes

Client ID — Permanent, from your SDK Config. Reuse the same clientId for every session — there’s no per-session ID to generate.
API Key — Never expose your API key in client-side code in production. Use environment variables.
Session Tokens — The single-use part. Automatically obtained and managed by the SDK per verification via createSession(), expire after 30 minutes, and are revoked immediately once liveness is submitted.

Troubleshooting

Error Code	HTTP	Cause	Fix
`INVALID_API_KEY`	401	Bad or missing `apiKey`	Check your `apiKey` value in the SDK Config
`SDK_CONFIG_NOT_FOUND`	404	Invalid `clientId`	Check your `clientId` value — it should be the UUID from your SDK Config, not regenerated per session
`INVALID_SESSION`	401	Session token missing, malformed, expired (30 min), or already revoked (a session is single-use — it’s consumed once liveness is submitted)	Call `createSession()` again to get a fresh token; `clientId`/`apiKey` stay the same
`VALIDATION_ERROR`	400	Missing or invalid fields in the request	Check `data.errors` in the response for which field failed
`RETRY_LIMIT_EXCEEDED`	429	User exceeded the retry limit for confirmation/liveness attempts	The user must restart with a new session
`INSUFFICIENT_BALANCE`	402	Wallet balance too low	Top up your wallet in the dashboard
`Camera not available`	—	Browser blocked camera access	Ensure HTTPS and camera permissions are granted

API Reference

Web SDK

Adhere Web SDK

Features

Installation

Option 1 — CDN (No build step required, recommended)

Option 2 — npm / yarn

Quick Start — Drop-in Widget (Recommended)

Configuration Parameters

Environment URLs

Branding

Framework Examples

React

Vue

Plain HTML (CDN)

Headless API (Advanced)

onComplete Payload

Receiving Results (Webhook)

Payload shape

Verify the signature

Security Notes

Troubleshooting

​Adhere Web SDK

​Features

​Installation

​Option 1 — CDN (No build step required, recommended)

​Option 2 — npm / yarn

​Quick Start — Drop-in Widget (Recommended)

​Configuration Parameters

​Environment URLs

​Branding

​Framework Examples

​React

​Vue

​Plain HTML (CDN)

​Headless API (Advanced)

​onComplete Payload

​Receiving Results (Webhook)

​Payload shape

​Verify the signature

​Security Notes

​Troubleshooting

Adhere Web SDK

Features

Installation

Option 1 — CDN (No build step required, recommended)

Option 2 — npm / yarn

Quick Start — Drop-in Widget (Recommended)

Configuration Parameters

Environment URLs

Branding

Framework Examples

React

Vue

Plain HTML (CDN)

Headless API (Advanced)

onComplete Payload

Receiving Results (Webhook)

Payload shape

Verify the signature

Security Notes

Troubleshooting