---
title: "Create a verification request"
method: POST
path: "/v1/requests"
---

# Create a verification request

`POST /v1/requests`

## Request

- Base URL: `https://api.lumethic.com`
- URL: `https://api.lumethic.com/v1/requests`
- Auth: `OAuth2PasswordBearer` (a scheme the document does not define)

Create a request and return its link.

The provider opens ``url`` (or scans its QR code), uploads a camera original
and the delivered JPEG, and needs no account. The verification runs under
this account and counts against its monthly allowance at the normal
metered price. ``token`` is a bearer secret and is returned on every read.

## Headers

- `X-API-Key` string, nullable

## Request body

- VerificationRequestCreate
  - `subject` string, required: The requester's own words for what is being asked ('front of the item', 'entry 48392'). Shown on the landing page and the record, labelled as the requester's words; never something Lumethic verified. Control characters are rejected.
  - `instructions` string, nullable: Free text for the landing page. Control characters other than newlines are rejected.
  - `expires_at` string, date-time, required: After this instant the public routes answer 410 REQUEST_EXPIRED. Must be in the future and at most 365 days out.
  - `max_submissions` integer, nullable: Cap on accepted uploads. Defaults by plan (free 5, paid 25) and is limited by a plan ceiling (free 5, Basic 25, Professional 250, Enterprise unlimited); above the ceiling is 422.
  - `share_with_provider` boolean: Create the public share for every submission at upload, so the provider reaches the record.
  - `mode` 'existing_original' | 'capture': How the provider answers a request: an uploaded camera original, or a capture with Lumethic Capture.

## Response `201`

Successful Response

- VerificationRequestResponse
  - `id` string, uuid, required
  - `subject` string, required
  - `instructions` string, nullable, required
  - `mode` 'existing_original' | 'capture', required: How the provider answers a request: an uploaded camera original, or a capture with Lumethic Capture.
  - `status` 'open' | 'closed' | 'expired', required: Derived status of a verification request. ``open`` and ``closed`` are stored; ``expired`` is ``open`` past ``expires_at`` and is never written to the row.
  - `expires_at` string, date-time, required
  - `closed_at` string, date-time, nullable, required
  - `max_submissions` integer, required
  - `submission_count` integer, required: Accepted uploads so far (counted, never stored).
  - `share_with_provider` boolean, required
  - `token` string, required: Bearer secret: anyone holding it can open the landing page and upload to this request until it closes, expires or fills. Returned on every owner read; listing requests exposes every open link of the account.
  - `url` string, required: The landing page link (and the QR code's content): {FRONTEND_URL}/r/{token}.
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `400`: Account name required
- `422`: Invalid request

---

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