API ReferenceDocuments

Update document metadata

Update mutable metadata on a document such as classification, linked session or identity, and custom metadata.

Required scope: documents:write

Authentication

X-API-Keystring

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

Path parameters

document_idstringRequired

Document ID (doc_*).

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 an object.
classificationstringOptional
Updated document classification.
identity_idstring or nullOptional
Identity ID to link or unlink.
session_idstring or nullOptional
Session ID to link or unlink.
metadatamap from strings to anyOptional

Arbitrary key-value metadata.

statusenumOptional
Manually set document status.
Allowed values:

Response

Document updated.
idstring

Document ID (doc_*).

document_typeenum
statusenum
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).

preview_urlstring or null

Server-side JPEG preview URL for page 1. Works for both PDFs (rendered via PyMuPDF) and images. Same HMAC signature as download_url. Null for redacted documents.

extracted_fieldsmap from strings to any or null

Structured field extraction produced by Verifa’s document extractor. Populated when the document’s matched document_type has non-empty extraction_hints. Each key is one of the field names from the type’s extraction_hints, and each value is either the extracted string or null if the field was not visible in the document. null until the verification pipeline has run.

extracted_fields_confidencemap from strings to doubles or null

Per-field token-presence confidence (0.0-1.0) for the corresponding entries in extracted_fields. Computed by checking whether each extracted value’s tokens actually appear in the underlying OCR text. Values below ~0.5 are likely hallucinations and should be flagged for reviewer attention. null until extraction has run.

updated_atdatetime or null

Errors

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