Full integration guide

curl --request POST "$SCANVERION_API_URL/api/v1/ai/document-processing"   --header "Authorization: Bearer $SCANVERION_API_KEY" \
  --header "Idempotency-Key: invoice-20260807-001"   --form "File=@invoice.pdf;type=application/pdf"   --form "Operations=Scanner" \
  --form "Operations=Rotation"   --form "ScannerFields=invoiceNumber"   --form "ScannerFields=issueDate"   --form "ScannerFields=dueDate"   --form "ScannerFields=paymentReference"   --form "ScannerFields=supplierIban"   --form "ScannerFields=customerIban"   --form "ScannerFields=supplierAddress"   --form "ScannerFields=supplierStreetName"   --form "ScannerFields=supplierStreetNumber"   --form "ScannerFields=supplierPostalCode"   --form "ScannerFields=supplierCity"   --form "ScannerFields=customerAddress"   --form "ScannerFields=supplierVatNumber"   --form "ScannerFields=customerVatNumber"   --form "ScannerFields=netTotal"   --form "ScannerFields=vatTotal"   --form "ScannerFields=vatBreakdown"   --form "ScannerFields=lineItems"   --form "ScannerFields=grossTotal"

curl --request POST "$SCANVERION_API_URL/api/v1/ai/document-processing/batches" \
  --header "Authorization: Bearer $SCANVERION_API_KEY" \
  --header "Idempotency-Key: onboarding-batch-42" \
  --form "Files=@front.jpg;type=image/jpeg" \
  --form "Files=@back.jpg;type=image/jpeg" \
  --form "Operations=Scanner"

curl --request POST "$SCANVERION_API_URL/api/v1/signature-comparisons" \
  --header "Authorization: Bearer $SCANVERION_API_KEY" \
  --header "Idempotency-Key: signature-comparison-001" \
  --form "Candidate=@candidate.png;type=image/png" \
  --form "References=@reference-1.png;type=image/png" \
  --form "References=@reference-2.png;type=image/png" \
  --form "References=@reference-3.png;type=image/png" \
  --form "Mode=balanced"

{
  "requestId": "3be5d51e33d64c7699954e3e9f07ea54",
  "isSimilar": true,
  "result": "Similar",
  "mode": "balanced",
  "metric": "cosine-distance",
  "rawDistance": 0.027,
  "threshold": 0.045,
  "referenceCount": 3,
  "warnings": [],
  "credits": 1.0
}

curl --request POST "$SCANVERION_API_URL/api/v1/face-comparisons" \
  --header "Authorization: Bearer $SCANVERION_API_KEY" \
  --header "Idempotency-Key: face-comparison-001" \
  --form "ReferenceImage=@reference.jpg;type=image/jpeg" \
  --form "CandidateImage=@candidate.png;type=image/png" \
  --form "Policy=balanced"

{
  "requestId": "face-comparison-001",
  "decision": "ManualReview",
  "similarity": 88.4,
  "policy": "balanced",
  "reviewRequired": true,
  "reasons": [
    "multiple_eligible_faces_best_pair"
  ],
  "providerModel": "model-version",
  "credits": 2,
  "referenceFace": {
    "bounds": {
      "left": 0.12,
      "top": 0.18,
      "width": 0.4,
      "height": 0.5
    },
    "landmarks": [
      {
        "type": "eyeLeft",
        "x": 0.24,
        "y": 0.33
      }
    ]
  },
  "candidateFace": {
    "bounds": {
      "left": 0.2,
      "top": 0.12,
      "width": 0.38,
      "height": 0.48
    },
    "landmarks": [
      {
        "type": "eyeLeft",
        "x": 0.3,
        "y": 0.27
      }
    ]
  }
}

import { readFile } from "node:fs/promises";
import { randomUUID } from "node:crypto";
import { Scanverion } from "@scanverion/sdk";

const client = new Scanverion({
  apiKey: process.env.SCANVERION_API_KEY ?? "",
  baseUrl: "https://api.scanverion.com",
});
const result = await client.faces.compare({
  reference: { image: await readFile("reference.jpg"), contentType: "image/jpeg" },
  candidate: { artifactId: "workspace-portrait-id" },
  idempotencyKey: randomUUID(),
});

import os
from pathlib import Path
from uuid import uuid4
from scanverion import Scanverion, FaceComparisonInput

client = Scanverion(api_key=os.environ["SCANVERION_API_KEY"],
                    base_url="https://api.scanverion.com")

result = client.faces.compare(
    FaceComparisonInput(image=Path("reference.jpg")),
    FaceComparisonInput(artifact_id="workspace-portrait-id"),
    idempotency_key=str(uuid4()),
)

using Scanverion;

using var client = new ScanverionClient(
    Environment.GetEnvironmentVariable("SCANVERION_API_KEY")!,
    baseUri: new Uri("https://api.scanverion.com"));
await using var reference = File.OpenRead("reference.jpg");
var result = await client.Faces.CompareAsync(
    new FaceComparisonInput(reference, "reference.jpg", "image/jpeg"),
    new FaceComparisonInput(ArtifactId: "workspace-portrait-id"),
    Guid.NewGuid().ToString());

scanverion face compare reference.jpg candidate.png --idempotency-key face-comparison-001 --output json

{
  "reference": { "imageBase64": "<JPEG base64>", "fileName": "reference.jpg", "contentType": "image/jpeg" },
  "candidate": { "imageBase64": "<PNG base64>", "fileName": "candidate.png", "contentType": "image/png" },
  "policy": "balanced",
  "idempotencyKey": "face-comparison-001"
}

export SCANVERION_TEMPLATE_URL="https://api.scanverion.com/api/v1/identity-templates"

curl --request POST "$SCANVERION_TEMPLATE_URL/workspace" \
  --header "Authorization: Bearer $SCANVERION_WORKSPACE_TOKEN" \
  --header "Idempotency-Key: template-enroll-person-001" \
  --form "ProcessingAuthorized=true" \
  --form "Images=@portrait.jpg;type=image/jpeg"

{
  "templateToken": "<signed template token>",
  "expiresAt": "<ISO 8601 expiry>",
  "searchIndex": {
    "formatVersion": "identity-template-search-v2",
    "compatibilityVersion": "<returned representation version>",
    "dimensions": 128,
    "encoding": "float32-le-base64",
    "metric": "cosine",
    "aggregationVersion": "normalized-weighted-centroid-cosine-v1",
    "selectionVersion": "<returned selection version>",
    "vector": "<Base64 float32 vector>"
  }
}

function decodeSearchVector(index: {
  formatVersion: string; dimensions: number; encoding: string;
  metric: string; aggregationVersion: string; vector: string;
}): number[] {
  if (index.formatVersion !== "identity-template-search-v2" ||
      index.dimensions !== 128 || index.encoding !== "float32-le-base64" ||
      index.metric !== "cosine" ||
      index.aggregationVersion !== "normalized-weighted-centroid-cosine-v1")
    throw new Error("Unsupported search index");
  if (index.vector.length !== 684) throw new Error("Invalid vector size");
  const bytes = Buffer.from(index.vector, "base64");
  try {
    if (bytes.length !== 512 || bytes.toString("base64") !== index.vector)
      throw new Error("Invalid vector encoding");
    const vector: number[] = [];
    for (let position = 0; position < 128; position++)
      vector.push(bytes.readFloatLE(position * 4));
    const norm = vector.reduce((sum, value) => sum + value * value, 0);
    if (!vector.every(Number.isFinite) || Math.abs(norm - 1) > 0.001)
      throw new Error("Invalid normalized vector");
    return vector;
  } finally { bytes.fill(0); }
}

CREATE EXTENSION IF NOT EXISTS vector;
CREATE TABLE person_face_template (
  workspace_id uuid NOT NULL,
  person_id uuid NOT NULL,
  template_token text NOT NULL,
  expires_at timestamptz NOT NULL,
  compatibility_version text NOT NULL,
  selection_version text NOT NULL,
  aggregation_version text NOT NULL,
  face_vector vector(128) NOT NULL,
  PRIMARY KEY (workspace_id, person_id)
);
CREATE INDEX person_face_template_cosine
  ON person_face_template USING hnsw (face_vector vector_cosine_ops);

SELECT person_id, 1 - (face_vector <=> $1::vector) AS similarity
FROM person_face_template
WHERE workspace_id = $2::uuid
  AND compatibility_version = $3
  AND selection_version = $4
  AND aggregation_version = $5
  AND expires_at > now()
ORDER BY face_vector <=> $1::vector
LIMIT 10;

curl --request POST "$SCANVERION_TEMPLATE_URL/workspace/comparisons" \
  --header "Authorization: Bearer $SCANVERION_WORKSPACE_TOKEN" \
  --header "Idempotency-Key: template-compare-001" \
  --form "ProcessingAuthorized=true" \
  --form-string "ReferenceTemplate=$REFERENCE_TEMPLATE_TOKEN" \
  --form-string "CandidateTemplate=$PROBE_TEMPLATE_TOKEN"

{
  "requestId": "7f6a7b7f0ad74729a4c4d13fa7dc6dd4",
  "model": "Document",
  "processingTimeMs": 412,
  "objects": [{
    "objectId": "document-1",
    "category": "Invoice",
    "confidence": 1,
    "bounds": { "left": 0, "top": 0, "right": 1, "bottom": 1 },
    "results": {
      "scanner": {
        "fields": {
          "invoiceNumber": "2026-0007",
          "issueDate": "2026-08-07",
          "dueDate": "2026-08-21",
          "paymentReference": "26000006",
          "supplierIban": "SK5511000000002628210731",
          "customerIban": null,
          "supplierName": "Scanverion s. r. o.",
          "supplierAddress": "Pribinova 10, 811 09 Bratislava",
          "supplierStreetName": "Pribinova",
          "supplierStreetNumber": "10",
          "supplierPostalCode": "81109",
          "supplierCity": "Bratislava",
          "supplierVatNumber": "SK2120720041",
          "customerName": "Example Customer s. r. o.",
          "customerAddress": "Main Street 12, 040 01 Kosice",
          "customerVatNumber": "SK2020123456",
          "netTotal": "19.29",
          "vatTotal": "4.44",
          "vatBreakdown": "[{"rate":"23","amount":"4.44"}]",
          "lineItems": "[{"description":"Monthly subscription","quantity":"1","unit":"pcs","unitPrice":"19.29","netAmount":"19.29","vatRate":"23","vatAmount":"4.44","grossAmount":"23.73"}]",
          "grossTotal": "23.73",
          "currency": "EUR"
        },
        "issuingCountry": null,
        "detectedLanguages": [{ "code": "sk", "confidence": 0.97 }]
      },
      "rotation": { "degrees": 0 }
    },
    "pageNumber": 1
  }],
  "operations": [
    { "operation": "Detection", "status": "Completed", "message": null },
    { "operation": "Scanner", "status": "Completed", "message": null },
    { "operation": "Rotation", "status": "Completed", "message": null }
  ],
  "usage": {
    "units": 3,
    "unitsByOperation": { "Detection": 1, "Scanner": 1, "Rotation": 1 }
  }
}

curl --request POST "$SCANVERION_API_URL/api/v1/validation/id-cards/lost-or-stolen" \
  --header "Authorization: Bearer $SCANVERION_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "cardNumber": "AA123456", "cardType": "nationalId" }'