Applicants
An applicant is the person you verify. Create one per user with POST /applicants and keep its id next to your user.
| Field | Notes |
|---|---|
external_id |
Required. Your user ID: up to 100 printable ASCII characters, unique per environment (a repeat returns 409 conflict) |
flow |
Flow key, default basic-kyc. An unknown key returns 422 unprocessable |
locale |
uz, ru or en (default uz). The language of the hosted flow |
purpose |
Optional, up to 200 characters. Default purpose of the check for this applicant's sessions; it appears in the certificate |
metadata |
Optional. Up to 20 string keys with string values (200 characters each). No personal data |
email and phone are not accepted yet: a non-empty value returns 400 validation_failed.
An applicant's status is one of:
status |
Meaning |
|---|---|
init |
New, after a reset, or after a RED with decision_type: retry. A session can be created |
on_hold |
The latest verification is waiting for manual review |
completed |
Has a final decision (GREEN, or RED with final) |
The applicant also carries the latest decision, risk_score, last_verification_id and valid_until. Find applicants with GET /applicants (filters: external_id, status, decision, flow, created_from, created_to; cursor pagination). The history of attempts is at GET /applicants/{id}/verifications.
Sessions
A session is one attempt. Create it with POST /applicants/{id}/sessions:
{
"redirect_url": "https://shop.example/kyc/done",
"expires_in": 1800,
"locale": "en",
"purpose": "Account opening"
}
| Field | Notes |
|---|---|
redirect_url |
Optional, https:// only. After the result the hosted page shows a "Back to service" button to this URL (not shown in the web embed) |
expires_in |
60–1800 seconds, default 1800 |
locale |
Defaults to the applicant's locale |
purpose |
Optional. Defaults to the applicant's purpose, then to the default purpose in your business profile |
contract |
Optional. { "sha256": "<64 hex>", "reference": "DOG-2026/17" } links the check to your contract with the customer. Only the hash is sent and stored; it appears in the certificate |
The response has url (hosted flow, a short link like https://kyc.goxost.net/v/Xk7mQ2pL9aR4wTb8) and token (for kyc.js and the Flutter SDK), plus expires_at.
Rules:
- A session can be created only when the applicant is in
init; otherwise409 conflict— reset the applicant first. - An applicant has one active session. Creating a new one expires the previous one.
- A session is single-use. Once it is submitted, expired or abandoned, its link returns
410and the SDKs show an error; create a new session for a new attempt. - The hosted page's language is taken from
?lang=in the URL, then the sessionlocale, then the browser language. - In live, creating a session reserves one unit of your monthly limit (
429 plan_limit_reachedwhen it is used up). An unused reservation is returned if the session expires before submission or is replaced.
Track a session with GET /sessions/{id}: status is created, started, submitted, processed, expired or abandoned, and steps_done lists completed steps.
What the user sees
- Handoff (desktop only). On a computer without a touch screen the flow first offers a QR code to continue on a phone. The desktop window follows the phone and shows the result too.
- Consent. The user agrees to the processing of their data, including biometric data for the selfie. The consent time is recorded in the certificate.
- Document. The user photographs the document — the passport photo page, or the front and back of an ID card. Photos that cannot be used are rejected on the spot with a hint, so the user can retake them.
- Selfie. The user takes a short selfie by following the on-screen instructions. This step also confirms that a real person is taking part.
- Processing and result. The checks run and the user sees the outcome. A late result is shown as "under review".
The hosted page, the web embed and the Flutter SDK all show the same steps, with a "Powered by" badge at the bottom. When the flow has the electronic document check enabled, the Flutter SDK also runs it after the photos.
You get the session.started webhook when the user gives consent and verification.submitted when all steps are done.
Decisions
When the checks finish, a verification (ver_…) is created and you receive verification.completed (GREEN or RED) or verification.on_hold. Read the full result with GET /verifications/{id}.
decision |
decision_type |
Applicant status after |
What to do |
|---|---|---|---|
GREEN |
null |
completed |
Mark the user as verified |
RED |
retry |
init |
Tell the user what went wrong and create a new session |
RED |
final |
completed |
Do not verify; a new attempt needs a reset |
ON_HOLD |
null |
on_hold |
Wait for verification.reviewed |
The result also includes:
reject_labels— why it isREDorON_HOLD(table below);checks— one entry per check (document,face_match,liveness, and when enabledaml,duplicate,age, plusdoc_fraudandchip), each withstatus(pass,warn,failorerror),scoreandlabels;document— type, country and the document data (document.data);risk_scorefrom0to1;valid_until— aGREENresult is valid for 2 years. You getapplicant.reverification_due30 days before and when it ends.
Decide on your backend only. The result in kyc.js callbacks or in the Flutter SDK is for the user experience — read the decision from the webhook or GET /verifications/{id}.
stale: true marks a result that arrived after the applicant was reset or deleted, or a newer session was opened. It stays in the history but does not change the applicant and sends no webhook.
Reject labels
| Label | Type | Meaning |
|---|---|---|
BAD_QUALITY |
retry | The photo quality is not good enough — retake it |
DOC_NOT_SUPPORTED |
retry | Document type or country is not allowed in the flow |
MRZ_NOT_READABLE |
retry | The document data could not be read from the photo — retake it |
MRZ_INVALID |
final | The document data is not valid |
MRZ_LOW_CONFIDENCE |
review | The document data was read, but not with enough certainty |
DOC_DATA_MISMATCH |
final | The data on the document is inconsistent, or the uploaded sides belong to different documents |
DOC_EXPIRED |
retry | The document has expired |
DOC_RECAPTURE |
retry | The document image did not pass the authenticity check — retake it with the original document. Off by default |
DOC_SCREEN_RECAPTURE |
review | The document image did not pass the authenticity check |
DOC_PRINTED_COPY |
review | The document may not be the original |
DOC_PHOTO_TAMPERED |
review | The document photo did not pass the authenticity check |
DOC_TEMPLATE_MISMATCH |
review | The document may have been altered |
DOC_FORGED |
final | Signs of forgery |
DOC_REVIEW_REQUIRED |
review | A document type that is always reviewed by a person |
DOC_FACE_UNBOUND |
review | The document sides could not be confirmed as one document |
PERSONAL_NUMBER_INVALID |
review | The national personal number is not valid or does not match the other document data |
UNDERAGE |
final | Younger than the flow's minimum age |
AGE_UNKNOWN |
review | Age-only flow: the birth date could not be read |
FACE_NOT_FOUND |
retry | No face found in the selfie or on the document |
FACE_MISMATCH |
final | The selfie and the document photo are different people |
FACE_MATCH_UNCERTAIN |
review | The selfie-to-document match did not give a clear result |
LIVENESS_FAILED |
retry | The selfie step was not completed, or time ran out |
LIVENESS_UNCERTAIN |
review | The presence check did not give a clear result |
LIVENESS_SPOOF |
final | The presence check failed: a real person did not take part |
SANCTIONS_MATCH |
final | Found on a sanctions list: a very close name and the exact birth date |
SANCTIONS_POSSIBLE |
review | Possible sanctions match (close name, birth date in range or unknown) |
PEP_MATCH |
review | Politically exposed person |
AML_NO_NAME |
review | AML is enabled but no name could be read from the document |
DUPLICATE |
final | This document number is already used by another applicant in your account |
CHIP_HASH_MISMATCH |
final | The electronic document check failed |
CHIP_SIGNATURE_INVALID |
final | The electronic document check failed |
CHIP_MRZ_MISMATCH |
final | The electronic data does not match the photographed document |
CHIP_CHAIN_UNVERIFIED |
review | The electronic document check could not be completed for this issuing country |
CHIP_CLONE_SUSPECTED |
review | The electronic document check did not give a clear result |
CHIP_NOT_READ |
review | The flow requires the electronic document check, but it was not done |
CHECK_UNAVAILABLE |
review | A check could not run (a service was unavailable) |
REVIEW_EXPIRED |
retry | An ON_HOLD result was not reviewed in time and was cancelled by the system |
MAX_ATTEMPTS |
final | Attempts exhausted |
Labels of type retry come with RED + retry, final with RED + final, and review lead to ON_HOLD. New labels may be added: treat an unknown label like ON_HOLD and show a generic message.
Manual review
ON_HOLD means a person must decide. You can review:
- in the panel — open the review queue, look at the document and face images and decide; or
- through the API —
POST /verifications/{id}/review:
{ "decision": "GREEN", "comment": "manual check ok" }
{ "decision": "RED", "decision_type": "final", "reject_labels": ["DOC_FORGED"] }
- Only the applicant's latest
ON_HOLDverification can be reviewed. An already decided, outdated or stale one returns409 conflict; so does a verification another reviewer has open in the panel. REDneedsdecision_typeand at least one label.REVIEW_EXPIREDcannot be chosen.- The
commentis not stored. - After the review you get
verification.reviewedwith the new decision. - If your account has the four-eyes rule on (panel → Settings → Review), a
REDfrom the API returns202 Acceptedand staysON_HOLDuntil a different person confirms it in the panel.GREENis not affected.
Each ON_HOLD result has review_deadline_at — 7 days after the decision. You get verification.review_reminder right away, then 2 days and 24 hours before the deadline. If nobody decides in time, the verification becomes RED + retry with REVIEW_EXPIRED, and you receive verification.reviewed.
Reset and retry
- After
RED+retrythe applicant goes back toinitautomatically. Create a new session and send the user through the flow again. - To verify again after
GREEN,RED+finalor a stuck attempt, callPOST /applicants/{id}/reset. Status becomesinit,decision,risk_scoreandlast_verification_idare cleared, and open sessions becomeabandoned. History stays inGET /applicants/{id}/verifications. You getapplicant.reset. - Inside one session the number of tries is limited (20 document uploads, 10 selfie attempts, 5 selfie uploads). When they run out, create a new session.
- To erase an applicant and their data, call
DELETE /applicants/{id}. It returns202withdeletion_scheduled, sendsapplicant.deleted, and afterwards the applicant returns404.
Flows
A flow is the configuration of a verification: which steps and checks run and which documents are accepted. Every account has the basic-kyc flow; pass another flow key in flow when you create an applicant.
Edit flows in the panel (Settings): checks (aml, duplicate, age_only), the electronic document check (off, optional, required, mobile SDK only) and data retention. Every change creates a new flow version. A session uses the flow version that was current when it was created, so changes never affect sessions already in progress.
Decision rules, minimum age and the list of accepted document types and countries are set by GOXOST KYC for all accounts and cannot be changed per account.
Read flows with GET /flows and GET /flows/{key}. Which documents are supported in which country is in the public GET /documents/catalog.