Documentverificatie-API: integratiegids voor ontwikkelaars

Een documentverificatie-API is een programmatische interface waarmee ontwikkelaars identiteitsdocumenten, facturen, certificaten of adresbewijzen indienen en gestructureerde verificatieresultaten ontvangen — echtheidscontroles, gegevensextractie, fraudesignalen — zonder de onderliggende AI-modellen zelf te hoeven bouwen. De CheckFile-API verwerkt een document in gemiddeld 4,2 seconden, bereikt een OCR-nauwkeurigheid van 98,7 % in 24 talen en ondersteunt meer dan 3.200 documenttypen in 32 rechtsgebieden.

De EU AI-verordening (Verordening (EU) 2024/1689, art. 6 en bijlage III) classificeert AI-systemen voor identiteitsdocumentverificatie in financiële dienstverlening als hoog risico, met de verplichting voor aanbieders om technische documentatie, een risicobeheersysteem en menselijk toezicht te onderhouden. Elke API die je integreert moet aan deze verplichtingen voldoen, anders erf je het compliancegat.

Deze gids behandelt authenticatie, kern-endpoints, webhookconfiguratie, foutafhandeling, SDK-opties en prijzen. Hij is gericht op backend-ontwikkelaars, DevOps-teams en technisch verantwoordelijken die documentverificatie-API's evalueren voor productie-integratie.

Dit artikel is uitsluitend bedoeld ter informatie en vormt geen juridisch, financieel of regelgevend advies.

Authenticatie en beveiliging

De CheckFile-API gebruikt OAuth 2.0 client credentials voor machine-naar-machine-authenticatie, conform RFC 6749, Sectie 4.4. Je wisselt je client_id en client_secret in voor een tijdelijk bearer-token (60 minuten geldig) en voegt dat token toe aan de Authorization-header van elk volgend verzoek.

Al het API-verkeer is versleuteld met TLS 1.3. Documenten worden in rust versleuteld met AES-256 en persoonsgegevens worden automatisch uit logbestanden verwijderd, in overeenstemming met artikel 32 van de AVG over passende technische maatregelen (AVG, art. 32).

 # Toegangstoken ophalen
curl -X POST https://api.checkfile.ai/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=JOUW_ID&client_secret=JOUW_SECRET"

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

Belangrijke beveiligingsfuncties:

• IP-allowlisting — API-toegang beperken tot bekende server-IP's
• Rate limiting — configureerbaar per plan (zie prijssectie)
• Webhook-handtekeningen — HMAC-SHA256-verificatie bij elke callback
• Auditlog — elke API-aanroep wordt vastgelegd met tijdstempel, client-ID, documenttype en resultaat

Scopes en machtigingen

Kern-endpoints van de API

De API volgt RESTful-conventies met JSON-payloads. Basis-URL: https://api.checkfile.ai/v1.

Documentindiening

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

 # Velden:
 # file (vereist) — documentafbeelding of PDF (max. 20 MB)
 # document_type (optioneel) — "passport", "id_card", "invoice", "proof_of_address"
 # country (optioneel) — ISO 3166-1 alfa-2-code
 # webhook_url (optioneel) — callback-URL voor asynchrone resultaten
 # reference_id (optioneel) — jouw interne referentie voor correlatie

Respons (HTTP 202 Accepted):

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

Wanneer document_type wordt weggelaten, gebruikt de API haar AI-classificatiesysteem — dat een classificatienauwkeurigheid van 96,1 % bereikt op onze benchmark van meer dan 3.200 documenttypen — om het type automatisch te detecteren.

Resultaten ophalen

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

Respons (HTTP 200):

{
  "document_id": "doc_8f3a2b1c",
  "status": "completed",
  "document_type": "identiteitskaart",
  "country": "NL",
  "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": "Jan de Vries",
    "date_of_birth": "1990-05-12",
    "document_number": "SPECI2014",
    "expiry_date": "2031-05-11",
    "nationality": "NLD"
  },
  "processing_time_ms": 3840,
  "created_at": "2026-03-19T10:15:00Z",
  "completed_at": "2026-03-19T10:15:03.840Z"
}

Het extracted_data-object bereikt een veldextractienauwkeurigheid van 94,3 % op onze interne benchmark, dekkend gestructureerde velden van alle ondersteunde documenttypen.

Batchverificatie

Voor integraties met hoog volume accepteert het batch-endpoint tot 50 documenten per verzoek:

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

 # files[] — array van documentbestanden
 # options — JSON-object met gedeelde instellingen

Batchverzoeken retourneren een batch_id en leveren resultaten via webhook naarmate elk document is verwerkt.

Webhookconfiguratie

Gebeurtenisgestuurde architecturen vermijden polling-overhead. Registreer een webhook-endpoint om realtime meldingen te ontvangen wanneer verificaties zijn afgerond.

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

{
  "url": "https://jouw-app.nl/webhooks/checkfile",
  "events": ["document.completed", "document.failed", "document.review_required"],
  "secret": "whsec_jouw_geheime_sleutel"
}

Elke webhookbezorging bevat een X-CheckFile-Signature-header met een HMAC-SHA256-hash van de payload. Verifieer deze voordat je de payload verwerkt:

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-herhalingbeleid: 3 pogingen met exponentieel backoff (5s, 30s, 300s). Na 3 mislukkingen wordt de webhook uitgeschakeld en ontvangt je team een e-mailmelding.

SDK's en integratieopties

De REST API werkt vanuit elke programmeertaal, maar officiële SDK's verkorten de integratietijd van dagen naar uren.

Beschikbare SDK's

Python-integratievoorbeeld

from checkfile import CheckFileClient

client = CheckFileClient(
    client_id="JOUW_CLIENT_ID",
    client_secret="JOUW_CLIENT_SECRET"
)

 # Synchrone verificatie
result = client.documents.verify(
    file=open("identiteitskaart.pdf", "rb"),
    document_type="id_card",
    country="NL"
)

print(f"Authentiek: {result.verification.authentic}")
print(f"Naam: {result.extracted_data.full_name}")
print(f"Verwerkingstijd: {result.processing_time_ms}ms")

Node.js-integratievoorbeeld

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('identiteitskaart.pdf'),
  documentType: 'id_card',
  country: 'NL',
});

console.log(`Authentiek: ${result.verification.authentic}`);
console.log(`Betrouwbaarheid: ${result.verification.confidence}`);

SDK's verzorgen tokenvernieuwing, herhaalpogingen met exponentieel backoff en webhook-handtekeningverificatie automatisch. Onze analyse toont dat SDK-gebaseerde integraties de mediane time-to-production verkorten van 8 dagen (ruwe REST) naar 2 dagen.

Foutafhandeling en snelheidslimieten

De API gebruikt standaard HTTP-statuscodes met gestructureerde foutbodies:

{
  "error": {
    "code": "DOCUMENT_UNREADABLE",
    "message": "Het geüploade bestand kon niet worden verwerkt. Zorg dat DPI >= 300.",
    "details": { "min_dpi": 300, "detected_dpi": 72 },
    "request_id": "req_9f2c4d1e"
  }
}

Veelvoorkomende foutcodes

Snelheidslimieten per plan

Rate-limitheaders (X-RateLimit-Remaining, X-RateLimit-Reset) worden in elke respons meegestuurd. Bouw je herhalingslogica op basis van deze headers in plaats van vaste vertragingen in te programmeren.

Compliance en gegevensverwerking

Documentverificatie raakt persoonsgegevens in meerdere rechtsgebieden. De API is ontworpen met compliance als eersteklas vereiste.

Sinds maart 2026 vereist de AVG (Verordening (EU) 2016/679, art. 28) dat verwerkingsverantwoordelijken alleen verwerkers inschakelen die voldoende garanties bieden voor passende technische en organisatorische maatregelen. CheckFile treedt op als verwerker, met een getekende verwerkersovereenkomst in alle Business- en Enterprise-plannen.

Conform de vereisten van de Wet ter voorkoming van witwassen en financieren van terrorisme (Wwft) en het toezicht door De Nederlandsche Bank (DNB) en de Autoriteit Financiële Markten (AFM) biedt de API:

• Bewaartermijn: documenten worden na verwerking verwijderd tenzij je expliciet opslag aanvraagt (configureerbaar van 0 tot 365 dagen)
• Dataresidentie: verwerking in de EU standaard; US- en APAC-regio's beschikbaar op Enterprise-plannen
• Audittrail: elke API-aanroep genereert een onveranderlijk auditrecord met documenthash, tijdstempel, resultaat en client-ID
• SOC 2 Type II-certificering voor de API-infrastructuur
• PCI DSS-conforme documentverwerking voor financiële documenten

Voor integraties onderworpen aan de DNB-richtsnoeren voor uitbesteding, levert CheckFile de vereiste derdepartijborging, resultaten van bedrijfscontinuïteitstests en exitstrategie-voorwaarden.

Prijsstructuur

CheckFile hanteert een prijsmodel per document met volumekortingen. Alle plannen omvatten volledige API-toegang, webhooks en auditlogs.

Bekijk de prijspagina voor details over volumestaffels, jaarlijkse kortingen en Enterprise-SLA-voorwaarden.

Onze platformanalyse toont dat organisaties die overstappen van handmatige documentcontrole naar API-gebaseerde verificatie de kosten per dossier met 67 % en de verwerkingstijd met 83 % verlagen. De gemiddelde terugverdientijd voor Business-klanten is minder dan 3 maanden bij verwerking van meer dan 500 documenten per maand.

Integratiearchitectuurpatronen

Patroon 1: synchroon (eenvoudig)

Voor integraties met laag volume (< 60 verzoeken/min), indienen en pollen:

Client → POST /v1/documents/verify → 202 Accepted
Client → GET /v1/documents/{id} (polling elke 2s) → 200 met resultaten

Geschikt voor onboardingflows waarbij de gebruiker wacht op verificatie.

Patroon 2: asynchroon met webhooks (aanbevolen)

Voor productie-workloads, indienen en resultaten per webhook ontvangen:

Client → POST /v1/documents/verify (met webhook_url) → 202 Accepted
CheckFile → POST webhook_url (getekende payload) → Jouw handler verwerkt het resultaat

Ontkoppelt indiening van verwerking. Schaalt lineair met het volume.

Patroon 3: batchpipeline

Voor backoffice-verwerking (nachtelijke KYC-beoordelingen, bulk-compliancecontroles):

Client → POST /v1/documents/verify/batch (tot 50 bestanden) → batch_id
CheckFile → POST webhook_url per document bij voltooiing
CheckFile → POST webhook_url met batch.completed-samenvatting

Ons platform verwerkt maandelijks meer dan 180.000 documenten met deze patronen. Het asynchrone webhookpatroon dekt 94 % van de productie-integraties.

Aan de slag

De integratie volgt vier stappen:

1. Account aanmaken bij checkfile.ai en API-referenties genereren vanuit het dashboard
2. Testen in sandbox — de sandbox-omgeving spiegelt productie met synthetische documenten (zonder facturering)
3. Integreren met de SDK of directe REST-aanroepen, beginnend met het synchrone patroon
4. Live gaan — overschakelen naar productie-referenties en webhooks configureren

De API-documentatie bevat een interactieve playground om endpoints te testen, en de prijspagina beschrijft de planopties voor je verwachte volume.

Voor teams die geautomatiseerde documentverificatie-workflows opbouwen, integreert de API direct met de patronen beschreven in onze workflowgids. Als je verificatieoplossingen breder evalueert, behandelt onze gids automatisering verificatie het volledige landschap van documentverificatiebenaderingen.

Veelgestelde vragen

Welke documenttypen ondersteunt de API?

De CheckFile-API ondersteunt meer dan 3.200 documenttypen in 32 rechtsgebieden: paspoorten, identiteitskaarten, rijbewijzen, facturen, bankafschriften, adresbewijzen, belastingaanslagen, loonstroken en KvK-uittreksels. Het AI-classificatiesysteem herkent documenttypen automatisch met 96,1 % nauwkeurigheid wanneer de document_type-parameter wordt weggelaten.

Hoe lang duurt een verificatie?

De gemiddelde verwerkingstijd is 4,2 seconden per document. De P95-latentie is minder dan 12 seconden voor standaarddocumenttypen. Batchindieningen verwerken documenten parallel — een batch van 50 documenten is doorgaans binnen 30 tot 60 seconden voltooid, afhankelijk van de documentcomplexiteit.

Is de API AVG-conform?

Ja. CheckFile treedt op als verwerker conform artikel 28 AVG met getekende verwerkersovereenkomst, verwerkingsinfrastructuur in de EU, configureerbare databewaartermijn (0 tot 365 dagen) en automatische verwijdering van persoonsgegevens uit logbestanden. SOC 2 Type II- en ISO 27001-certificeringen dekken de API-infrastructuur.

Kan ik de API testen voordat ik een betaald plan afneem?

Het Starter-plan bevat 100 gratis verificaties per maand, en de sandbox-omgeving maakt onbeperkt testen met synthetische documenten mogelijk zonder kosten. Geen creditcard vereist om te starten.

Wat gebeurt er als de API een document niet kan verifiëren?

Documenten die onder de betrouwbaarheidsdrempel vallen, worden gemarkeerd met status review_required en via webhook doorgestuurd naar je wachtrij voor menselijke beoordeling. De respons bevat het gedeeltelijke resultaat met de betrouwbaarheidsscore, geëxtraheerde gegevens en de specifieke fraudesignalen die de markering hebben geactiveerd. Zo gaat geen enkel document verloren.