API ReferenceDocuments

Upload a document to a session

Upload a document image (ID front, ID back, or selfie) to a session via the API. This enables document submission from native mobile apps or custom UIs without using the hosted capture flow. If a document of the same type already exists, it is replaced (idempotent). If the session was in `pending` status, it transitions to `capturing`. **Required scope:** `documents:write`

Authentication

X-API-Keystring

Organization API key. Keys are prefixed with vk_live_ (production) or vk_sandbox_ (sandbox).

Path parameters

session_idstringRequired

Session ID (ses_*).

Headers

Verifa-VersiondateOptional

API version date string (e.g. 2026-02-01). If omitted, the version pinned to your API key is used.

Request

This endpoint expects a multipart form containing a file.
filefileRequired

The document image file (JPEG, PNG, WebP, or PDF). Max 10MB.

document_typeenumRequired
The type of document being uploaded.
poa_document_typeenumOptional

Proof-of-address document subtype. Optional, but strongly recommended when document_type is proof_of_address: without it the check cannot apply the per-type recency window and falls back to the policy default.

poa_document_datedateOptional

Date printed on the proof-of-address document (YYYY-MM-DD). Compared against the date OCR reads off the document — a disagreement larger than the policy’s date_match_tolerance_days raises a date_mismatch reason.

poa_issuing_countrystringOptionalformat: "^[A-Z]{2}$"=2 characters

Country that issued the proof-of-address document. Optional; defaults to the country of the ID document on the session. Drives country-aware address normalisation, PO-box detection, and any per-country recency override in the policy.

Response

Document uploaded successfully.
idstring
Public ID of the uploaded document.
session_idstring
Public ID of the session.
document_typeenum
The type of document uploaded.
mime_typestring
MIME type of the uploaded file.
file_size_bytesinteger
Size of the uploaded file in bytes.
created_atdatetime
When the document was uploaded.

Errors

400
Bad Request Error
401
Unauthorized Error
404
Not Found Error
422
Unprocessable Entity Error