Verify identities with one API call.

Base URL https://api.yourdomain.com · All requests and responses are JSON · TLS required in production.

Getting started

What you need

KYC Orchestrator is a hosted service — there is nothing to install and no SDK to ship. Everything below can be set up in a few minutes from the dashboard.

Integration checklist

Overview

How it works

Three moving parts: your server, your user, and the Orchestrator. You never touch raw documents — they go straight to a hosted, isolated upload page.

Reference

Authentication

All authenticated endpoints accept one of two credentials. Pick whichever fits your integration — they are interchangeable on every protected route.

Method A — Bearer token

Exchange your account email + password at POST /api/auth/login for a token, then send it on every request. Best for interactive / dashboard-style integrations.

# 1. Get a token
curl -X POST https://api.yourdomain.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"dev@yourapp.com","password":"secret123"}'

# 2. Use it
curl https://api.yourdomain.com/api/verifications \
  -H "Authorization: Bearer 14|aBcD3f...your-token"

Method B — API key

Generate a key in the dashboard under API Keys and send it in the X-API-Key header. Best for server-to-server / machine integrations — no expiry handling needed.

curl https://api.yourdomain.com/api/verifications \
  -H "X-API-Key: kyc_live_8f3a91c2e7b04d56a1f0..."

Getting started

Quick start

Five steps from zero to a verified identity. The only requests your server makes are 1, 2 and (optionally) 5.

1 · Register an account

POST /api/auth/register

{
  "name": "Acme Integrations",
  "email": "dev@yourapp.com",
  "password": "secret123",
  "password_confirmation": "secret123"
}

{
  "user": {
    "id": "usr_9fK2...",
    "name": "Acme Integrations",
    "email": "dev@yourapp.com"
  },
  "token": "14|aBcD3f...your-token"
}

2 · Create a verification

POST /api/verifications · requires auth

{
  "reference": "order_10482",
  "callback_url": "https://yourapp.com/webhooks/kyc",
  "redirect_url": "https://yourapp.com/kyc/done"
}

{
  "id": "ver_7Ax91Qm2",
  "reference": "order_10482",
  "status": "created",
  "verification_url": "https://api.yourdomain.com/verify/tok_5Bn3...e9",
  "expires_at": "2026-06-25T12:00:00Z",
  "created_at": "2026-06-24T12:00:00Z"
}

3 · Send the URL to your user

No API call. Just embed verification_url in your flow — redirect to it, render it in an iframe, or email/SMS it. The user uploads their selfie and ID front on the hosted page. The page handles capture, validation and submission for you.

4 · Listen for the webhook

Once processing finishes, the Orchestrator POSTs a signed payload to your callback_url.

{
  "event": "verification.completed",
  "id": "ver_7Ax91Qm2",
  "reference": "order_10482",
  "status": "approved",
  "result": {
    "face_match": true,
    "face_match_score": 0.971,
    "document_valid": true,
    "identity": {
      "full_name": "JANE A. DOE",
      "document_number": "X1234567",
      "date_of_birth": "1994-03-11",
      "expiry_date": "2030-03-10",
      "nationality": "USA"
    }
  },
  "completed_at": "2026-06-24T12:04:18Z"
}

5 · Or poll for the result

GET /api/verifications/{id} · requires auth

{
  "id": "ver_7Ax91Qm2",
  "reference": "order_10482",
  "status": "approved",
  "result": {
    "face_match": true,
    "document_valid": true,
    "identity": {
      "full_name": "JANE A. DOE",
      "document_number": "X1234567",
      "date_of_birth": "1994-03-11"
    }
  },
  "completed_at": "2026-06-24T12:04:18Z"
}

Reference

API reference

All endpoints are prefixed with the base URL http://kyc_orch.souryasocial.shop. Rate limits are per credential (token or API key); public routes are per IP.

Authentication

Verifications

Public (hosted page)

System

Reference

Errors & status codes

The API uses conventional HTTP status codes and always returns a JSON body with a message (and, for validation, an errors map).

Link lifetime & one-time use

72 hours: each verification_url is backed by a single-use session valid for that long. After a successful upload the link is consumed and can't be reused. An expired link returns 410; an already-used link returns 409. If either happens, create a fresh verification and send the new URL.

Reference

Webhooks

When a verification reaches a terminal state, the Orchestrator sends a POST to the callback_url you supplied at creation time. Every webhook is signed so you can prove it came from us and wasn't tampered with.

Signature

Each request carries an X-KYC-Signature header. It is the lowercase hex HMAC-SHA256 of the raw request body, keyed with your webhook signing secret (dashboard → API Keys → Webhook secret), prefixed with sha256=.

X-KYC-Signature: sha256=3f8a1c...e90b
X-KYC-Event: verification.completed
Content-Type: application/json

Example payload

{
  "event": "verification.completed",
  "id": "ver_7Ax91Qm2",
  "reference": "order_10482",
  "status": "approved",
  "result": {
    "face_match": true,
    "face_match_score": 0.971,
    "document_valid": true,
    "identity": {
      "full_name": "JANE A. DOE",
      "document_number": "X1234567",
      "date_of_birth": "1994-03-11",
      "expiry_date": "2030-03-10",
      "nationality": "USA"
    }
  },
  "completed_at": "2026-06-24T12:04:18Z"
}

Verify the signature

<?php
$secret = getenv('KYC_WEBHOOK_SECRET');
$payload = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_KYC_SIGNATURE'] ?? '';

$expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);

// constant-time comparison
if (! hash_equals($expected, $header)) {
    http_response_code(401);
    exit('invalid signature');
}

$event = json_decode($payload, true);
// ... handle $event['status'] ...
http_response_code(200);

const crypto = require('crypto');

// mount with express.raw() so body is the exact bytes
app.post('/webhooks/kyc',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const secret = process.env.KYC_WEBHOOK_SECRET;
    const header = req.get('X-KYC-Signature') || '';
    const expected = 'sha256=' +
      crypto.createHmac('sha256', secret)
            .update(req.body)
            .digest('hex');

    const ok = header.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
    if (!ok) return res.status(401).send('invalid signature');

    const event = JSON.parse(req.body.toString());
    // ... handle event.status ...
    res.sendStatus(200);
  });

Reference

Verification statuses

A verification moves through a small, predictable lifecycle. approved, rejected and expired are terminal — no further changes occur.

Integrate

Code examples

Full server-side flow in three languages: register (once), create a verification, then verify the inbound webhook. Send your user the verification_url in between.

<?php
$base = 'https://api.yourdomain.com';

// --- 1. Register once, store the token ---
$ch = curl_init("$base/api/auth/register");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Acme Integrations',
    'email' => 'dev@yourapp.com',
    'password' => 'secret123',
    'password_confirmation' => 'secret123',
  ]),
]);
$token = json_decode(curl_exec($ch), true)['token'];

// --- 2. Create a verification ---
$ch = curl_init("$base/api/verifications");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Content-Type: application/json',
    "Authorization: Bearer $token",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'reference' => 'order_10482',
    'callback_url' => 'https://yourapp.com/webhooks/kyc',
  ]),
]);
$verification = json_decode(curl_exec($ch), true);

// 3. Send $verification['verification_url'] to your user.
echo $verification['verification_url'];

// --- 4. Webhook handler (separate endpoint) ---
$secret = getenv('KYC_WEBHOOK_SECRET');
$body = file_get_contents('php://input');
$sig = $_SERVER['HTTP_X_KYC_SIGNATURE'] ?? '';
if (hash_equals('sha256=' . hash_hmac('sha256', $body, $secret), $sig)) {
    $event = json_decode($body, true);
    // $event['status'] === 'approved' | 'rejected'
}

const crypto = require('crypto');
const BASE = 'https://api.yourdomain.com';

// --- 1. Register once, store the token ---
async function register() {
  const r = await fetch(`${BASE}/api/auth/register`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Acme Integrations',
      email: 'dev@yourapp.com',
      password: 'secret123',
      password_confirmation: 'secret123',
    }),
  });
  return (await r.json()).token;
}

// --- 2. Create a verification ---
async function createVerification(token) {
  const r = await fetch(`${BASE}/api/verifications`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`,
    },
    body: JSON.stringify({
      reference: 'order_10482',
      callback_url: 'https://yourapp.com/webhooks/kyc',
    }),
  });
  const v = await r.json();
  // 3. Send v.verification_url to your user.
  return v.verification_url;
}

// --- 4. Verify the webhook ---
function verifyWebhook(rawBody, header, secret) {
  const expected = 'sha256=' +
    crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return header.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

import hmac, hashlib, requests

BASE = "https://api.yourdomain.com"

# --- 1. Register once, store the token ---
def register():
    r = requests.post(f"{BASE}/api/auth/register", json={
        "name": "Acme Integrations",
        "email": "dev@yourapp.com",
        "password": "secret123",
        "password_confirmation": "secret123",
    })
    return r.json()["token"]

# --- 2. Create a verification ---
def create_verification(token):
    r = requests.post(f"{BASE}/api/verifications",
        headers={"Authorization": f"Bearer {token}"},
        json={
            "reference": "order_10482",
            "callback_url": "https://yourapp.com/webhooks/kyc",
        })
    v = r.json()
    # 3. Send v["verification_url"] to your user.
    return v["verification_url"]

# --- 4. Verify the webhook (Flask example) ---
def verify_webhook(raw_body: bytes, header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, header)

Integrate

Going-live checklist

Before you put real users through the flow, confirm each of these.