API<REFERENCE<V1<<<<<<<<<<<<

API-referentie

De IDBird Redaction API is bewust klein: twee endpoints, één request-vorm, één foutenvelop. Deze pagina is het volledige oppervlak. De machineleesbare specificatie en interactieve referentie staan op api.idbird.eu.

Base-URL & authenticatie

Elk verzoek draagt een bearer-API-key, uitgegeven door het IDBird-team. Keys worden alleen als SHA-256-hash opgeslagen en bij elk verzoek live gecontroleerd — intrekking geldt vanaf het eerstvolgende verzoek.

https://api.idbird.eu
Authorization: Bearer idb_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Endpoints

`POST`	`/v1/redact`	Redigeer een document en ontvang de geschoonde afbeelding plus findings en warnings.
`POST`	`/v1/inspect`	Proefronde: alleen findings en warnings — er wordt nooit een afbeelding teruggegeven.
`GET`	`/up`	Healthcheck, zonder authenticatie.

Request

Beide endpoints accepteren hetzelfde multipart/form-data-verzoek.

Veld	Verplicht	Omschrijving
`document`	ja	Het bestand: JPEG, PNG, BMP of PDF (standaard tot 5 pagina's), max 10 MiB. Het type wordt uit de bestandsinhoud afgeleid — bestandsnaam en Content-Type-header worden genegeerd.
`country_hint`	nee	ISO 3166-1 alpha-2-code van het land van uitgifte, niet hoofdlettergevoelig (EL geldt als alias voor GR). Weglaten = automatische modus — met hint is de detectie scherper.
`redact_photo`	nee	true (standaard) verwijdert de pasfoto. false laat hem zichtbaar en voegt de warning photo_not_redacted toe. both geeft twee afbeeldingen terug: volledig geredigeerd én met zichtbare foto.
`redact_documentnumber`	nee	false (standaard) laat het documentnummer zelf leesbaar en voegt de warning document_number_not_redacted toe wanneer er een wordt gedetecteerd. true vernietigt het. Nationale nummers en de MRZ worden altijd vernietigd.

curl https://api.idbird.eu/v1/redact \
  -H "Authorization: Bearer idb_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -F document=@passport-scan.jpg \
  -F country_hint=NL

Responses

Het veld image is altijd een base64-gecodeerde PNG en altijd het meest geredigeerde resultaat van het verzoek. findings bevat detectornamen en aantallen — nooit waarden. warnings en findings zijn altijd aanwezig, leeg als er niets te melden is.

POST /v1/redact — één pagina

{
  "image": "iVBORw0KGgoAAAANSUhEUgAA…",
  "warnings": [],
  "findings": {
    "MRZ_TD3_LINE_1": 1,
    "MRZ_TD3_LINE_2": 1,
    "NETHERLANDS_PASSPORT": 1,
    "OBJECT_TYPE/PERSON/FACE": 2,
    "OBJECT_TYPE/PERSON/SIGNATURE": 1
  }
}

POST /v1/redact — redact_photo=both

{
  "image": "…fully redacted PNG…",
  "image_photo_visible": "…portrait intact, everything else redacted…",
  "warnings": [],
  "findings": {
    "MRZ_TD3_LINE_2": 1,
    "NETHERLANDS_BSN_NUMBER": 1
  }
}

POST /v1/redact — meerpagina-PDF (pages vervangt image, telt vanaf 1)

{
  "pages": [
    { "page": 1, "image": "iVBORw0KGgo…", "findings": { "OBJECT_TYPE/PERSON/FACE": 1 } },
    { "page": 2, "image": "iVBORw0KGgo…", "findings": { "MRZ_TD3_LINE_2": 1, "NETHERLANDS_BSN_NUMBER": 1 } }
  ],
  "warnings": [],
  "findings": {
    "MRZ_TD3_LINE_2": 1,
    "NETHERLANDS_BSN_NUMBER": 1,
    "OBJECT_TYPE/PERSON/FACE": 1
  }
}

POST /v1/inspect — alleen findings, nooit een afbeelding

{
  "findings": {
    "NETHERLANDS_BSN_NUMBER": 1,
    "MRZ_TD3_LINE_2": 1
  },
  "warnings": ["no_country_hint"]
}

Warning-codes

HTTP 200 betekent verwerkt, niet beschermd. Warnings verschijnen in een vaste, gedocumenteerde volgorde; controleer ze vóór het archiveren. De negen mogelijke codes:

nothing_detected: Er is niets herkenbaars gevonden; de afbeelding wordt ongewijzigd teruggegeven. Archiveer haar niet als geredigeerd zonder controle.
no_country_hint: De detectie van nationale nummers draaide in automatische modus. Geef country_hint mee voor scherpere detectie.
country_detectors_unavailable: Voor het opgegeven land bestaat geen landspecifieke nummerdetectie; alleen redactie op MRZ-niveau. Het gedrukte nationale nummer kan zichtbaar blijven — controleer.
country_detector_no_match: De landdetectoren draaiden, maar er is geen nationaal nummer gevonden. Staat het zichtbaar op het document, dan kan het zijn blijven staan — controleer.
mrz_not_found: Geen machineleesbare zone gevonden — afwezig aan deze zijde, afgesneden of onleesbaar. Normaal voor de voorzijde van ID-kaarten.
missing_face_finding: Geen pasfoto gedetecteerd. Meestal in orde voor pagina's met alleen tekst.
missing_signature_finding: Geen handtekening gedetecteerd. Meestal in orde voor pagina's zonder handtekening.
photo_not_redacted: Er is om redact_photo=false gevraagd: de teruggegeven kopie houdt de pasfoto zichtbaar. Behandel haar daarnaar.
document_number_not_redacted: Er is een documentnummer gedetecteerd en zichtbaar gelaten — de standaard. Stuur redact_documentnumber=true als het vernietigd moet worden.

Fouten

Alle fouten gebruiken één envelop met een stabiele code en een statische Engelstalige melding — veilig om op te matchen, vrij van documentinhoud:

{
  "error": {
    "code": "country_not_supported",
    "message": "The issuing country \"US\" is not supported by this service."
  }
}

HTTP	code	message
`401`	`invalid_api_key`	The bearer API key is missing, unknown, or revoked.
`404`	`not_found`	Not found.
`405`	`method_not_allowed`	Method not allowed.
`413`	`payload_too_large`	The document exceeds the 10 MiB limit.
`415`	`unsupported_media_type`	The document must be a JPEG, PNG, BMP or PDF; the type is detected from file content.
`422`	`country_hint_invalid`	The country_hint must be a two-letter ISO 3166-1 alpha-2 code.
`422`	`country_not_supported`	The issuing country "US" is not supported by this service.
`422`	`file_required`	The document file is required.
`422`	`redact_photo_invalid`	The redact_photo field must be one of: true, false, both.
`422`	`redact_documentnumber_invalid`	The redact_documentnumber field must be one of: true, false.
`422`	`too_many_pages`	The PDF exceeds the 5-page limit; split it and submit the pages separately.
`422`	`pdf_encrypted`	Encrypted PDFs are not supported.
`422`	`unreadable_image`	The document could not be decoded as an image.
`422`	`image_normalization_failed`	The image could not be reduced to the redaction backend request budget without degrading below the quality floor.
`429`	`rate_limited`	Too many requests; retry later.
`429`	`daily_quota_exceeded`	The daily allowance of 50 API call(s) for this key is exhausted for today (UTC).
`500`	`internal_error`	Internal error.
`502`	`dlp_unavailable`	The redaction backend is unavailable; no image was produced.

Limieten & facturering

Rate-limit: 30 verzoeken per minuut per key; 429 met Retry-After-header bij overschrijding.
Daglimiet: standaard 50 aanroepen per key per dag (UTC); per key verhoogd door het IDBird-team, met onmiddellijke ingang.
Eén volledig verwerkt verzoek is één factureerbare aanroep — meerpagina-PDF inbegrepen. Afgewezen (4xx) en mislukte (5xx) verzoeken worden nooit gefactureerd, en de limiet wordt vóór verwerking gecontroleerd: een verzoek boven de limiet kost niets.

Landendekking

Nationaal nummer + MRZ + foto + handtekening

NL Nederland
DE Duitsland
FR Frankrijk
ES Spanje
AT Oostenrijk
BE België
HR Kroatië
CZ Tsjechië
DK Denemarken
FI Finland
IE Ierland
IT Italië
PL Polen
PT Portugal
SE Zweden

Voor België en Duitsland richten de landspecifieke detectoren zich op het documentnummer, dat standaard leesbaar blijft — stuur redact_documentnumber=true om het te vernietigen. MRZ, foto en handtekening worden altijd gedekt.

MRZ + foto + handtekening

BG Bulgarije
CY Cyprus
EE Estland
GR Griekenland
HU Hongarije
LV Letland
LT Litouwen
LU Luxemburg
MT Malta
RO Roemenië
SK Slowakije
SI Slovenië

Documenten uit elk ander land van uitgifte worden geweigerd — nooit stilzwijgend half geredigeerd.

Machineleesbare documentatie

De OpenAPI 3.1-specificatie is met een CI-test aan de implementatie vastgepind: elke reason-code en warning die de dienst kan geven móét gedocumenteerd zijn, en niets meer. De documentatie kan niet wegdrijven.

Interactieve referentie (Redoc) openapi.yaml llms-full.txt