Get started
Concepts
Organisations, apps, workflows, sessions, checks and decisions, and how they fit together.
Six objects make up everything in KYCVerify. Learn them once and the rest of the documentation reads quickly.
| Object | Id prefix | What it is |
|---|---|---|
| Organisation | org_ | Your company. Owns the team, the apps and the audit log. |
| App | app_ | An environment (sandbox or live) with its own API keys, workflows, webhook URL and secret, branding and retention period. Data never crosses apps. |
| Workflow | wf_ | The configuration a session runs: which steps, which thresholds, how to decide. Versioned; one is the app's default. |
| Session | ses_ | One verification of one person, with a hosted-flow link and a status. |
| Check | chk_ | One result inside a session: document, liveness, face_match, aadhaar, pan, aml, age, duplicate, email or ip. |
| Webhook delivery | whd_ | One event sent to your endpoint, with its attempts and responses. |
Ids are a prefix and 20 lower-case base32 characters: ten time-ordered, ten random. They sort by creation time.
Sessions and their status
not_started
in_progress
processing
approved
in_review
declined
not_started or in_progress past its expiry becomes expired; a link never used can end as abandoned.
A reviewer (console) or PATCH /v1/sessions/{id}/status moves in_review to approved or declined. Every transition sends a webhook.
A session is created not_started. Accepting consent moves it to in_progress. Submitting moves it to processing, where the background checks run, and the engine then decides.
Steps and background checks
The person completes steps in a fixed order: consent → email → document → aadhaar → pan → liveness → review (submit). Disabled steps are skipped. Each step produces a check immediately, so the flow can ask for a retake. At submit, four background checks run: face_match, aml, age and duplicate, plus ip, which records the client address and user agent.
Decisions
1. Any enabled check failed?
in_review when decision.auto_decline is false
declined
2. Any check review or error?
a person decides in the review queue
in_review
3. Otherwise
every check passed or was skipped
approved
The decision is the session's status, the decision_reason of the first deciding check (for example face_match_failed or aml_potential_match), the extracted identity, every check and, if a person decided, the review.
Identity
The identity is the best-known set of fields across all checks, with sources recording where each came from (mrz, ocr, aadhaar_qr, aadhaar_xml, …). Document numbers are stored masked; Aadhaar keeps only its last four digits. The keyed fingerprint used for duplicate detection stays internal and is not part of the identity.
Sandbox and live
A sandbox app issues kyc_test_ keys and a live app kyc_live_ keys. They run the same engine; the split keeps test traffic, workflows and webhooks apart from production data and lets you give each a different retention period.