API ReferenceDocuments

Upload a standalone document

Upload a document outside the context of a capture session. Optionally attach it to an existing session or identity. The document is stored and available for classification, extraction, and verification via the sub-resource action endpoints.

Required scope: documents:write

Authentication

X-API-Keystring

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

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 10 MB.

document_typeenumRequired
The type of document being uploaded.
Allowed values:
session_idstringOptional
Optional session ID to attach the document to.
identity_idstringOptional
Optional identity ID to attach the document to.
classificationstringOptional

Optional document classification (e.g. passport, drivers_license).

original_filenamestringOptional
Original filename of the uploaded document.

Response

Document uploaded successfully.
idstring

Document ID (doc_*).

document_typeenum
Allowed values:
statusenum
Allowed values:
created_atdatetime
org_idstring
Organization ID.
session_idstring or null
Associated session ID, if any.
identity_idstring or null
Associated identity ID, if any.
classificationstring or null

Detected or assigned document classification (e.g. passport, drivers_license).

mime_typestring or null
MIME type of the uploaded file.
file_size_bytesinteger or null
File size in bytes.
original_filenamestring or null
Original filename at upload time.
page_countinteger or null

Number of pages (for multi-page documents).

metadatamap from strings to any

Arbitrary key-value metadata.

upload_sourcestring or null

How the document was uploaded (api, capture, dashboard).

download_urlstring or null

HMAC-signed download URL (when available).

updated_atdatetime or null

Errors

400
Bad Request Error
401
Unauthorized Error
422
Unprocessable Entity Error