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

# Handle verification sessions

> Retry session creation safely and parse polling and streaming payloads correctly.

Create a session with `POST /v2/sessions`. Keep the same `Idempotency-Key` and unchanged JSON payload when retrying an uncertain result. The optional key supports up to 256 characters.

| Result | Your next step |
| - | - |
| `200` | Read the create payload, including `reusedExisting`, and direct the user to `verifyUrl`. |
| `409 IDEMPOTENCY_CONFLICT` | Stop: the key was already used for a different payload. |
| `503 IDEMPOTENCY_IN_PROGRESS` | Wait for `Retry-After: 2`, then retry the unchanged request with the same key. |

Read status using `GET /v2/sessions/{id}`. The read payload includes `createdAt`, `terminalAt`, and `result`; it does **not** contain the create-only `reusedExisting` field. JSON success responses wrap this payload in `data`.

Use `If-None-Match` with the response's `ETag`. A matching response is HTTP `304` with an empty body. Reuse your cached payload instead of parsing JSON. You can use `wait=25` to long poll; respect polling limits and retry headers.

The stream endpoint is `GET /v2/sessions/{id}/stream`. Listen for events named `session`. Parse each event's `data` as the session object directly; it has no JSON response envelope. Terminal states close the stream. If a session disappears, the stream can end with a minimal `id` and `status: "expired"` object.

Keep v1 integration parsing separate. V1 uses `sid`, `status_reason`, and `status` / `complete` / `expired` stream event names. Do not redirect v1 endpoints to v2 or reuse the v2 parser for v1.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.