# Incode Session Statuses There are two categories of session status values: - **Onboarding progress statuses** are set automatically by the Incode Platform as [a session moves](https://developer.incode.com/docs/onboarding-session-lifecycle) through its verification modules. You receive these via the [Onboarding Status Webhook](https://developer.incode.com/docs/onboarding-status-webhook) or by polling the [`/omni/get/onboarding/status`](https://developer.incode.com/reference/getonboardingstatus) endpoint. - **Manual session states** are values you set by calling the [`/omni/session/status/set`](https://developer.incode.com/reference/setsessionstatus) endpoint. > 📘 **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](https://developer.incode.com/docs/onboarding-vs-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](https://developer.incode.com/reference/getsessionstatus) 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](#deleted-sessions) below. | *** ## Manual Session States You can manually set a session's state by calling the [`POST /omni/session/status/set`](https://developer.incode.com/reference/setsessionstatus) 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](#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](https://developer.incode.com/docs/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](https://developer.incode.com/docs/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 | *** ## Related Pages - [Onboarding Session Lifecycle](https://developer.incode.com/docs/onboarding-session-lifecycle): How statuses change during a session - [Onboarding Status Webhook](https://developer.incode.com/docs/onboarding-status-webhook): Webhook payload details, authentication, and retry policy - [Session Webhooks](https://developer.incode.com/docs/session-webhooks): Targeted webhooks for specific session events (`Session_Started`, `Session_Failed`, `Session_Succeeded`, `Session_Pending_Review`) - [Get Session Status](https://developer.incode.com/reference/getonboardingstatus): API endpoint for polling session status - [Set Session Status](https://developer.incode.com/reference/setsessionstatus): API endpoint for setting session state