Acupixel Cloud Service SDK

The Acupixel Cloud Service SDK is a comprehensive .NET library for integrating document data extraction, identity verification, and document authentication into your applications.

It enables developers to securely submit identity documents and related images (such as selfies or holographic captures) to the Acupixel Cloud, where advanced AI-driven processing extracts structured data, verifies personal identity, and authenticates document integrity.

With this SDK, you can easily:

• Extract and normalize fields from identity documents (e.g., name, date of birth, address).
• Verify a person’s identity through face matching and database checks.
• Perform full forensic and visual authentication of ID documents, including barcode, UV, and IR validation.

This SDK provides a streamlined, asynchronous API designed for high reliability, simple integration, and scalability across verification workflows.

---

📘 Overview

The Acupixel Cloud Service SDK enables developers to send identity documents and related media to the Acupixel Cloud for automated validation and data extraction.

Core components include:

• CloudManager - Initializes and configures SDK access, environments, and authorization.
• DocumentManager - Handles all document-related cloud operations.
• ProcessDocumentRequest and ProcessDocumentRequestImages - Represent input structures for processing identity documents.
• CloudResponse<T> - Wraps the structured response returned from the cloud.
• DocumentInfo, DocumentField, ForensicAuthentications, TemplateInfo - Define the rich structured data returned by document verification.

---

🧩 Architecture

Key Managers

CloudManager

The entry point for initializing and establishing a secure connection with the SDK.

Responsibilities:

• Configure environment (Sandbox / Production / Custom)
• Store the API key securely
• Maintain HttpClient instance for all requests
• Validate configuration with InitializeAsync

Initialization Example:

bool success = await CloudManager.Instance.InitializeAsync( ServiceEnvironments.Sandbox, "YOUR_API_KEY_HERE", "yyyy-MM-dd" ); if (!success) throw new Exception("Failed to authenticate SDK.");

The SDK performs a test request (/v1/UserManagement/GetUserTransactionsReport) to validate credentials and connectivity.

DocumentManager

Manages cloud-based document processing requests.
Supports multiple input formats:

• File-based (FileInfo)
• Base64-encoded strings
• Raw byte arrays

All formats map to the same endpoint:
v1/Document/ProcessDocumentFromFiles

Usage Example:

var images = new ProcessDocumentRequestImages<FileInfo> { FrontSide = new FileInfo("front.jpg"), BackSide = new FileInfo("back.jpg"), SelfieImage = new FileInfo("selfie.jpg") }; var request = new ProcessDocumentRequest { ReturnDocumentForensicAuthentications = true, PerformBarcodeInspection = true, PerformIdentityVerification = true }; var result = await DocumentManager.Instance.ProcessDocumentAsync(images, request); DocumentInfo document = result.Data;

The SDK automatically constructs a multipart form upload, validates configuration, attaches authentication headers (x-api-key), and returns a structured response.

---

⚙️ Configuration

ProcessDocumentRequest

Specifies document-processing options and output preferences such as whether to include cropped images, perform authentication, or verify against government databases.

Key Fields:

• ReturnDocumentForensicAuthentications - Full authentication to verify the authenticity of the identification document.
• ReturnFrontImage, ReturnBackImage, ReturnFaceImage - Include specific visual elements.
• PerformIdentityVerification, PerformAAMVADriverLicenseVerification - Enable deeper identity checks.
• FetchWebFields - Enrich results with online data sources.
• CheckForSelfieLiveness - Evaluate selfie authenticity.

These options let you fine-tune trade-offs between latency, cost, and depth of verification.

ProcessDocumentRequestImages<T>

Defines all possible image types the SDK can send to the cloud.
Supports visible, infrared, ultraviolet, holographic, and other capture types:

var images = new ProcessDocumentRequestImages<byte[]> { FrontSide = frontBytes, BackInfraredImage = backIRBytes, HologramsImage = hologramBytes };

CloudRequest

A base class for all request types, providing universal request metadata such as ApiKey, Environment, and TraceId for tracking requests through the system.

---

📤 Cloud Responses

CloudResponse<T>

A generic wrapper for all server responses.
Provides utilities for JSON persistence and strongly-typed deserialization.

Key Members:

• Id - Transaction ID.
• Data - Strongly-typed payload (e.g., DocumentInfo).
• SaveToJson() - Save response to a local JSON file.
• FromJson() - Reconstruct a CloudResponse from JSON.

await response.SaveToJsonAsync("response.json"); Console.WriteLine(response.Data.DocumentCountry.CountryName);

---

🧠 Data Models

DocumentInfo

Encapsulates the results of the identity document analysis - from extracted fields to forensic and biometric results.

Contains:

• DocumentType, DocumentRegion, DocumentCountry
• Fields (list of DocumentField objects)
• ForensicAuthentications and DocumentColorAuthentications
• Image fields (FrontImage, BackImage, etc.)
• Face and signature coordinates
• Validation results (address, postal code, barcode detection, MRZ, etc.)

DocumentField

Represents a specific extracted field, its raw and normalized values, bounding box, and validation state.

Console.WriteLine($"{field.Label}: {field.Text.Value}");

Each field includes type info (DocumentFieldIds), extraction source (FieldSources), and FieldValidations results.

ForensicAuthentications

Includes full audit details of forensic tests, barcode analysis, and document authenticity scoring.
Fields such as WasAuthenticationPerformed, DocumentAuthenticityScore, and DocumentAuthenticityAdditionalDescriptions quantify reliability.

TemplateInfo

Metadata about the document’s official template - such as issuing authority, circulation status, RealID status, and UV features.

AddressValidation

Represents the validation results of the address appearing on the identification document, along with breakdown details and extraction metadata.
Includes the validation status, the source of the field, and detailed address information.

AgeVerification

Provides age and date-of-birth validation results obtained by comparing extracted document data against authoritative databases.
Indicates whether the country is supported, whether a person was found, calculated age, and whether the age meets the specified limit.

CountryInfo

Contains comprehensive metadata about the issuing country of the identification document - including ISO codes, jurisdiction, and region.
This model helps identify document origin and jurisdiction hierarchy.

FieldValidations

Defines a rich set of validation checks applied to each field extracted from the document.
Covers multiple validation types, such as OCR accuracy, barcode and MRZ matches, date consistency, jurisdiction checks, and logical data integrity.

FieldValue

Represents the normalized field value, including parsed date components and character alphabet detection.
Automatically constructs a valid DateTime when applicable.

ForensicBarcodeInspection

Provides details about the barcode inspection performed on the ID document - including extracted barcode image, location, and inspection results.
Useful for assessing barcode integrity and readability.

ForensicDataInspection

Contains information about data integrity checks performed on the document’s fields, including whether the document has expired, field validations passed, and general data consistency.

IdentityVerificationMatch

Represents identity verification results comparing document data against external databases.
Includes detailed match confidence for multiple identity aspects - name, address, date of birth, SSN, driver license, and contact details.

PostalCodeValidation

Contains the validation results of postal codes extracted from the document.
Includes structured postal information, test results, and overall validation status with the source of extraction.

AAMVAVerification

Represents detailed verification results against AAMVA (American Association of Motor Vehicle Administrators) state databases.
Evaluates identity data (e.g., names, document number, dates, and demographics) for accuracy and legitimacy.

---

🧾 Example Workflow

// Initialize SDK await CloudManager.Instance.InitializeAsync(ServiceEnvironments.Production, "API_KEY"); // Create processing input var request = new ProcessDocumentRequest { PerformIdentityVerification = true, ReturnDocumentForensicAuthentications = true }; var images = new ProcessDocumentRequestImages<FileInfo> { FrontSide = new FileInfo("front.png"), BackSide = new FileInfo("back.png"), SelfieImage = new FileInfo("selfie.png") }; // Submit for cloud processing CloudResponse<DocumentInfo> response = await DocumentManager.Instance.ProcessDocumentAsync(images, request); // Work with results Console.WriteLine($"Document Type: {response.Data.DocumentType}"); Console.WriteLine($"Holder Name: {response.Data.GetFieldByKind(DocumentFieldIds.FullName)}");

---

🧰 Development Notes

• Compatible with .NET Standard 2.1, .NET 5.0+, and .NET 6.0+
• JSON serialization handled by System.Text.Json or Newtonsoft.Json (depending on target)
• All operations are asynchronous (Task-based)
• Thread-safe singleton managers (CloudManager, DocumentManager)

---

🛡️ Error Handling

Custom exception types provide detailed error contexts:

• BadRequestException
• UnauthorizedUserException
• ForbiddenException
• InternalServerErrorException

These are thrown based on HTTP status codes received from the Acupixel Cloud API.

---

🧾 License

This SDK is proprietary to Acupixel.
All rights reserved. Usage is subject to the Acupixel developer license agreement.