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

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
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 (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.
• If you need only the final result, enable the scenario setting "Notify only if the session is finalized" and receive it by webhook.

---

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.