> For the complete documentation index, see [llms.txt](https://docs.1kosmos.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.1kosmos.com/identity-verification/core-concepts/session.md).

# Session

***

### Overview

A **session** is a single user's attempt at a verification flow. Every verification you run - whether you started it from AdminX, the API, an OIDC/SAML redirect, or a webhook callback produces exactly one session.

### What a session contains

| Field           | Description                                                                                                                                           |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sessionId`     | Globally unique identifier. Use it to fetch results or cancel.                                                                                        |
| `url`           | The hosted verification URL. Hand this to the user any way you like.                                                                                  |
| `journeyTag`    | The flow this session was created against.                                                                                                            |
| `status`        | `pending` → `in_progress` → terminal state. See the lifecycle below.                                                                                  |
| `expiresAt`     | When the session will time out if no further activity occurs.                                                                                         |
| `referenceData` | The first name, last name, and DOB you supplied (optional, used for name/DOB comparison).                                                             |
| `result`        | Populated once the session reaches a terminal state. See [Verification result](/identity-verification/core-concepts/viewing-verification-results.md). |

### Lifecycle

A session moves through a small state machine. Most paths converge on `success` or `failed`; a few branch off when the user walks away or your retention policy kicks in.

```mermaid
stateDiagram-v2
    [*] --> pending
    pending --> in_progress: user opens URL
    pending --> abandoned: expiresAt reached
    in_progress --> success: all checks pass
    in_progress --> failed: a required check fails
    in_progress --> review: needs manual review
    in_progress --> abandoned: user walks away
    success --> [*]
    failed --> [*]
    review --> [*]
    abandoned --> [*]
```

### Status meanings

* **pending** — Session created. URL is live but not yet opened.
* **in\_progress** — User has opened the URL. Document or biometric capture may be in flight.
* **success** — All required checks passed. `result` contains extracted fields and scores.
* **failed** — A required check failed. `result.failureReason` tells you which one. Common reasons: document expired, face match below threshold, AAMVA mismatch, document type not allowed.
* **review** — Verdict is ambiguous and requires a human reviewer. Only produced if your tenant has the manual-review queue enabled.
* **abandoned** — Session expired or the user closed the tab before reaching a verdict.
* **not\_performed** — A particular sub-check (e.g. AAMVA) couldn't run because the upstream system was unreachable. The session as a whole may still succeed depending on flow strictness.

### Expiry

Two timers govern when a session ends. Both are configured on the flow.

| Timer                     | Default (Configurable) | What it controls                                                |
| ------------------------- | ---------------------- | --------------------------------------------------------------- |
| **From Session Creation** | 7 days                 | How long the URL is valid if the user never opens it.           |
| **From Session Start**    | 60 minutes             | How long the user has to complete, once they've opened the URL. |

Once either timer elapses without a terminal state, the session moves to `abandoned`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.1kosmos.com/identity-verification/core-concepts/session.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.