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
| Status | Meaning | Final |
|---|---|---|
idle | The session is created, processing has not started | No |
processing | The session is being processed, including database checks | No |
success | Verification passed | Yes |
failed | Verification failed | Yes, once the session lifetime is over; with the [legal] database check failed code — immediately |
suspicious | The session is flagged as suspicious | Yes |
exception | Processing error | No |
expired | The user did not finish the session within the link lifetime | Yes |
When the result is final
- While the session has time left (
secondsToLivegreater than 0) and attempts remain, the user can retake a step. Sofailedcan change tosuccess. - Treat the result as final when
secondsToLive= 0, or when the status issuccessorsuspicious. - When the lifetime is over, a session in
idlebecomesexpired. A session inprocessinggets its final status when processing finishes. failedwith the[legal] database check failedcode inerrorsis a refusal by a blocking database check. Treat it as a final refusal without waiting for the lifetime to end:secondsToLivemay 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
failedwhile 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:
| Status | Meaning |
|---|---|
idle | The questionnaire is open, the answers have not been submitted |
success | The 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.