Session statuses

The status of a KYC session is returned in the status field of the kyc/session/status response, in the session list and in the SESSION_COMPLETE webhook (see Webhooks).


Values

StatusMeaningFinal
idleThe session is created, processing has not startedNo
processingThe session is being processed, including database checksNo
successVerification passedYes
failedVerification failedYes, once the session lifetime is over; with the [legal] database check failed code — immediately
suspiciousThe session is flagged as suspiciousYes
exceptionProcessing errorNo
expiredThe user did not finish the session within the link lifetimeYes

When the result is final

  • While the session has time left (secondsToLive greater than 0) and attempts remain, the user can retake a step. So failed can change to success.
  • Treat the result as final when secondsToLive = 0, or when the status is success or suspicious.
  • When the lifetime is over, a session in idle becomes expired. A session in processing gets its final status when processing finishes.
  • failed with the [legal] database check failed code in errors is a refusal by a blocking database check. Treat it as a final refusal without waiting for the lifetime to end: secondsToLive may still be greater than 0 (see the section below).
  • Receive the result by webhook in the default mode, where a webhook comes on every change of the session result, and pick the final statuses on your side by the rules above. In the "Notify only when the session is finalized" mode no webhook comes if the session got failed while it still had time left, including a refusal by a blocking database check.

Refusal by a database check

A database check can be marked as blocking in the scenario. If a blocking check fails, a session that passed its steps gets the failed status, and the [legal] database check failed code appears in errors. Non-blocking checks do not affect the session status: their outcome is only in the database check results.

If the check is run again and passes, the code is removed and the session status is worked out anew.


The suspicious status

A session becomes suspicious if:

  • the face images show different people — such a session is blocked for good;
  • the critical error limit set in the scenario is reached;
  • the face did not match the reference session (see kyc/session/reference).

If the user exceeded the number of attempts, the session errors contain [general] too many tries.


The exception status

exception on a whole session is rare: request the status again. More often exception is the status of a single step or check inside the session.


Changing the status manually

The status can be changed with kyc/session/status/change. The method accepts any of the seven values above.


Questionnaire statuses

A stage-1 questionnaire record (see Two-stage verification: questionnaire → KYC) has two statuses:

StatusMeaning
idleThe questionnaire is open, the answers have not been submitted
successThe questionnaire answers are recorded

success on a questionnaire is not a decision about the user. Database check results are in the checks field.


Session not found

If there is no session with the given identifier, the method answers HTTP 200 with the body:

{
  "status": "error",
  "message": "session not found"
}

Check the status field of the response body, not only the HTTP code.