Sessions
Create, list, retrieve, decide and cancel verification sessions; evidence URLs and PII erasure.
Guide: sessions.
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, 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 |
400 | Error | Error |
401 | Error | 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
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, 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 |
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 |
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 |
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 |
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 |
REST API
Base URL, authentication, versioning and the OpenAPI document every page here is generated from.
Checks
Run a single check server-to-server, without a hosted session, and fetch its result.
© 2026 Aiistic Technologies Private Limited. OKYC is a product of Aiistic Technologies Private Limited. Privacy notice