Quickstart

5-minute integration · sandbox · first PAN verify.

1 · Get your sandbox key

2 · Make first call

curl -X POST https://api.kyc.zyroai.com/v1/identity/pan/verify \
  -H "Authorization: Bearer kos_sandbox_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"pan":"ABCDE1234F","name":"John Doe","customerId":"cust-001"}'

3 · Inspect response

{
  "verificationId": "a1b2...",
  "outcome": "Verified",
  "panMasked": "XXXXX0000X",
  "name": "John Doe",
  "category": "Individual",
  "kycCompliant": true,
  "latencyMs": 312,
  "provider": "nsdl-stub"
}

Auth · API keys

Bearer token. Sandbox keys start kos_sandbox_ · production kos_live_. Rotate via dashboard or DELETE /v1/keys/{id}.

Scopes per key (least privilege): identity:write · face:write · billing:read · etc. See full scope matrix in dashboard.

Block reference

16 single-block + N tenant-custom journeys. Each call meter-debited from wallet.

POST /v1/identity/pan/verify · NSDL · ₹1.50
POST /v1/identity/aadhaar/otp/{start,confirm} · UIDAI sub-AUA · ₹3.00
POST /v1/identity/digilocker/session · ₹6.00
POST /v1/ocr/id-card · PaddleOCR · ₹2.00
POST /v1/face/match · InsightFace · ₹2.00
POST /v1/liveness/check · Silent-Face · ₹1.50
POST /v1/vcip · ₹35.00 (full session)
POST /v1/ckyc/{search,download} · Cersai · ₹35.00 gov passthrough
POST /v1/bureau/pull · CIBIL/Experian · ₹15.00
POST /v1/bank/verify · penny-drop · ₹1.00
POST /v1/address/verify · India Post · ₹1.00
POST /v1/selfie/score · ₹0.50
POST /v1/screen · watchlist · ₹2.00
POST /v1/esign/{initiate,complete} · NSDL eSign · ₹25.00

SDKs

Three first-party SDKs. All open source · Apache-2.0.

Web · npm i @kycos/web-sdk · 5 KB gzip · React/Vue/Vanilla
Android · Maven · in.kycos:android-sdk:0.1.0 · Kotlin · MinSdk 26
iOS · SPM · github.com/kycos/ios-sdk · Swift · iOS 15+

Web · 3-line hosted flow

import { KycOs } from "@kycos/web-sdk";
const sdk = new KycOs({ tenantSlug: "acme", env: "sandbox" });
sdk.startHostedJourney({
  templateCode: "t-individual-basic",
  customerId: "user-12345",
  mount: "#kyc-container",
  onComplete: (r) => console.log("done", r),
});

Flow templates

20 pre-built · combine any blocks. SaaS-admin owns global · tenant owns custom.

16 single-block · t-pan-only · t-aadhaar-otp-only · t-face-only · etc
4 multi-block · t-individual-basic · t-individual-full · t-vcip-flow · t-corporate
Custom · POST /v1/templates with kebab-code + block array

Webhooks

HMAC-SHA256 signed · exponential retry · dead-letter · replay UI.

// header
X-KycOs-Signature: t=1715000000,v1=abcdef...
X-KycOs-Event-Type: kyc.identity.pan-verified
X-KycOs-Delivery: d8a3f...
X-KycOs-Source-Event: 7b2c1...

Verify:

const sig = req.headers['x-kycos-signature'];
const [t, v1] = sig.split(',');
const expected = hmacSha256(secret, `${t.slice(2)}.${rawBody}`);
if (v1.slice(3) !== expected) throw new Error('bad signature');

Billing · Wallet

Pre-funded · per-verify debit · low-balance webhook · auto-recharge via Razorpay (production).

GET /v1/wallet · current balance · currency · lifetime credit/debit
POST /v1/wallet/topup · add funds · returns ledger entry
GET /v1/wallet/ledger · paginated history

DPDP · consent · DPO

Compliance built-in. No bolt-ons.

Consent · purpose-limited · revocable · receipt PDF · hash-stable audit
Erasure · 30-day SLA · auto-cascade across svcs
Grievance officer · public form · 3-day ack · 30-day resolve
Breach notification · CERT-In 6 hr · DPDP Board 72 hr · data-principal notification
Audit trail · hash-chained · WORM S3 · 7-year retention

Errors · rate limits

Standard HTTP. Custom X-RateLimit-* headers. 429 with Retry-After.

400 validation failed · response body has field errors
401 bad/expired API key
402 insufficient wallet balance · auto-topup or block
403 scope missing
423 block not live in your country (catalog gate)
429 rate limit · default 50 RPS per tenant

Compliance certs

RBI Regulatory Sandbox · in flight
DPDP 2023 · DPO registered · grievance officer · erasure API
iBeta L1 · Q4 2026 target
NIST FRVT · Q4 2026 target
SOC 2 Type 1 · M9 target
SOC 2 Type 2 · M24 target
ISO 27001 · M15 target
CERT-In annual VAPT · M3+