DocumentationAPI Reference
General reference

Incode Session Statuses

There are two categories of session status values:

**Note**

Some of the API and code references on this page refer to onboarding sessions. Some of the statuses can apply to either onboarding or authentication sessions. It's important to know the difference between onboarding and authentication.

Onboarding Progress Statuses

A session moves through these statuses in order. Not every status occurs in every session. The modules configured in your Workflow or Flow determine which statuses occur.

Sequential Processing Statuses

Status Description
UNKNOWN Initial status. The session is created but the user has not yet started it. For example, an onboarding URL has been shared but the user has not clicked it. No webhook notification is sent for this status. Retrieve it by calling the get session status endpoint.
ID_VALIDATION_FINISHED ID document validation is complete. OCR data has been extracted and the idValidation score has been calculated. Preliminary OCR data and the ID validation score can be fetched at this point. Wait for ONBOARDING_FINISHED before fetching final results.
ID_VALIDATION_FINISHED_SECOND_ID ID document validation is complete for a second ID document, if applicable. Preliminary data for the second ID can be fetched at this point.
GOVERNMENT_VALIDATION_FINISHED Validation against a government registry or third-party source of truth is complete. Preliminary government validation results can be fetched. Wait for ONBOARDING_FINISHED before fetching final results.
FACE_VALIDATION_FINISHED Face Match is complete. The selfie has been compared against the ID document photo. The faceRecognition and liveness scores have been calculated. If government validation is part of the flow, this status generally occurs after GOVERNMENT_VALIDATION_FINISHED.
POST_PROCESSING_FINISHED ID post-processing is complete. Used in specific implementations where additional server-side data review is required after ID capture.
POST_PROCESSING_FINISHED_SECOND_ID ID post-processing is complete for the second ID document, if applicable.
ONBOARDING_FINISHED The session is complete. All data has been collected and processed, business rules have been applied, the final session score has been calculated, and the user has exited the flow. Wait for this status for before fetching scores and session data.

Post-Completion Statuses

These statuses occur after ONBOARDING_FINISHED and show the outcome of manual review or session lifecycle events.

Status Description
MANUAL_REVIEW_APPROVED A session that was in a Needs Review state has been manually approved by a reviewer in Dashboard.
MANUAL_REVIEW_REJECTED A session that was in a Needs Review state has been manually rejected by a reviewer in Dashboard.
EXPIRED A time limit is configured on the Flow or Workflow and the user abandons the session after that limit. If the user returns, they see a session expired screen.
DELETED The session's data has been deleted. Deletion is not immediate. Finished sessions are placed in a queue. The webhook payload for this status uses interviewIds, a string array, instead of the usual interviewId field. Multiple sessions may be deleted in a single event. See Deleted sessions below.

Manual Session States

You can manually set a session's state by calling the POST /omni/session/status/set endpoint with one of the following action values:

State Description
Alive The session is active. All /add/... data capture calls are permitted. This is the default state for a session in progress.
Closed The session is closed. All /add/... calls are disabled. No further data can be added to the session. The session data is preserved.
Deleted The important data stored in the session is deleted. See Deleted sessions below.

Deleted Sessions

Deleted appears in both categories because a session can reach a deleted state in two ways:

  1. Manually, by calling POST /omni/session/status/set with action: Deleted.
  2. Automatically, as a platform-level data deletion event. For example, when data retention policies cause session data to be purged.

In both cases, if you have configured the Onboarding Status Webhook, a DELETED webhook notification is sent when the deletion is processed. The payload for this notification differs from all other onboarding status webhooks; it contains an interviewIds array of one or more session IDs, rather than a single interviewId field.

Webhook Coverage

Not all onboarding progress statuses trigger a webhook notification. The table below shows which statuses send a webhook when the Onboarding Status Webhook is configured.

Status Webhook sent?
UNKNOWN ❌ No, poll the API instead
ID_VALIDATION_FINISHED ✅ Yes
ID_VALIDATION_FINISHED_SECOND_ID ✅ Yes, if applicable
GOVERNMENT_VALIDATION_FINISHED ✅ Yes
FACE_VALIDATION_FINISHED ✅ Yes
POST_PROCESSING_FINISHED ✅ Yes
POST_PROCESSING_FINISHED_SECOND_ID ✅ Yes, if applicable
ONBOARDING_FINISHED ✅ Yes
MANUAL_REVIEW_APPROVED ✅ Yes
MANUAL_REVIEW_REJECTED ✅ Yes
EXPIRED ✅ Yes
DELETED ✅ Yes, payload uses interviewIds array

Was this page helpful?