Certula Verify

Certula Verify vs Certula Connect

These are two separate products with different credentials, different endpoints, and different use cases.

Verification Flow

API Key Setup

Contact the Certula team to provision API access for your application. You receive:

Quick Start

1 — Create a session (server-side)

// Node.js — POST to Certula to create a verification session
const res = await fetch(`${process.env.CERTULA_SERVER_URL}/api/v1/sessions/`, {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.CERTULA_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    applicant_id:            user.certula_id,       // "sub" from OAuth userinfo
    user_email:              user.email,
    user_name:               user.name,
    workflow_id:             'identity_verification', // must be this exact value
    redirect_url:            `https://yourapp.com/verification/complete`,
    language:                'en',
    country:                 'MY',
    send_email_notification: false,
    metadata:                { user_id: user.id, source: 'your-app' },
  }),
})
const { session_token, expires_at } = await res.json()
const verificationUrl = `${process.env.CERTULA_FRONTEND_URL}/ekyc?session=${session_token}`

2 — Redirect the user

res.redirect(verificationUrl)   // or: return NextResponse.redirect(verificationUrl)

3 — Check status after redirect

// GET /verification/complete — user landed back after eKYC
const profile = await fetch(
  `${process.env.CERTULA_SERVER_URL}/api/v1/users/${user.certula_id}/profile`,
  { headers: { 'X-API-Key': process.env.CERTULA_API_KEY } }
).then(r => r.json())

const verified = profile.kyc_verified ?? profile.ekyc_verified ?? false
// Update your DB, notify the user

Create Session Endpoint

Request Headers

Request Body

Response

{
  "session_token": "eyJhbGciOiJIUzI1NiJ9...",
  "expires_at":     "2026-06-30T14:30:00Z"
}

Construct the redirect URL: {CERTULA_FRONTEND_URL}/ekyc?session={session_token}

Status Check Endpoint

Request headers: X-API-Key: YOUR_API_KEY

Response

{
  "kyc_verified":   true,
  "ekyc_verified":  true,
  "kyc_status":    "verified",
  "full_name":     "Ahmad bin Razif",
  "phone_number":  "+60123456789"
}

Detailed Identity Data

{
  "user_id":       "22f35f9a-d82f-4f81-afec-e8a9864621c9",
  "email":         "user@example.com",
  "kyc_verified":  true,
  "kyc_level":     "basic",
  "verified_at":   "2026-06-30T10:00:00Z",
  "kyc_details": {
    "status":                "verified",
    "overall_confidence":    0.92,
    "face_match_confidence": 0.95,
    "document_type":        "national_id",
    "document_country":     "MY",
    "extracted_data": {
      "full_name":    "AHMAD BIN RAZIF",
      "id_number":   "900512-10-1234",
      "date_of_birth":"1990-05-12",
      "gender":      "M",
      "address_line_1":"123 Jalan Ampang",
      "city":        "Kuala Lumpur",
      "postal_code": "50450"
    }
  }
}

Node.js (Express) — Complete Backend

// routes/verification.js
const express = require('express')
const router  = express.Router()
const { CERTULA_SERVER_URL, CERTULA_API_KEY, CERTULA_FRONTEND_URL } = process.env

// Normalize the status across different field/value variants
function resolveKycStatus(profile) {
  for (const k of ['kyc_verified', 'ekyc_verified', 'kyc_status', 'ekyc_status']) {
    if (profile[k] != null) {
      const v = profile[k]
      if (typeof v === 'boolean') return v
      return ['verified', 'approved', 'passed', 'complete'].includes(String(v).toLowerCase())
    }
  }
  return false
}

// Step 1: User requests eKYC — create a session and redirect
router.post('/verification/start', requireAuth, async (req, res) => {
  const { user } = req
  if (user.kyc_verified) return res.json({ already_verified: true })

  const apiRes = await fetch(`${CERTULA_SERVER_URL}/api/v1/sessions/`, {
    method: 'POST',
    headers: { 'X-API-Key': CERTULA_API_KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      applicant_id:            user.certula_id || user.id,
      user_email:              user.email,
      user_name:               user.name,
      workflow_id:             'identity_verification',
      redirect_url:            `${process.env.APP_URL}/verification/complete`,
      language:                'en',
      country:                 'MY',
      send_email_notification: false,
      metadata:                { user_id: user.id, source: 'my-app' },
    })
  })
  if (!apiRes.ok) return res.status(503).json({ error: 'Verification service unavailable' })
  const { session_token, expires_at } = await apiRes.json()
  const verificationUrl = `${CERTULA_FRONTEND_URL}/ekyc?session=${session_token}`
  res.json({ verification_url: verificationUrl, expires_at })
})

// Step 2: User returns after eKYC — check status
router.get('/verification/complete', requireAuth, async (req, res) => {
  const { user } = req
  if (!user.certula_id) return res.redirect('/dashboard?kyc=unknown')

  const statusRes = await fetch(
    `${CERTULA_SERVER_URL}/api/v1/users/${user.certula_id}/profile`,
    { headers: { 'X-API-Key': CERTULA_API_KEY } }
  )

  if (!statusRes.ok) return res.redirect('/dashboard?kyc=error')
  const profile = await statusRes.json()
  const verified = resolveKycStatus(profile)

  // Update your database
  await db.users.update({ id: user.id }, { kyc_verified: verified })
  res.redirect(verified ? '/dashboard?kyc=success' : '/dashboard?kyc=pending')
})

// Get detailed identity data (requires kyc.details scope)
router.get('/verification/details', requireAuth, async (req, res) => {
  const { user } = req
  const detailRes = await fetch(
    `${CERTULA_SERVER_URL}/api/v1/apps/me/user/${user.certula_id}?include_details=true`,
    { headers: { 'X-API-Key': CERTULA_API_KEY } }
  )
  if (!detailRes.ok) return res.status(503).json({ error: 'Failed to load identity data' })
  // ⚠ Don't log the full response body — it contains PII
  const data = await detailRes.json()
  res.json({ kyc_verified: data.kyc_verified, kyc_level: data.kyc_level })  // return minimal
})

module.exports = router

Python (FastAPI) — Complete Backend

# routers/verification.py
import httpx, logging
from fastapi import APIRouter, Depends, HTTPException
from fastapi.responses import RedirectResponse

router = APIRouter(prefix="/verification")
logger = logging.getLogger(__name__)

def resolve_kyc_status(payload: dict) -> bool:
    """Normalize kyc status across field/value variants."""
    for key in ("kyc_verified", "ekyc_verified", "kyc_status", "ekyc_status"):
        if key in payload:
            val = payload[key]
            if isinstance(val, bool): return val
            return str(val).lower() in {"verified", "approved", "passed", "complete"}
    return False


@router.post("/start")
async def start_verification(session: dict = Depends(get_current_session),
                             db: Session = Depends(get_db)):
    user = get_user(db, session["sub"])
    if user.profile.ekyc_verified:
        raise HTTPException(400, "eKYC already verified")

    session_data = {
        "applicant_id":            user.certula_id or str(user.id),
        "user_email":              user.email,
        "user_name":               user.display_name or user.full_name,
        "workflow_id":             "identity_verification",
        "redirect_url":            f"{settings.app_url}/verification/complete",
        "language":                "en",
        "country":                 "MY",
        "send_email_notification": False,
        "metadata":                {"user_id": str(user.id), "source": "my-app"},
    }
    headers = {"X-API-Key": settings.certula_api_key, "Content-Type": "application/json"}

    async with httpx.AsyncClient(timeout=10) as client:
        resp = await client.post(
            f"{settings.certula_server_url}/api/v1/sessions/",
            json=session_data, headers=headers
        )
    resp.raise_for_status()
    payload = resp.json()
    session_token = payload["session_token"]
    verification_url = f"{settings.certula_frontend_url}/ekyc?session={session_token}"
    return {"verification_url": verification_url, "expires_at": payload.get("expires_at")}


@router.get("/complete")
async def verification_complete(session: dict = Depends(get_current_session),
                               db: Session = Depends(get_db)):
    user = get_user(db, session["sub"])
    if not user.certula_id:
        return RedirectResponse("/dashboard?kyc=unknown")

    async with httpx.AsyncClient(timeout=10) as client:
        resp = await client.get(
            f"{settings.certula_server_url}/api/v1/users/{user.certula_id}/profile",
            headers={"X-API-Key": settings.certula_api_key},
        )

    if resp.status_code >= 400:
        logger.warning("eKYC status check failed: %s", resp.text)
        return RedirectResponse("/dashboard?kyc=error")

    verified = resolve_kyc_status(resp.json())
    user.profile.ekyc_verified = verified
    db.commit()
    return RedirectResponse("/dashboard?kyc=success" if verified else "/dashboard?kyc=pending")

All Endpoints

All requests require X-API-Key: YOUR_API_KEY header.

Status Values

The response field name may vary — always check all four: kyc_verified, ekyc_verified, kyc_status, ekyc_status.

Webhooks

Certula can push a webhook notification when a user's verification status changes, so you don't need to poll. Contact the Certula team to configure a webhook endpoint for your connected app.

Payload

{
  "event":        "kyc.completed",
  "applicant_id": "certula-user-uuid",
  "status":       "verified",
  "verified_at":  "2026-06-30T10:00:00Z",
  "metadata": {
    "user_id": "your-internal-uuid",
    "source":  "my-app"
  }
}

Error Reference

Compliance & Data Handling

Mandatory Data-Handling Requirements