# Sessions

> Create a verification, read it back, or cancel it while it is still open. Your sessionId is the idempotency key.

Canonical page: https://venuego.co.uk/docs/sessions

## Create or return

`POST /api/v1/verification-sessions`

Creating a session past the plan allowance returns `402`. There is no metered overage. See [Errors](https://venuego.co.uk/docs/errors/agent.md).

| Field | Required | Meaning |
| --- | --- | --- |
| `sessionId` | Yes | Your reference, 1–191 printable ASCII characters, no spaces. One verification per id. While it is still open, sending it again returns that session. A finished id returns `409` and `session_closed`. |
| `minimumAge` | No | Integer from 13 to 99. Otherwise the account default is used. A guest under this age is declined and cannot retry. |
| `webhookUrl` | No | Public HTTPS URL for this session only. Signed with the per-session secret from Developers, not an endpoint's secret. |
| `metadata` | No | Up to 50 keys. Values are strings up to 500 characters, finite numbers, booleans, or null. Keys are 1–40 characters: letters, digits, `_ . : -`. The object must be 8 KB or less. It is returned unchanged and is never shown to the guest. Do not put document numbers in it. |
| `successUrl` | No | Where the guest's browser goes after approval. HTTPS, or localhost in development. No embedded username or password. |
| `failureUrl` | No | Where the browser goes after a decline with no retry left, or when the session is expired or cancelled. |

When a redirect is used, VenueGo adds `verifyme_session_id` and `verifyme_status` to the query string. Still confirm the result with the API or a webhook.

## Response

`201` when the session is new, `200` when that `sessionId` already exists. The body is the verification, plus `created`.

```json
{
  "created": true,
  "sessionId": "order_8412",
  "publicId": "a1b2c3…",
  "url": "https://verify.venuego.co.uk/v/a1b2c3…",
  "status": "created",
  "step": "face",
  "stage": "waiting_for_phone",
  "attempt": 1,
  "minimumAge": 18,
  "metadata": { "customerId": "cus_1043", "ticketType": "VIP" },
  "successUrl": "https://example.com/checkout/verified",
  "failureUrl": "https://example.com/checkout/not-verified",
  "country": null,
  "documentType": null,
  "decision": null,
  "identity": null,
  "checks": [],
  "createdAt": "2026-10-07T16:00:00.000Z",
  "updatedAt": "2026-10-07T16:00:00.000Z",
  "expiresAt": "2026-10-08T16:00:00.000Z"
}
```

Send the guest to `url`. You do not upload images. The phone uploads straight to storage. Video is up to 40 MB (`video/webm` or `video/mp4`). Images are up to 8 MB JPEG.

## Read

`GET /api/v1/verification-sessions/:sessionId`

Returns the same payload without `created`. Unknown ids return `404` and `not_found`. Identity fields are present once a result exists. URL-encode `sessionId` if it contains characters such as `/` or `+`.

```bash
curl https://verify.venuego.co.uk/api/v1/verification-sessions/order_8412 \
  -H "Authorization: Bearer $VERIFYME_API_KEY"
```

## Cancel

`POST /api/v1/verification-sessions/:sessionId/cancel`

Cancels a session that is still open: `created`, `in_progress`, `processing`, or `declined` while a retry is still available. A finished session returns `409` and `not_open`. The response is the payload with `status: "cancelled"`, and a `verification.cancelled` webhook is sent.

```bash
curl -X POST https://verify.venuego.co.uk/api/v1/verification-sessions/order_8412/cancel \
  -H "Authorization: Bearer $VERIFYME_API_KEY"
```