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.
`photo_redaction`	nee	redact (standaard) verwijdert de pasfoto. keep laat hem zichtbaar en voegt de warning photo_not_redacted toe. both geeft twee afbeeldingen terug: volledig geredigeerd én met zichtbare foto.

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 — photo_redaction=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 acht mogelijke codes:

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`	`photo_redaction_invalid`	The photo_redaction field must be one of: redact, keep, both.
`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

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