# Sessions

> Create, list, retrieve, decide and cancel verification sessions; evidence URLs and PII erasure.

Source: https://docs.okyc.stream/reference/api/sessions

Guide: [sessions](https://docs.okyc.stream/backend/sessions.md).

Base URL `https://api.okyc.stream/v1` · API version `2026-10-01` · authenticate with `Authorization: Bearer sk_test_…`.

### POST /v1/sessions

Create a verification session.

**Request body** ([CreateSession](https://docs.okyc.stream/reference/api/schemas.md#createsession), required)

| Field               | Type         | Required | Notes                                                      |
| ------------------- | ------------ | -------- | ---------------------------------------------------------- |
| `workflow_id`       | `string`     | yes      | —                                                          |
| `reference_id`      | `string`     |          | Your user's id — max length 128                            |
| `country`           | `string`     |          | Applicant's country; defaults to the workflow's — length 2 |
| `prefill`           | `object`     |          | —                                                          |
| `prefill.phone`     | `string`     |          | —                                                          |
| `prefill.email`     | `string`     |          | format `email`                                             |
| `prefill.full_name` | `string`     |          | —                                                          |
| `locale`            | `string`     |          | —                                                          |
| `redirect_url`      | `string`     |          | format `uri`                                               |
| `metadata`          | object (map) |          | —                                                          |
| `expires_in`        | `integer`    |          | Seconds — min 300, max 2592000                             |

**Responses**

| Status | Description | Body                                                    |
| ------ | ----------- | ------------------------------------------------------- |
| `201`  | Created     | [CreatedSession](https://docs.okyc.stream/reference/api/schemas.md#createdsession) |
| `400`  | Error       | [Error](https://docs.okyc.stream/reference/api/schemas.md#error)                   |
| `401`  | Error       | [Error](https://docs.okyc.stream/reference/api/schemas.md#error)                   |

### GET /v1/sessions

List sessions.

**Parameters**

| Name             | In    | Type                                                                                                                                                    | Required | Notes                        |
| ---------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ---------------------------- |
| `limit`          | query | `integer`                                                                                                                                               |          | min 1, max 100, default `25` |
| `starting_after` | query | `string`                                                                                                                                                |          | —                            |
| `status`         | query | `created` \| `started` \| `in_progress` \| `processing` \| `approved` \| `declined` \| `review` \| `resubmission_requested` \| `expired` \| `cancelled` |          | —                            |
| `reference_id`   | query | `string`                                                                                                                                                |          | —                            |

**Responses**

| Status | Description | Body     |
| ------ | ----------- | -------- |
| `200`  | OK          | `object` |

### GET /v1/sessions/\{id}

Retrieve a session.

**Parameters**

| Name     | In    | Type     | Required | Notes                   |
| -------- | ----- | -------- | -------- | ----------------------- |
| `id`     | path  | `string` | yes      | e.g. `ses_in_01j…`      |
| `expand` | query | `string` |          | e.g. `checks,applicant` |

**Responses**

| Status | Description | Body                                      |
| ------ | ----------- | ----------------------------------------- |
| `200`  | OK          | [Session](https://docs.okyc.stream/reference/api/schemas.md#session) |
| `404`  | Error       | [Error](https://docs.okyc.stream/reference/api/schemas.md#error)     |

### POST /v1/sessions/\{id}/decision

Decide a session in review (or override a final decision).

**Parameters**

| Name | In   | Type     | Required | Notes              |
| ---- | ---- | -------- | -------- | ------------------ |
| `id` | path | `string` | yes      | e.g. `ses_in_01j…` |

**Request body** ([Decision](https://docs.okyc.stream/reference/api/schemas.md#decision), required)

| Field         | Type                                                 | Required | Notes                                           |
| ------------- | ---------------------------------------------------- | -------- | ----------------------------------------------- |
| `outcome`     | `approved` \| `declined` \| `resubmission_requested` | yes      | —                                               |
| `reason_code` | `string`                                             | yes      | max length 64                                   |
| `note`        | `string`                                             |          | max length 2000                                 |
| `steps`       | `string`\[]                                          |          | For resubmission: steps the applicant must redo |

**Responses**

| Status | Description | Body                                  |
| ------ | ----------- | ------------------------------------- |
| `200`  | OK          | `object`                              |
| `409`  | Error       | [Error](https://docs.okyc.stream/reference/api/schemas.md#error) |

### POST /v1/sessions/\{id}/cancel

Cancel an active session.

**Parameters**

| Name | In   | Type     | Required | Notes              |
| ---- | ---- | -------- | -------- | ------------------ |
| `id` | path | `string` | yes      | e.g. `ses_in_01j…` |

**Responses**

| Status | Description | Body                                  |
| ------ | ----------- | ------------------------------------- |
| `200`  | OK          | `object`                              |
| `409`  | Error       | [Error](https://docs.okyc.stream/reference/api/schemas.md#error) |

### POST /v1/sessions/\{id}/client\_token

Issue a fresh client token (resume in the frontend).

**Parameters**

| Name | In   | Type     | Required | Notes              |
| ---- | ---- | -------- | -------- | ------------------ |
| `id` | path | `string` | yes      | e.g. `ses_in_01j…` |

**Responses**

| Status | Description | Body                                  |
| ------ | ----------- | ------------------------------------- |
| `200`  | OK          | `object`                              |
| `409`  | Error       | [Error](https://docs.okyc.stream/reference/api/schemas.md#error) |

### GET /v1/sessions/\{id}/evidence/\{evidence\_id}

Short-lived URL for an evidence file.

**Parameters**

| Name          | In   | Type     | Required | Notes              |
| ------------- | ---- | -------- | -------- | ------------------ |
| `id`          | path | `string` | yes      | e.g. `ses_in_01j…` |
| `evidence_id` | path | `string` | yes      | —                  |

**Responses**

| Status | Description | Body                                  |
| ------ | ----------- | ------------------------------------- |
| `200`  | OK          | `object`                              |
| `404`  | Error       | [Error](https://docs.okyc.stream/reference/api/schemas.md#error) |

### DELETE /v1/sessions/\{id}/pii

Erase personal data (DPDP erasure).

**Parameters**

| Name | In   | Type     | Required | Notes              |
| ---- | ---- | -------- | -------- | ------------------ |
| `id` | path | `string` | yes      | e.g. `ses_in_01j…` |

**Responses**

| Status | Description | Body     |
| ------ | ----------- | -------- |
| `200`  | OK          | `object` |