Skip to main content

​
Reference

reference is your own stable id for the client, 1 to 64 characters of A-Z a-z 0-9 _ . : -. With one, the call files a case where your staff look. Without one, nothing is stored on your workspace and no webhook is sent. Pick a reference that does not change and is not a personal value. A database id (client-0001, acct:8812) works. An email address does not (the @ is not allowed, and it would put personal data in your logs and in webhooks).

​
Case

A case is unique per workspace, environment and reference. The first call with a reference creates it. Later calls update it:
  • /extract adds a document, its read fields and its checks.
  • /verify and /assess file the verdict, and the assessment for /assess. Documents whose document_id you send back are linked to the case.
  • /eid files the eID request as pending, and a poll records the outcome.
A name sent in subject replaces the stored name. A call without a name keeps the stored one. If no subject is sent, the name is built from the read fields. A status that a person set in the console (approved, refused) is never changed by a new verdict.

​
Environment

environment is sandbox (default) or production. The same reference in the two environments is two cases. See Sandbox and production for what else the field changes.

​
Document and fields

A document is read into fields from a fixed vocabulary of keys (names, dates, address, bank details, entity numbers and more). Every value is a string. The reader omits what it cannot read. See Document types and fields.

​
Verdict and severity

Every check has a severity. critical blocks, warning flags for a person, info is for the record. passed is true when no critical check failed. See Verify a profile.

​
Policy

Every call runs under your workspace policy for the client kind (kyc or kyb) and the environment. A request switch can add checks, but cannot turn off one the policy locks. A refused switch is listed in policy.overrides_refused and is not an error. The policy decides thresholds (days), locks, required documents and the strictness of the risk bands. It is edited in Settings, KYC policy in the console.

​
Kinds of client

​
What the API does not do

  • It does not decide. It returns checks and a verdict. Your policy decides what to do.
  • It does not return a per-field confidence.
  • It has no bank connection endpoint and no 1000-point score. Those are console products.
  • It has no batch endpoint and no idempotency key.