> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usecontra.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Sessions Overview

> Each session is one verification run for a user or business. Lifecycle, statuses, idempotency, sharing — all explained here.

A **session** is the core unit of Contra verification. Every flow follows the same lifecycle:

```mermaid theme={null}
flowchart LR
  C[Create] --> U[User visits url] --> P[Decision] --> A{status}
  A -- approved --> Tk[ContraToken issued]
  A -- in_review --> M[Manual review]
  A -- declined --> X[Stop]
```

## Statuses

| Status        | Meaning                                                        |
| ------------- | -------------------------------------------------------------- |
| `pending`     | Just created. User hasn't opened the verification URL yet.     |
| `in_progress` | User is completing verification.                               |
| `in_review`   | Borderline result. Awaiting manual decision or auto-aging out. |
| `approved`    | All required nodes passed → **ContraToken issued**.            |
| `declined`    | One or more required nodes failed.                             |
| `expired`     | Session passed its `expires_at` without resolution.            |

## Idempotency

Posting [Create Session](/api-reference/sessions/create) twice with the same `(workflow_id, vendor_data)` while a session is **active** (`pending` / `in_progress` / `in_review`) returns the **existing** session with `idempotent_reuse: true`.

## Webhook events

| Event                    | Fires on                                  |
| ------------------------ | ----------------------------------------- |
| `session.status_changed` | Every status transition                   |
| `session.data_updated`   | KYC / PoA extracted-data manually patched |
| `session.review_created` | A reviewer added a note or override       |

See [Webhook Destinations](/api-reference/webhooks/list).

## Endpoints

<CardGroup cols={2}>
  <Card title="Create Session" icon="plus" href="/api-reference/sessions/create" />

  <Card title="Retrieve Session" icon="magnifying-glass" href="/api-reference/sessions/get" />

  <Card title="Get Decision" icon="circle-check" href="/api-reference/sessions/get-decision" />

  <Card title="List Sessions" icon="list" href="/api-reference/sessions/list" />

  <Card title="Update Status" icon="pen" href="/api-reference/sessions/update-status" />

  <Card title="Update Data" icon="pen-to-square" href="/api-reference/sessions/update-data" />

  <Card title="Delete Session" icon="trash" href="/api-reference/sessions/delete" />

  <Card title="Generate PDF" icon="file-pdf" href="/api-reference/sessions/generate-pdf" />

  <Card title="Share Session" icon="share-nodes" href="/api-reference/sessions/share" />

  <Card title="Import Shared Session" icon="download" href="/api-reference/sessions/import-shared" />
</CardGroup>