Document Verification API: A Developer's Guide to Integrating AI Document Checks

Authorization: Bearer tc_live_your_key_here

# .env
TAMPERCHECK_API_KEY=tc_live_your_key_here

import httpx
import os
 
def verify_document(file_path: str) -> dict:
    with open(file_path, "rb") as f:
        response = httpx.post(
            "https://api.tampercheck.ai/api/v1/documents/",
            headers={"Authorization": f"Bearer {os.environ['TAMPERCHECK_API_KEY']}"},
            files={"document": f},
            data={"mode": "async"},
            timeout=30,
        )
    response.raise_for_status()
    return response.json()

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "document_type": "bank_statement",
  "document_subtype": "Indian Savings Account Statement",
  "verdict": "tampered",
  "risk_score": 64,
  "confidence": 0.87,
  "findings": [
    {
      "category": "ela_anomaly",
      "severity": "high",
      "description": "Compression anomalies detected in balance field region.",
      "confidence": 0.89
    },
    {
      "category": "font_inconsistency",
      "severity": "medium",
      "description": "Closing balance character spacing is a statistical outlier.",
      "confidence": 0.72
    }
  ],
  "human_summary": "ELA analysis found compression artefacts consistent with value replacement in the closing balance region. Font metrics reinforce the signal. Manual review recommended before proceeding."
}

def route_document(result: dict, exposure: float) -> str:
    score = result["risk_score"]
    if score >= 70:
        return "reject"
    if score >= 30 or exposure > HIGH_VALUE_THRESHOLD:
        return "manual_review"
    return "approve"
 
def get_high_severity_findings(result: dict) -> list:
    return [
        f for f in result["findings"]
        if f.get("severity") == "high"
    ]

import httpx, os
 
# 1. Submit with a webhook
response = httpx.post(
    "https://api.tampercheck.ai/api/v1/documents/",
    headers={"Authorization": f"Bearer {os.environ['TAMPERCHECK_API_KEY']}"},
    files={"document": open("statement.pdf", "rb")},
    data={
        "mode": "async",
        "webhook_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    },
)
job_id = response.json()["id"]  # store this
 
# 2. Receive the webhook payload at your registered URL
# POST https://yourapp.com/webhooks/tampercheck
# Headers: X-Webhook-ID, X-Webhook-Signature
# Body: same shape as GET /api/v1/documents/<id>/

import hmac
import hashlib
 
def verify_webhook(payload: bytes, signature_header: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256,
    ).hexdigest()
    provided = signature_header.removeprefix("sha256=")
    return hmac.compare_digest(expected, provided)

import time
 
def verify_with_retry(file_path: str, max_retries: int = 3) -> dict:
    for attempt in range(max_retries):
        try:
            return verify_document(file_path)
        except httpx.HTTPStatusError as e:
            if e.response.status_code >= 500:
                time.sleep(2 ** attempt)
            else:
                raise  # don't retry client errors
    raise RuntimeError("Max retries exceeded")

import fs from "fs";
 
interface SubmitResult {
  id: string;
  status: string;
}
 
interface VerificationResult {
  id: string;
  status: string;
  verdict: "authentic" | "tampered";
  risk_score: number;
  confidence: number;
  findings: Array<{
    category: string;
    severity: "low" | "medium" | "high";
    description: string;
    confidence: number;
  }>;
  human_summary: string;
}
 
async function submitDocument(filePath: string): Promise<SubmitResult> {
  const formData = new FormData();
  formData.append("document", new Blob([fs.readFileSync(filePath)]), filePath);
  formData.append("mode", "async");
 
  const response = await fetch("https://api.tampercheck.ai/api/v1/documents/", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.TAMPERCHECK_API_KEY}`,
    },
    body: formData,
  });
 
  if (!response.ok) {
    const error = await response.json();
    throw new Error(`API error ${response.status}: ${error.detail}`);
  }
 
  return response.json();
}