Document Verification API: A Developer's Guide to Building Fraud-Resistant Workflows

There are two primary patterns for document verification API integration:

• Synchronous (inline): The document is submitted and the verdict is returned in the same API call. Simple to implement, appropriate for low-volume flows where 3-second processing time is acceptable within the request timeout. Best for: admin review tools, one-at-a-time verification flows.
• Asynchronous (webhook): The document is submitted, a job ID is returned immediately, and the result is delivered via webhook when processing completes. Best for: high-volume onboarding, mobile apps, and any flow where you don't want to hold open an HTTP connection.

Document verification APIs handle sensitive data. Authentication best practices for production integrations:

• Store API keys in environment variables, never in source code or client-side bundles
• Create separate API keys per environment (development, staging, production)
• Rotate keys on a schedule or after any suspected compromise
• Use per-key rate limits to prevent runaway costs if a key is exposed

For multi-tenant platforms, consider creating a separate API key per customer account so usage and costs can be attributed and audited at the customer level.

Teams with existing AI provider contracts — OpenAI, Anthropic, Google Gemini, AWS Bedrock, Azure OpenAI — can configure the document verification API to route analysis through their own credentials. This means:

• AI costs are billed directly to your provider contract, often at negotiated enterprise rates
• Documents are processed within your chosen provider's infrastructure and data residency zone
• You choose which model is used for semantic analysis

BYOK is configured as a named provider config in the dashboard. Each API key can be associated with a specific provider config, enabling different integrations to use different AI backends.

A well-structured document verification response includes three layers of signal:

• Verdict: authentic, tampered, or suspicious — the top-level decision
• Risk score: A 0–100 numeric score for use in risk-tiering decisions
• Findings: An array of specific findings with category, severity, confidence, and description — the forensic evidence behind the verdict

The findings array is what enables your team to act on the result rather than just accept it. A "tampered" verdict with a finding that says "running balance inconsistency detected across 3 rows" tells a reviewer exactly where to look.

Document processing can fail due to unreadable files, unsupported formats, or transient provider errors. Robust integrations handle these cases:

• Distinguish between client errors (400 — bad file format) and transient errors (503 — provider unavailable)
• Implement exponential backoff for transient failures
• Set a fallback policy: hold for manual review rather than blocking the user indefinitely
• Log job IDs for every submission so results can be retrieved later if a webhook is missed

Before going live with document verification in a production workflow:

• Test with a representative set of genuine documents from your expected submission pool
• Set false-positive thresholds appropriate to your risk appetite (lower threshold = more manual review, fewer fraud passes)
• Ensure your webhook endpoint is idempotent (results may be delivered more than once)
• Monitor the document_type field in results — a high rate of unknown classifications may indicate your submission flow is sending unexpected file types
• Set up alerting on error rates and processing latency