Destroy the identity data. Keep the document.

A 200 means processed — the warnings say what was protected

Everything the detection finds is destroyed. What it did not find is reported, never hidden: every response carries a warnings array and a findings object, always present, empty when coverage is complete.

findings maps detector names to match counts — for example {"NETHERLANDS_BSN_NUMBER": 1, "MRZ_TD3_LINE_2": 1}. Detected values are never returned, logged, or stored.

Authentication & limits

Every request needs a bearer API key, provisioned by the IDBird team. Revocation is effective on the very next request.

Authorization: Bearer idb_…

• Rate limit — 30 requests/minute per key by default. Exceeding it returns 429 rate_limited with a Retry-After header: back off and retry.
• Daily allowance — each key has a daily budget of API calls, counted per UTC day. One fully-processed request is one call — a multi-page PDF still counts once. Exhausted budgets return 429 daily_quota_exceeded; its Retry-After points at the next UTC midnight. Rejected and failed requests are never billed. New keys start with a modest allowance — ask to have it raised.

Multipart form upload. Returns the redacted document as base64-encoded PNG inside a JSON envelope.

Request fields

Example

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

Response — single page

{
  "image": "<base64 PNG>",
  "warnings": ["document_number_not_redacted"],
  "findings": {
    "MRZ_TD3_LINE_1": 1,
    "MRZ_TD3_LINE_2": 1,
    "NETHERLANDS_PASSPORT": 1,
    "OBJECT_TYPE/PERSON/FACE": 2,
    "OBJECT_TYPE/PERSON/SIGNATURE": 1
  }
}

image is always the most-redacted artifact of the request.

Response — multi-page PDF

Multi-page PDFs return a pages array instead of the flat image, with aggregate warnings and findings at the top level:

{
  "pages": [
    { "page": 1, "image": "<base64 PNG>", "findings": { … } },
    { "page": 2, "image": "<base64 PNG>", "findings": { … } }
  ],
  "warnings": [],
  "findings": { … }
}

Same inputs, same detection — but returns only the detected information types with match counts. No image, never any values. Use it as a dry run: empty findings tells you a redaction of this document would find nothing. Billed and rate-limited like a redaction.

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

Multi-page PDFs add a per-page pages findings array.

Photo redaction modes

The portrait is redacted by default; redact_photo changes that per request. The MRZ, personal identification numbers and the signature are destroyed in every returned copy regardless of mode.

Document number redaction

The document's own number (passport or ID-card number) printed in the visual zone is kept by default — it is typically needed by the receiving party. redact_documentnumber changes that per request. Personal identification numbers (BSN, NIR, DNI, PESEL, CPR, …) are always destroyed, and the MRZ — which also encodes the document number — is always fully destroyed regardless of this flag.

For BE and DE the only country-specific detectors are document-number detectors, so default requests there protect the MRZ, portrait and signature.

Warnings

Always present. An empty array means full expected coverage.

Errors

One envelope for every error, with a stable machine-readable code and a static message. On any backend failure, no image is ever returned.

{ "error": { "code": "…", "message": "…" } }

Country support

Input requirements

• Formats — JPEG, PNG, BMP, or PDF up to 5 pages (not password-protected). Each PDF page is processed individually.
• Size — 10 MiB maximum upload.
• Orientation — sideways or upside-down scans are corrected automatically when the orientation can be determined reliably; metadata is not trusted.
• Quality — sharp, well-lit, uncropped documents detect best. Very large photos are downscaled before processing; extremely noisy input surfaces as mrz_not_found or nothing_detected warnings.
• Expect roughly 2–8 seconds per page end-to-end; set client timeouts of 30 s or more for multi-page PDFs.