Skip to content

api.xiomid.com

Two API calls and a webhook

Create an applicant, open a session, and let xiomid handle the camera, the checks and the review. Your backend hears the decision.

import crypto from 'node:crypto';

// Sign each request: HMAC-SHA256(secret, ts + method + path + body)
async function xiomid(method, path, body) {
  const ts = Math.floor(Date.now() / 1000).toString();
  const payload = body ? JSON.stringify(body) : '';
  const sig = crypto.createHmac('sha256', process.env.XIOMID_SECRET)
    .update(ts + method + path + payload).digest('hex');
  const res = await fetch('https://api.xiomid.com' + path, {
    method,
    headers: {
      'Content-Type': 'application/json',
      'X-Xiomid-App-Token': process.env.XIOMID_APP_TOKEN,
      'X-Xiomid-Ts': ts,
      'X-Xiomid-Sig': sig,
    },
    body: payload || undefined,
  });
  return res.json();
}

const applicant = await xiomid('POST', '/v1/applicants', {
  externalUserId: 'user_123',
  flow: 'standard-kyc',
  email: 'jane@example.com',
});
const session = await xiomid('POST', `/v1/applicants/${applicant.id}/sessions`);
// → { token, url, expiresAt }: redirect to session.url, or embed the SDK

How it fits together

The same three steps whether you redirect to the hosted page or embed the flow in your own.

  1. 01

    Create an API key

    Each brand has its own sandbox and live keys. Requests are signed with HMAC-SHA256 over the timestamp, method, path and body; the secret never leaves your server.

  2. 02

    Open a session

    Create an applicant with your own user id and a flow, then a session. You get a link to the hosted page and a token for the SDK.

  3. 03

    Hear the decision

    A signed webhook tells your backend when the applicant submits, when a decision is made and when a reviewer changes it.

Hosted page or SDK

Send applicants to the hosted page at verify.xiomid.com or your own domain, by redirect, email or SMS. Or load the SDK and open the flow inline or as a modal in your app.

Either way, the camera guidance, liveness, retakes and phone handoff come built in, in English, Turkish and German.

<div id="kyc"></div>
<script src="https://cdn.xiomid.com/sdk/v1/sdk.js"></script>
<script>
  const verification = xiomid.init({
    token: 'SESSION_TOKEN', // from the session you just created
    mode: 'inline',
    container: '#kyc',
  });
  verification.on('result', () => window.location.assign('/onboarding/done'));
  verification.open();
</script>

Signed webhooks

Every event is signed with your webhook secret (X-Xiomid-Signature: t=…,v1=…) and retried with backoff when your endpoint is down.

// POST /hooks/xiomid
// X-Xiomid-Signature: t=1731662651,v1=5f2b…
{
  "id": "evt_3Fq81Lz",
  "type": "applicant.reviewed",
  "applicantId": "apl_7Kq2",
  "externalUserId": "user_123",
  "flow": "Standard KYC",
  "status": "approved",
  "score": 92,
  "reasonCodes": [],
  "reusedFrom": null,
  "sandbox": true,
  "createdAt": "2026-11-15T09:24:11Z"
}

Events

  • applicant.createdApplicant created
  • applicant.startedApplicant started the flow
  • step.completedStep completed
  • applicant.submittedApplicant submitted
  • applicant.reviewedDecision made (approved, review or rejected)
  • applicant.decision_changedDecision changed by a reviewer
  • applicant.action_requiredApplicant asked to redo a step
  • applicant.monitoring_dueRe-verification due (monitoring)
  • reauth.completedSelfie re-check finished
  • screening.alertAML screening found a possible match
  • screening.resolvedAML match resolved by a reviewer
  • privacy.erasedApplicant data erased (GDPR / KVKK)
Webhook endpoints with their delivery rates

A sandbox that is never billed

Sandbox keys run the real flow without checking anything for real. Use the last name APPROVE, REVIEW or REJECT to force a result, and test documents to walk through every step.

Endpoints

  • POST/v1/applicantsCreate an applicant for a flow
  • POST/v1/applicants/{id}/sessionsOpen a session: link, token and expiry
  • GET/v1/applicants/{id}Status and decision
  • GET/v1/applicants/{id}/reportSteps, checks, scores and reason codes
  • POST/v1/applicants/{id}/resetLet the applicant try again
  • GET/v1/flowsThe brand’s published flows
  • GET/v1/usageUsage for a month
Full API reference

Get your sandbox keys

Sign up, create a key and run your first verification in minutes. Sandbox use is free, and the first 500 live verifications every month are too.