Upload a document to a session | Verifa

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

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_*).

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_typestringOptional

Proof-of-address document subtype (e.g. utility_bill, bank_statement). Required when document_type is proof_of_address.

poa_document_datedateOptional

Date on the proof-of-address document (YYYY-MM-DD).

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.

Allowed values:

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

1	import requests
2
3	url = "https://devapi.withverifa.com/api/v1/sessions/session_id/documents"
4
5	files = { "file": "open('string', 'rb')" }
6	payload = {
7	"document_type": "id_front",
8	"poa_document_type": ,
9	"poa_document_date":
10	}
11	headers = {"X-API-Key": "<apiKey>"}
12
13	response = requests.post(url, data=payload, files=files, headers=headers)
14
15	print(response.json())

1	{
2	"id": "doc_abc123",
3	"session_id": "ses_abc123",
4	"document_type": "id_front",
5	"mime_type": "image/jpeg",
6	"file_size_bytes": 245760,
7	"created_at": "2024-01-15T09:30:00Z"
8	}

Authentication

Path parameters

Headers

Request

Response

Errors