Build with Bangladesh's identity infrastructure

Authorization: Bearer kyc_test_xxxxxxxxxxxxxxxx

HTTP/1.1 409 Conflict
x-request-id: req_3f9c1a7e2b8d4c6f0a1e5b7d

{
  "error": {
    "code": "invalid_state",
    "message": "Cannot move verification from verified to cancelled.",
    "request_id": "req_3f9c1a7e2b8d4c6f0a1e5b7d"
  }
}

curl -X POST https://kyc.bd/api/public/v1/verifications \
  -H "Authorization: Bearer $KYC_API_KEY" \
  -H "Idempotency-Key: onboarding-USER-1001-attempt-1" \
  -H "Content-Type: application/json" \
  -d '{"applicant_id":"5b0c…","template":{"documents":["nid"],"require_selfie":true}}'

created ──► started ──► documents_submitted ──► processing ──┬─► verified
   │           │                 ▲                          ├─► failed
   │           │                 │                          ├─► requires_review ──► verified | failed | requires_retry
   │           │                 └──── requires_retry ◄─────┘
   └───────────┴──► cancelled | expired (7 days by default)

{
  "external_id": "USER-1001",
  "type": "individual",
  "consent": { "purpose": "identity_verification", "version": "2026-10" },
  "pii": { "full_name": "Applicant Name", "date_of_birth": "1990-01-01", "national_id": "1234567890" }
}

{ "object": "applicant", "id": "5b0c2f1e-…", "external_id": "USER-1001", "type": "individual", "status": "active", "created_at": "2026-10-07T20:00:00Z" }

{
  "applicant_id": "5b0c2f1e-…",
  "type": "individual_kyc",
  "country": "BD",
  "template": { "documents": ["nid"], "require_selfie": true, "mock_outcome": "pass" }
}

{
  "id": "a581d10c-…", "object": "verification", "applicant_id": "5b0c2f1e-…",
  "status": "created", "decision": null, "risk_score": null, "risk_level": null,
  "expires_at": "2026-10-14T20:00:00Z", "created_at": "2026-10-07T20:00:00Z"
}

POST /verifications/a581d10c-…/documents
{ "document_type": "nid", "side": "front", "mime_type": "image/jpeg", "file_size": 284113 }

201 Created
{ "object": "document_upload", "document_id": "9e1d…", "upload_url": "https://…signed…",
  "method": "PUT", "headers": { "content-type": "image/jpeg" }, "expires_in": 7200 }

curl -X PUT "$UPLOAD_URL" -H "Content-Type: image/jpeg" --data-binary @nid-front.jpg

{ "id": "a581d10c-…", "status": "verified", "decision": "approve", "risk_score": 0, "risk_level": "low", "documents_received": 2 }

{
  "object": "decision", "verification_id": "a581d10c-…", "status": "requires_review", "decision": "review",
  "risk": { "risk_score": 40, "risk_level": "medium", "decision": "review",
            "risk_signals": [{ "code": "face_match_inconclusive", "weight": 40, "detail": "score 0.72 < 0.8" }] },
  "review": { "id": "…", "status": "open", "resolved_at": null }
}

{
  "full_name": "John Doe",
  "date_of_birth": "1998-05-15",
  "national_id": "1234567890",
  "mobile": "+8801XXXXXXXXX",
  "consent": true,
  "reference_id": "USER-1001"
}

{
  "status": "verified",
  "verification_id": "KYC-8472931",
  "match_score": 98.7,
  "risk_level": "low",
  "timestamp": "2026-05-07T12:00:00Z"
}

curl -X POST https://api.kyc.bd/v1/identity/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "full_name":"John Doe",
    "date_of_birth":"1998-05-15",
    "national_id":"1234567890",
    "mobile":"+8801XXXXXXXXX",
    "consent":true
  }'

{
  "document_image": "base64_encoded_image",
  "selfie_image": "base64_encoded_image",
  "reference_id": "USER-1001"
}

{
  "status": "matched",
  "confidence_score": 96.4,
  "liveness": true,
  "fraud_risk": "low"
}

{
  "company_name": "Example Technologies Ltd",
  "registration_number": "C-123456",
  "tin": "987654321",
  "contact_email": "admin@example.com"
}

{
  "status": "verified",
  "company_status": "active",
  "risk_level": "medium",
  "verification_id": "BIZ-82711"
}

{
  "mobile_verified": true,
  "operator": "Detected Operator",
  "sim_status": "active",
  "risk_score": 12
}

POST https://your-app.example/webhooks/kyc
content-type: application/json
kyc-signature: t=1791403200,v1=5d41402abc4b2a76b9719d911017c592…
kyc-event-id: 7c9e6679-7425-40de-944b-e07fc1f90ae7
idempotency-key: 7c9e6679-7425-40de-944b-e07fc1f90ae7

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "type": "verification.completed",
  "created_at": "2026-10-07T20:00:05Z",
  "data": { "id": "a581d10c-…", "object": "verification", "status": "verified", "decision": "approve", "risk_score": 0 }
}

import crypto from "node:crypto";

export function verifyKycSignature(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 ?? ""));
}

import hmac, hashlib, time

def verify_kyc_signature(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    if abs(time.time() - int(parts["t"])) > 300:
        return False
    expected = hmac.new(secret.encode(), f"{parts['t']}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))