---
title: "List verification requests"
method: GET
path: "/api/v1/verification-requests"
tags: ["Verification Requests"]
---

# List verification requests

`GET /api/v1/verification-requests`

## Request

- Base URL: `https://api.proof.holdings`
- URL: `https://api.proof.holdings/api/v1/verification-requests`
- Auth: HTTP bearer

Get paginated list of verification requests.

## Query parameters

- `page` integer
- `limit` integer
- `status` 'pending' | 'partial' | 'completed' | 'expired' | 'cancelled' | 'active': Status filter for listing verification requests. `active` is a synthetic alias for live (not-yet-expired) pending or partial requests; `pending`/`partial`/`expired` are time-aware.
- `reference_id` string

## Response `200`

List of verification requests

- VerificationRequestListResponse
  - `data` VerificationRequestListItem[], required
    - `id` string, required: MongoDB ObjectId
    - `reference_id` string
    - `status` 'pending' | 'partial' | 'completed' | 'expired' | 'cancelled', required: Status of a verification request
    - `computed_state` object, required
      - `status` 'pending' | 'partial' | 'completed' | 'expired' | 'cancelled', required: Status of a verification request
      - `is_expiring_soon` boolean, required: Whether this request is close enough to `expires_at` to act on — and the WINDOW depends on which side of the request is reading, so one row can honestly answer differently on two surfaces. Read `next_action.role` to know which answer you have. For a `requester` the window is the lesser of 24h and HALF the request's own lifetime, so a just-created short-lived request is NOT "expiring soon" (advising a reminder before the recipient has had any time is the case this excludes). For a `recipient` the window is a flat 24h, because they already hold the link and what matters is the deadline itself.
      - `next_action` object, required
        - `code` string, required
        - `role` 'requester' | 'recipient', required
        - `label` string, required
    - `action_type` 'verification' | '2fa' | 'login' | 'custom' | 'confirmation' | 'authorization', required: Type of action for verification request or authorization
    - `asset_count` integer, required: How many assets the request asks for
    - `progress` object, required
      - `completed` integer, required
      - `completed_required` integer, required
      - `required` integer, required
      - `total` integer, required
    - `expires_at` string, date-time, required
    - `completed_at` string, date-time
    - `created_at` string, date-time, required
  - `pagination` PaginationResponse, required: Pagination info in list responses
    - `page` integer
    - `limit` integer
    - `total` integer
    - `total_pages` integer

---

[API](https://skmtc.dev/proof/apis/proof-holdings-api.md) · [All operations](https://skmtc.dev/proof/apis/proof-holdings-api/llms.txt) · [OpenAPI document](https://skmtc.dev/proof/apis/proof-holdings-api/revisions/b15f506de696?raw)