Overview¶
Five concepts you should understand before writing any code.
Applicant¶
An applicant is the unit of compliance state — one record per end user. You
create applicants under your own externalUserId, so the same user always maps
to the same applicant in our system. An applicant is either an individual or
a company and carries:
- profile fields (name, DOB, address, …),
- the verification level they're being checked against,
- a verification status and a risk level (the result of checks),
- a list of attached documents,
- an audit trail.
Once created, the applicant is the thing you read, update, screen, and attach documents to. Webhooks reference it by
externalUserId.
Verification level¶
A verification level is a recipe for "what does it mean to be verified for this product." A level is a configured pipeline of steps:
- Identity document (passport / ID card / driver's license),
- Selfie / liveness check,
- Questionnaire (KYC / source-of-funds / risk profile questions),
- AML screening (sanctions / PEP / adverse media).
Levels are configured in the product portal, not at request time. Each level
has a short, stable name (KYC_01, KYB_STANDARD, …) — that name is the
wire identifier you use everywhere. Assign one to an applicant via
POST /v1/applicants/{externalUserId}/levels/{levelName}.
Verification session¶
A verification session is a single hosted attempt at completing whatever
the applicant's level requires. You create one with
POST /v1/applicants/{externalUserId}/verification-sessions and get back:
Redirect the user to url. They complete the steps in the hosted UI (camera,
form, questionnaire) and are redirected back to your site when done.
The token is an internal detail of the URL — your client never handles it.
Screening hit¶
A screening hit is a match returned by /v1/screening/* lookups. For each
candidate the response includes a confidence score, the source list, and any
PEP / sanctions / adverse-media flags. Use these for enhanced due diligence
or to enumerate beneficial owners of a corporate applicant.
Webhook event¶
A webhook event is a JSON payload we POST to your registered callback URL when something happens to an applicant — verification completed, status changed, screening hit added, etc. Every event is signed with HMAC so you can verify it came from us. See Webhook integration.