scanverion

Node and Python are the first supported Scanverion client languages. This package provides synchronous and asynchronous standard-library clients for the OCR API.

Download and install

Install the published package from PyPI:

python -m pip install scanverion==0.1.1

It requires Python 3.10 or newer.

Quickstart

Client-held identity templates

from scanverion import IdentityTemplateImage

template = client.templates.create(
    [IdentityTemplateImage("portrait.png")],
    processing_authorized=True, idempotency_key="template-create-001")
comparison = client.templates.compare(
    reference_template=template["templateToken"],
    candidate_image=IdentityTemplateImage("candidate.png"),
    processing_authorized=True, idempotency_key="template-compare-001")

Use the configured Scanverion client shown below; AsyncScanverion exposes the same methods with await. Creation accepts 1-8 JPEG/PNG images (10 MiB each, 40 MiB combined). Compare a reference template or reference_images against a candidate template or one candidate_image. Both operations cost 2 credits on completion, require explicit processing authorization and a 1-96 character idempotency key, and never automatically retry. Do not print the template dictionary: tokens and search vectors are sensitive biometric data. There is no server gallery. Cosine similarity requires human review; it is not identity probability or liveness.

Camera liveness

Included in release 0.1.1. Availability depends on the deployment and workspace; a successful public try-out does not activate workspace API access. Check /api/v1/face-liveness/policy and workspace capabilities. Synchronous and asynchronous clients expose liveness.create_session and liveness.get_result:

import os
from uuid import uuid4
from scanverion import Scanverion

client = Scanverion(
    api_key=os.environ["SCANVERION_API_KEY"],
    base_url="https://api.scanverion.com",
)
session = client.liveness.create_session(
    processing_authorized=True, idempotency_key=str(uuid4()))

Complete the real camera challenge using Scanverion's React component and the returned capture metadata, then retrieve the assessment after its completion callback. The backend must authenticate participants, verify processing authorization and bind each session to its owner:

result = client.liveness.get_result(session_id=session["sessionId"], access_token=session["accessToken"])

Use await for the same methods on AsyncScanverion. Neither method automatically retries. Do not print or persist the session dictionary: its access token and short-lived capture ID are sensitive. Valid completed assessments are billable independently of pass/fail; liveness does not prove identity or compare faces. Camera flow, IAM, expiry and activation.

Document processing

import os
from pathlib import Path
from scanverion import Scanverion

client = Scanverion(
    api_key=os.environ["SCANVERION_API_KEY"],
    base_url=os.getenv("SCANVERION_API_URL", "https://api.scanverion.com"),
)
result = client.documents.process(
    Path("invoice.pdf"),
    file_name="invoice.pdf",
    content_type="application/pdf",
    operations=["Detection", "Scanner"],
    scanner_fields=["invoiceNumber", "grossTotal"],
    idempotency_key="invoice-2026-0007",
)
print(result["requestId"], result["objects"])

The core methods accept bytes, bytearray, memoryview, pathlib.Path, or binary file objects. AsyncScanverion exposes the same resource groups and uses an injected async transport or asyncio.to_thread with the default transport.

from scanverion import AsyncScanverion

async with AsyncScanverion(
    api_key=os.environ["SCANVERION_API_KEY"],
    base_url=os.getenv("SCANVERION_API_URL", "https://api.scanverion.com"),
) as client:
    summary = await client.usage.summary(from_date="2026-07-01", to_date="2026-07-31")

API keys are server-side credentials. Do not put them in browser code, mobile binaries, logs, or public fixtures. Processing POST retries happen only when an idempotency key is supplied; safe GET resources may retry transient failures.

Face comparison

The current workspace adds client.faces.compare and its async equivalent. These additions are not in the published PyPI package yet; install from this repository for local use.

from scanverion import FaceComparisonInput

comparison = client.faces.compare(
    FaceComparisonInput(image=Path("reference.jpg")),
    FaceComparisonInput(artifact_id="workspace-portrait-id"),
    policy="balanced",
    idempotency_key="face-comparison-001",
)
print(comparison["similarity"], comparison["decision"], comparison["reviewRequired"])

For an AsyncScanverion instance, use await client.faces.compare(...). Supply exactly one JPEG/PNG image or same-workspace portrait artifact per side, with a 10 MB image limit. Byte inputs need an explicit content_type. Responses include face bounds and landmarks; similarity is not identity proof or liveness. Successful requests use the configured face credit price. Validation and provider failures are uncharged, and face requests never retry automatically. Investigate uncertain completion before resubmitting.

Local validation

From the scanverion directory:

python -m unittest discover -s packages/sdk-python/tests -v
python -m compileall packages/sdk-python/src