Scanverion.Sdk 0.1.1

Scanverion.Sdk

Dependency-free .NET client for the Scanverion OCR API. The package targets .NET 8 and .NET 10 and uses the standard HttpClient and System.Text.Json stack.

Install from NuGet

Install Scanverion.Sdk from NuGet.org in your application directory:

dotnet add package Scanverion.Sdk --version 0.1.1

Keep API credentials in your server environment.

Quickstart

Client-held identity templates

await using var portrait = File.OpenRead("portrait.png");
var template = await client.Templates.CreateAsync(
    [new IdentityTemplateImage(portrait, "portrait.png", "image/png")], true, "template-create-001");
await using var candidate = File.OpenRead("candidate.png");
var comparison = await client.Templates.CompareAsync(
    new IdentityTemplateReference(TemplateToken: template!.TemplateToken),
    new IdentityTemplateCandidate(Image: new(candidate, "candidate.png", "image/png")),
    true, "template-compare-001");

Use a configured ScanverionClient as shown below. Creation accepts 1-8 JPEG/PNG images (10 MiB each, 40 MiB combined). Compare a reference token or images against a candidate token or one image. Each operation costs 2 credits on completion, requires processing authorization and a 1-96 character idempotency key, supports cancellation, and never retries automatically. Template and search-index ToString() output is redacted. Their JSON remains sensitive biometric data; protect it as source portraits. There is no server gallery. Cosine similarity requires human review and is not identity probability or liveness.

Camera liveness

Included in release 0.1.1. Availability depends on the deployment and workspace; a working public try-out does not activate workspace API access. Check /api/v1/face-liveness/policy and workspace capabilities.

using Scanverion;

using var client = new ScanverionClient(
    Environment.GetEnvironmentVariable("SCANVERION_API_KEY")!,
    baseUri: new Uri("https://api.scanverion.com"));
var session = await client.Liveness.CreateSessionAsync(true, Guid.NewGuid().ToString());

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

var result = await client.Liveness.GetResultAsync(session!.SessionId, session.AccessToken);

Both methods accept cancellation and never automatically retry. Keep credentials and short-lived capture IDs out of logs, storage and URLs (ToString() redacts the session). Valid completed assessments are billable independently of pass/fail. Liveness is separate from face similarity and identity proof. Camera flow, IAM, expiry and activation.

Document processing

using Scanverion;

using var client = new ScanverionClient(
    Environment.GetEnvironmentVariable("SCANVERION_API_KEY")!,
    baseUri: new Uri(Environment.GetEnvironmentVariable("SCANVERION_API_URL") ?? "https://api.scanverion.com"));
await using var file = File.OpenRead("invoice.pdf");

var result = await client.Documents.ProcessAsync(
    file,
    "invoice.pdf",
    "application/pdf",
    new ProcessingOptions
    {
        Operations = ["Detection", "Scanner"],
        ScannerFields = ["invoiceNumber", "grossTotal"],
        IdempotencyKey = "invoice-2026-0007"
    });

Console.WriteLine(result?.RequestId);

Documents and Vehicles expose single-file and batch processing. Usage exposes summary, daily, capability, and price-preview queries. Catalog exposes capability metadata and capability usage. Upload methods accept caller-owned streams or byte arrays; the client does not dispose caller-owned streams.

Processing POST requests retry only when ProcessingOptions.IdempotencyKey is supplied. Safe GET resources retry transient network, timeout, 408, 429, and server failures. ScanverionApiException retains the HTTP status, structured ProblemDetails, request ID, and retryability.

API keys are server-side credentials. Do not embed them in browser code, mobile binaries, logs, or public fixtures.

Face comparison (local source)

The local SDK source adds Faces; this is not a claim that the published 0.1.0 package or hosted API already supports it. The API remains disabled by default and must have separately approved provider, evaluation, privacy, terms, and billing configuration.

Comparison responses may include ReferenceFace and CandidateFace, with normalized bounds and landmarks from the existing input detection calls. Coordinates are fractions of the source image dimensions; bounds may extend outside the image and should be clipped for display. Missing geometry must not be inferred. These optional fields do not change the similarity score, add provider calls, or establish identity or liveness.

With multiple detections, comparison ignores faces smaller than 80 by 80 pixels or 2% of image area and accepts up to four eligible faces per side. The returned geometry describes the highest-scoring eligible pair. Multiple eligible faces set ReviewRequired and the multiple_eligible_faces_best_pair reason; ignored detections add small_or_invalid_faces_ignored. The adapter uses at most four source-to-many comparisons per request. Request shape and per-request billing are unchanged; similarity is not an identity probability.

await using var reference = File.OpenRead("portrait.png");
await using var candidate = File.OpenRead("selfie.png");
var comparison = await client.Faces.CompareAsync(
    new FaceComparisonInput(reference, "portrait.png", "image/png"),
    new FaceComparisonInput(candidate, "selfie.png", "image/png"),
    idempotencyKey: "verification-2026-0001");

Either side can instead use new FaceComparisonInput(ArtifactId: "..."). Portrait artifacts are opaque, workspace-owned, and expire after 15 minutes in the current single-instance store. Supply exactly one upload or artifact per side. Uploaded streams remain caller-owned; the SDK clears its transient image buffers after sending.

The sole supported policy is balanced; the server owns its threshold. Similarity is a provider score, not an identity probability. Comparison does not establish liveness or legal identity. A missing provider score yields UnableToCompare with ReviewRequired = true.

An idempotency key of 1-128 trimmed characters is required. This method does not automatically retry, even when maxRetries is configured. Reusing a workspace key returns 409, not a cached response. Completed provider responses carry Credits; exceptions release the reservation. Invalid-input or unscored responses can still incur the configured completed-comparison credit because provider processing has occurred.

Local validation

From the scanverion directory:

dotnet test packages/sdk-dotnet.tests/Scanverion.Sdk.Tests.csproj
dotnet pack packages/sdk-dotnet/Scanverion.Sdk.csproj --no-restore