API reference

IDotta lets tenant applications verify their end users remotely. Every verification runs on a session; documents and liveness data attach to that session.

Two separate credentials are used.

Tenant → API

X-Api-Key: idv_live_<key>

Used on every call from the tenant backend. It must never reach a browser.

SDK → API

Authorization: Bearer <jwt>

The short-lived JWT from the POST /v1/sessions response. Scoped to that session and valid for 15 minutes (the session record lives 60 min).

Two flows are supported: the photo path (standard) and the NFC path.

The modules field in the POST /v1/sessions body decides which verification steps run. The SDKs read it from GET /v1/sessions/{id}/config and drive the flow accordingly.

Reusable KYC

With reuse_if_verified: true, if the same applicant_external_id was approved within the last 180 days, has no AML alert and is in the verified state, the session returns approved without asking for a document or liveness. It removes all friction for a returning user.

Tenant rule engine

Under config.rules a tenant can only tighten the verification thresholds — never drop below the platform floor. It raises the bar for automatic approval on higher-risk use cases.

config.rules = {
  "document_score_pass": 85,      // default 70; lower values clamp to 70
  "document_score_review": 55,    // default 45
  "liveness_min_confidence": 75   // default 60
}

The WebSDK is embedded in the tenant page as an iframe. Session creation and API key handling stay entirely on the backend — nothing is exposed to the browser.

1. Create a session on your backend

POST /v1/sessions
X-Api-Key: idv_live_...
Content-Type: application/json

{ "applicant_external_id": "usr_abc123", "metadata": {} }

// Response:
{
  "session_id": "550e8400-...",
  "access_token": "eyJ...",
  "sdk_url": "https://verify.idotta.com/session/550e8400-...?token=eyJ...",
  "expires_at": "2026-09-20T01:00:00Z"
}

2. Embed the iframe

<iframe
  src="https://verify.idotta.com/session/{session_id}?token={access_token}"
  allow="camera; microphone"
  style="width:480px; height:640px; border:none;"
/>

3. Listen for postMessage events

window.addEventListener("message", (e) => {
  const ev = e.data;
  switch (ev.type) {
    case "sdk.ready":         // SDK loaded, camera ready
      break;
    case "step.changed":      // ev.step: "welcome" | "document_front"
      break;                  //   | "document_back" | "liveness" | "processing" | "result"
    case "session.completed": // finished (approved or manual_review)
      break;                  // ev.sessionId → GET /v1/sessions/{id}
    case "session.failed":    // rejected or expired (ev.reason)
      break;
  }
});

Two SDKs are offered for native mobile apps. Both use the same API contract: the session is created on the tenant backend and only the session_id + access_token are handed to the app. The tenant API key never reaches the device.

Flutter — usage

import 'package:idotta_sdk/idotta_sdk.dart';

// session_id + token come from your backend (X-Api-Key stays on the server)
final result = await IdottaSdk.startVerification(
  context, baseUrl: 'https://api.idotta.com', sessionId: sessionId, token: accessToken,
);

React Native — usage

import { IdottaVerification } from '@idotta/react-native-sdk';

<IdottaVerification
  baseUrl="https://api.idotta.com"
  sessionId={sessionId}   // from your backend
  token={accessToken}     // short-lived JWT
  onComplete={(result) => { /* 'approved' | 'rejected' | 'review' | 'expired' */ }}
  onCancel={() => { /* the user left */ }}
/>

Using an SDK is not required. The whole flow can run server to server over the REST API. The session is created with X-Api-Key; the following steps are called with the session-scoped short-lived Bearer JWT.

Your responsibility as the integrator

• You capture the images yourself: the document photos and, for liveness, a frame at each challenge plus a selfie.
• The challenge order comes from the server (/liveness/start) and the server verifies the frames independently.
• You receive the result over a webhook (recommended) or by polling GET /result.

End-to-end example (document path)

# 1) Create the session — backend, X-Api-Key
curl -X POST https://api.idotta.com/v1/sessions \
  -H "X-Api-Key: idv_live_..." -H "Content-Type: application/json" \
  -d '{"applicant_external_id":"usr_abc","modules":["document"]}'

# 2) Document info — Bearer JWT
curl -X POST https://api.idotta.com/v1/sessions/$SID/access-keys \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"method":"manual","document_type":"passport"}'

# 3) Upload the photos — multipart
curl -X POST https://api.idotta.com/v1/sessions/$SID/documents/images \
  -H "Authorization: Bearer $TOKEN" -F "front=@front.jpg" -F "back=@back.jpg"

# 4) Read the result (webhook recommended)
curl https://api.idotta.com/v1/sessions/$SID/result -H "Authorization: Bearer $TOKEN"

Liveness step (headless)

# start → the challenge order comes from the server
curl -X POST https://api.idotta.com/v1/sessions/$SID/liveness/start \
  -H "Authorization: Bearer $TOKEN"
# → { "challenge_id":"...", "challenges":["head_left","blink","head_right"] }

# submit → one frame per challenge + a neutral selfie (ORDER MATTERS)
curl -X POST https://api.idotta.com/v1/sessions/$SID/liveness/submit \
  -H "Authorization: Bearer $TOKEN" -F "challenge_id=..." \
  -F "frames=@head_left.jpg" -F "frames=@blink.jpg" -F "frames=@head_right.jpg" \
  -F "selfie=@selfie.jpg"

Every session response and webhook sent to the tenant carries three fields: status (the key — your code checks this), status_label (a fixed, human-readable display name) and step (the internal step, informational). A rejection with retries left is in_progress; declined is final.

The decision object (on approved, declined, in_review and kyc_expired; null otherwise) carries the check results and the reason codes. decided_by: auto (engine) · manual (analyst) · reuse (reuse). Reason text and parameters are not sent (they may carry personal data); do not show the codes to the end user as they are.

{
  "decided_by": "auto",
  "document_score": 62.5,
  "checks": [
    { "name": "mrz_checksum", "status": "passed", "reason_code": null },
    { "name": "expiry", "status": "failed", "reason_code": "expiry.expired" },
    { "name": "liveness", "status": "passed", "reason_code": null }
  ],
  "warnings": ["expiry.expired"]
}

SDK endpoints (/result, document and liveness responses) return the internal step: created → document_pending → document_processing | nfc_processing → liveness_pending → liveness_processing → approved | review | rejected | expired. In tenant responses this value is step. Every step transition is written to the session_events table (audit log).

Every session event POSTs to the tenant's registered webhook_url. Failed deliveries are retried at increasing intervals.

Signature verification

// Headers
X-Signature:  sha256=<hex_digest>
X-Event-Id:   <uuid>
X-Event-Type: session.approved

// Verifying in Python
import hmac, hashlib

expected = hmac.new(WEBHOOK_SECRET.encode(), request.body, hashlib.sha256).hexdigest()
assert hmac.compare_digest(expected, x_signature.removeprefix("sha256="))

Example payload

{
  "event_type":   "session.approved",
  "event_id":     "a1b2c3d4-...",
  "session_id":   "550e8400-...",
  "status":       "approved",
  "status_label": "Approved",
  "step":         "approved",
  "environment":  "production",
  "decision":     { "decided_by": "auto", "document_score": 91.0, "checks": [ … ], "warnings": [] }
}