---
title: "List verification sessions"
method: GET
path: "/verifications"
tags: ["Verifications"]
---

# List verification sessions

`GET /verifications`

## Request

- Base URL: `https://developers.ozav.io/v2`
- URL: `https://developers.ozav.io/v2/verifications`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Lists verification sessions, newest first, with the standard cursor
pagination. Filter to one customer with the `customer_id` query
parameter to recover an existing verification id after `POST
/verifications` or after a duplicate `VERIFICATION_ALREADY_EXISTS`
response. Returns a `Page` of `Verification`.

## Query parameters

- `limit` integer
- `starting_after` string
- `customer_id` string

## Response `200`

Paginated verification sessions.

- object: The uniform envelope every list endpoint returns.
  - `data` Verification[], required: The page of results. Each list endpoint documents its own item type.
    - `id` string, required: Opaque verification identifier, prefixed `ozav_vrf_`.
    - `object` 'verification', required: Resource type discriminator; always the literal `verification`.
    - `customer_id` string, required: The `ozav_cus_` id of the customer being verified.
    - `session_url` string, uri: Hosted verification session URL - redirect the end-user here to complete identity capture (government ID, selfie, liveness; KYB/UBO for a business customer). **In sandbox this field never appears.** A `test` key never starts a hosted session, because a real session bills a third party per attempt. Exercise the outcome with `POST /verifications/{verification_id}/simulate` instead - that is the sandbox affordance, and it lets you drive `approved` or `rejected` yourself. **With a `live` key, two things must both be true**, and the second is not something you control: 1. Your `capabilities` include at least one that hosted capture covers: `kyc_document`, `liveness`, `face_match`, `age_estimation`, `kyb`, `ubo`. Asking only for list/data checks (`aml_name_screening`, `economic_capacity`, ...) never starts a session, because there is nothing for the end-user to do. 2. Hosted capture is switched on at OZAV. This is a single platform-wide setting, **not** something enabled per organization - there is nothing to request for your account. While it is off, no `live` key starts a session. When either condition is missing - or the key is a `test` key - the verification is still created and is a valid record with **no `session_url`**. That is not an error and retrying will not produce one. For an individual on a `live` key with hosted capture off, it is `in_progress` with the hosted checks at `review` and `pending_documents` saying what to upload instead; otherwise it stays `pending` with `checks` at `not_started`. The field is never fabricated: if the session cannot be created, the request fails with a `503` and nothing is persisted, rather than returning a record with a broken link. The `code` says whether retrying helps: `VERIFICATION_SESSION_UNAVAILABLE` (retry shortly), `VERIFICATION_TEMPORARILY_UNAVAILABLE` (on OZAV's side, not caused by your data - retry later with the same data), `VERIFICATION_PROVIDER_REJECTED` or `VERIFICATION_PROVIDER_NOT_CONFIGURED` (contact OZAV support with the `request_id`).
    - `status` 'pending' | 'in_progress' | 'completed' | 'expired', required: Overall state of the verification session: - `pending` - created; checks have not started. - `in_progress` - one or more checks are running. - `completed` - every check reached an outcome. - `expired` - the session expired before completing.
    - `pending_documents` object[]: Only on the `POST /verifications` response, and only when no hosted session was started for an individual: the documents still to send with `POST /customers/{customer_id}/documents`. Absent otherwise.
      - `doc_type` string, required: For example `identity_document`, `selfie`, `proof_of_address`.
      - `state` 'missing' | 'rejected', required
      - `reason` string: Why a rejected file was not accepted.
    - `checks` object: Per-capability check results, keyed by `CapabilityKind`.
    - `created_at` string, date-time: When the verification session was created (RFC 3339 / ISO 8601, UTC).
  - `has_more` boolean, required: True when more results exist beyond this page - keep paging with `starting_after`.
  - `next_cursor` string, nullable: Opaque cursor for the next page; pass it as `starting_after`. Null on the last page.

## Other responses

- `401`: Missing or invalid API key.

---

[API](https://skmtc.dev/ozav/apis/ozav-api.md) - [All operations](https://skmtc.dev/ozav/apis/ozav-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ozav/apis/ozav-api/revisions/4133dc2109d7?raw)