Skip to content
API reference Get API keys

Integration · Chapter 5

Verification flow

How applicants, sessions and verifications fit together, what the user sees, and how to handle every decision.

9 min read

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; otherwise 409 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 410 and 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 session locale, then the browser language.
  • In live, creating a session reserves one unit of your monthly limit (429 plan_limit_reached when 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

  1. 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.
  2. Consent. The user agrees to the processing of their data, including biometric data for the selfie. The consent time is recorded in the certificate.
  3. 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.
  4. Selfie. The user takes a short selfie by following the on-screen instructions. This step also confirms that a real person is taking part.
  5. 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 is RED or ON_HOLD (table below);
  • checks — one entry per check (document, face_match, liveness, and when enabled aml, duplicate, age, plus doc_fraud and chip), each with status (pass, warn, fail or error), score and labels;
  • document — type, country and the document data (document.data);
  • risk_score from 0 to 1;
  • valid_until — a GREEN result is valid for 2 years. You get applicant.reverification_due 30 days before and when it ends.
Important

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:

{ "decision": "GREEN", "comment": "manual check ok" }
{ "decision": "RED", "decision_type": "final", "reject_labels": ["DOC_FORGED"] }
  • Only the applicant's latest ON_HOLD verification can be reviewed. An already decided, outdated or stale one returns 409 conflict; so does a verification another reviewer has open in the panel.
  • RED needs decision_type and at least one label. REVIEW_EXPIRED cannot be chosen.
  • The comment is not stored.
  • After the review you get verification.reviewed with the new decision.
  • If your account has the four-eyes rule on (panel → Settings → Review), a RED from the API returns 202 Accepted and stays ON_HOLD until a different person confirms it in the panel. GREEN is 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 + retry the applicant goes back to init automatically. Create a new session and send the user through the flow again.
  • To verify again after GREEN, RED + final or a stuck attempt, call POST /applicants/{id}/reset. Status becomes init, decision, risk_score and last_verification_id are cleared, and open sessions become abandoned. History stays in GET /applicants/{id}/verifications. You get applicant.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 returns 202 with deletion_scheduled, sends applicant.deleted, and afterwards the applicant returns 404.

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.