Document Verification API: Developer Integration Guide

A document verification API is a programmatic interface that lets developers submit identity documents, invoices, certificates or proof-of-address files and receive structured verification results -- authenticity checks, data extraction, fraud signals -- without building the underlying AI models themselves. CheckFile's REST API processes a single document in 4.2 seconds on average, returns 98.7% OCR accuracy across 24 languages, and handles 3,200+ document types across 32 jurisdictions.

PIPEDA and provincial privacy legislation require organizations using automated systems for identity document verification to maintain appropriate safeguards for personal information, including technical documentation and human oversight capabilities. Any API you integrate must satisfy these obligations -- or you inherit the compliance gap.

This guide covers authentication, core endpoints, webhook configuration, error handling, SDK options, and pricing. It is written for backend engineers, DevOps teams and technical leads evaluating document verification APIs for production integration.

This article is for informational purposes only and does not constitute legal, financial, or regulatory advice.

Authentication and Security

The CheckFile API uses OAuth 2.0 client credentials for machine-to-machine authentication, following RFC 6749, Section 4.4. You exchange your client_id and client_secret for a short-lived bearer token (60-minute expiry), then include that token in the Authorization header of every subsequent request.

All API traffic is encrypted with TLS 1.3. Document payloads are encrypted at rest using AES-256, and PII is automatically redacted from logs, satisfying PIPEDA requirements for appropriate technical measures.

 # Obtain access token
curl -X POST https://api.checkfile.ai/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=YOUR_ID&client_secret=YOUR_SECRET"

 # Response
{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Key security features:

• IP allowlisting -- restrict API access to known server IPs
• Rate limiting -- configurable per plan (see pricing section)
• Webhook signatures -- HMAC-SHA256 verification on every callback
• Audit log -- every API call is logged with timestamp, client ID, document type, and result

Scopes and Permissions

Core API Endpoints

The API follows RESTful conventions with JSON payloads. Base URL: https://api.checkfile.ai/v1.

Document Submission

POST /v1/documents/verify
Content-Type: multipart/form-data
Authorization: Bearer {token}

 # Fields:
 # file (required) -- document image or PDF (max 20 MB)
 # document_type (optional) -- "passport", "id_card", "invoice", "proof_of_address"
 # country (optional) -- ISO 3166-1 alpha-2 code
 # webhook_url (optional) -- callback URL for async results
 # reference_id (optional) -- your internal reference for correlation

Response (HTTP 202 Accepted):

{
  "document_id": "doc_8f3a2b1c",
  "status": "processing",
  "estimated_completion_seconds": 4,
  "created_at": "2026-03-19T10:15:00Z"
}

When document_type is omitted, the API uses its AI classification engine -- which achieves 96.1% classification accuracy on our benchmark of 3,200+ document types -- to detect the type automatically.

Retrieve Results

GET /v1/documents/{document_id}
Authorization: Bearer {token}

Response (HTTP 200):

{
  "document_id": "doc_8f3a2b1c",
  "status": "completed",
  "document_type": "passport",
  "country": "CA",
  "verification": {
    "authentic": true,
    "confidence": 0.97,
    "fraud_signals": [],
    "checks": {
      "mrz_valid": true,
      "photo_tamper": false,
      "expiry_valid": true,
      "data_consistency": true
    }
  },
  "extracted_data": {
    "full_name": "Jane Smith",
    "date_of_birth": "1990-05-12",
    "document_number": "GA123456",
    "expiry_date": "2031-05-11",
    "nationality": "CAN"
  },
  "processing_time_ms": 3840,
  "created_at": "2026-03-19T10:15:00Z",
  "completed_at": "2026-03-19T10:15:03.840Z"
}

Batch Verification

For high-volume integrations, the batch endpoint accepts up to 50 documents per request:

POST /v1/documents/verify/batch
Content-Type: multipart/form-data
Authorization: Bearer {token}

 # files[] -- array of document files
 # options -- JSON object with shared settings

Batch requests return a batch_id and deliver results via webhook as each document completes.

Webhook Configuration

Event-driven architectures avoid polling overhead. Register a webhook endpoint to receive real-time notifications when verifications complete.

POST /v1/webhooks
Authorization: Bearer {token}
Content-Type: application/json

{
  "url": "https://your-app.com/webhooks/checkfile",
  "events": ["document.completed", "document.failed", "document.review_required"],
  "secret": "whsec_your_secret_key"
}

Every webhook delivery includes an X-CheckFile-Signature header containing an HMAC-SHA256 hash of the payload. Verify it before processing:

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Webhook retry policy: 3 attempts with exponential backoff (5s, 30s, 300s). After 3 failures, the webhook is disabled and your team receives an email alert.

SDK and Integration Options

While the REST API works from any language, official SDKs reduce integration time from days to hours.

Available SDKs

Python Integration Example

from checkfile import CheckFileClient

client = CheckFileClient(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET"
)

 # Synchronous verification
result = client.documents.verify(
    file=open("passport.pdf", "rb"),
    document_type="passport",
    country="CA"
)

print(f"Authentic: {result.verification.authentic}")
print(f"Name: {result.extracted_data.full_name}")
print(f"Processing time: {result.processing_time_ms}ms")

Node.js Integration Example

import { CheckFileClient } from '@checkfile/sdk';
import { readFileSync } from 'fs';

const client = new CheckFileClient({
  clientId: process.env.CHECKFILE_CLIENT_ID,
  clientSecret: process.env.CHECKFILE_CLIENT_SECRET,
});

const result = await client.documents.verify({
  file: readFileSync('passport.pdf'),
  documentType: 'passport',
  country: 'CA',
});

console.log(`Authentic: ${result.verification.authentic}`);
console.log(`Confidence: ${result.verification.confidence}`);

SDKs handle token refresh, retries with exponential backoff, and webhook signature verification automatically. Our analysis shows that SDK-based integrations reduce median time-to-production from 8 days (raw REST) to 2 days.

Error Handling and Rate Limits

The API uses standard HTTP status codes with structured error bodies.

Common Error Codes

Rate Limits by Plan

Compliance and Data Handling

Document verification touches PII across multiple jurisdictions. The API is designed with compliance as a first-class concern.

PIPEDA requires organizations to use only processors providing sufficient guarantees of appropriate technical and organizational measures. CheckFile acts as a service provider, with a signed Data Processing Agreement (DPA) included in all Business and Enterprise plans.

Data handling guarantees:

• Retention: Documents are deleted after processing unless you explicitly request storage (configurable from 0 to 365 days)
• Residency: Canadian-based processing by default; US and EU regions available on Enterprise plans
• Audit trail: Every API call generates an immutable audit record with document hash, timestamp, result, and client ID
• SOC 2 Type II certification covers the API infrastructure

For integrations subject to OSFI guidance on technology and cyber risk management (Guideline B-13), CheckFile provides the required third-party assurance documentation, business continuity testing results, and exit strategy terms.

Pricing Structure

CheckFile uses a per-document pricing model with volume discounts. All plans include full API access, webhooks, and audit logs.

See the full pricing page for details on volume tiers, annual billing discounts, and Enterprise SLA terms.

Our platform analysis shows that organizations switching from manual document checks to API-based verification reduce cost per dossier by 67% and processing time by 83%.

Getting Started

Integration follows four steps:

1. Create an account at checkfile.ai and generate API credentials from the dashboard
2. Test in sandbox -- the sandbox environment mirrors production with synthetic documents (no billing)
3. Integrate using the SDK or direct REST calls, starting with the synchronous pattern
4. Go live -- switch to production credentials and configure webhooks

The API documentation includes an interactive playground for testing endpoints, and the pricing page details plan options for your expected volume.

For teams building automated document verification workflows, the API integrates directly with the patterns described in our workflow setup guide.

Frequently Asked Questions

What document types does the API support?

The CheckFile API supports 3,200+ document types across 32 jurisdictions, including Canadian passports, provincial driver's licences, invoices, bank statements, proof of address, T4 slips, pay stubs, and corporate registration documents. The AI classification engine identifies document types automatically with 96.1% accuracy when the document_type parameter is omitted.

How long does verification take?

Average processing time is 4.2 seconds per document. P95 latency is under 12 seconds for standard document types. Batch submissions process documents in parallel, so a 50-document batch typically completes within 30-60 seconds depending on document complexity.

Is the API PIPEDA-compliant?

Yes. CheckFile acts as a service provider under PIPEDA with signed DPAs, Canadian-based processing infrastructure, configurable data retention (0-365 days), and automatic PII redaction from logs. SOC 2 Type II and ISO 27001 certifications cover the API infrastructure.

Can I test the API before committing to a paid plan?

The Starter plan includes 100 free verifications per month, and the sandbox environment allows unlimited testing with synthetic documents at no cost. No credit card is required to start.

What happens if the API cannot verify a document?

Documents that fall below the confidence threshold are flagged with review_required status and routed to your human review queue via webhook. The response includes the partial result with the confidence score, extracted data, and specific fraud signals that triggered the flag. This ensures no document falls through the cracks.

---

The information presented in this article is provided for informational purposes only and does not constitute legal, financial, or regulatory advice. Regulatory obligations vary by province and territory. Consult a legal professional for analysis specific to your situation.