API v1

Anonymize API

One endpoint. Send an ID scan, get an anonymized PDF back. Use this to integrate AnonID into your KYC flow, tenant onboarding, or mobile app.

Authentication

Every request requires an API key in the X-API-Key header. Create keys under Settings → API keys. Keys are shown once at creation and only their SHA-256 hash is stored.

Endpoint

POST /api/public/v1/anonymize

Request

• Content-Type: multipart/form-data
• file (required): the scan to anonymize. JPG, PNG or PDF. Maximum 10MB.
• fields (optional): comma-separated list of field keys to override the default profile.
• purpose (optional, 3–200 chars): free-text reason this copy is being made (e.g. "Huurcontract Prinsengracht 42"). When present, a diagonal red "KOPIE – {purpose}" watermark at 50% opacity is burned into every page of the returned PDF, and the value is persisted on the document row for your audit trail.
• extract (optional): 1/true to also return the extracted full name, date of birth and date of expiry. Equivalent to sending header X-Extract: 1. Dates are always normalized to ISO 8601 YYYY-MM-DD regardless of the source format on the document.
• format (optional): json to receive a JSON envelope instead of a raw PDF (see below). Equivalent to sending Accept: application/json.
• Rate limit: 60 requests per 5 minutes per key.

Response — PDF (default)

• 200: body is the redacted PDF (application/pdf).
• Headers always present: X-Document-Id.
• When extract=1, these headers are added:
  • X-Extracted-Full-Name (URL-encoded UTF-8)
  • X-Extracted-Date-Of-Birth (ISO YYYY-MM-DD)
  • X-Extracted-Date-Of-Expiry (ISO YYYY-MM-DD)
  • X-Anonymid-Expired (true/false, compared against today)
  • X-Anonymid-Extracted (base64-encoded JSON of all three fields, dates already ISO — canonical single header)
  • X-anonid-Extracted / X-anonid-Expired — deprecated aliases, still emitted for older clients. Prefer the X-Anonymid-* names in new code.
• Error responses (400, 401, 413, 415, 422, 429, 500, 502, 503, 504) return JSON { "error": "..." }.

Response — JSON envelope

Send format=json (or Accept: application/json) to receive everything in one structured payload:

{
  "document_id": "…uuid…",
  "pdf_base64": "JVBERi0xLjQK…",       // the anonymized PDF, base64-encoded
  "extracted": {                        // null unless extract=1
    "full_name": "JANE DOE",
    "date_of_birth": "1985-04-16",
    "date_of_expiry": "2027-08-30"
  },
  "expired": false                      // null unless extract=1
}

Retries & backoff

The service may return 429 (rate limit or temporary saturation — "Server busy") or 502 / 503 / 504 under load. These are transient and safe to retry. Other 4xx responses (400, 401, 413, 415, 422) are permanent — do not retry.

• Retry up to 3 times with exponential backoff (~1s, 2s, 4s + small jitter).
• On 429, honor the Retry-After response header (seconds) if present, instead of the backoff.
• Treat any 2xx as success; stop retrying on permanent 4xx.

Example — curl (PDF + extracted headers)

curl -X POST https://anonid.nl/api/public/v1/anonymize \
  -H "X-API-Key: $ANONID_KEY" \
  -F "file=@scan.jpg" \
  -F "purpose=Huurcontract Prinsengracht 42" \
  -F "extract=1" \
  -o anonymized.pdf -D headers.txt

# Then read the extracted fields from headers.txt:
grep -i '^x-extracted-' headers.txt

Example — Node.js (JSON envelope)

import fs from "node:fs/promises";

const blob = new Blob([await fs.readFile("scan.jpg")], { type: "image/jpeg" });
const fd = new FormData();
fd.append("file", blob, "scan.jpg");
fd.append("purpose", "Huurcontract Prinsengracht 42");
fd.append("extract", "1");
fd.append("format", "json");

const res = await fetch("https://anonid.nl/api/public/v1/anonymize", {
  method: "POST",
  headers: { "X-API-Key": process.env.anonid_KEY! },
  body: fd,
});
if (!res.ok) throw new Error(await res.text());

const { document_id, pdf_base64, extracted, expired } = await res.json();
await fs.writeFile("anonymized.pdf", Buffer.from(pdf_base64, "base64"));

console.log("document:", document_id);
console.log("full name:", extracted?.full_name);
console.log("date of birth:", extracted?.date_of_birth);
console.log("date of expiry:", extracted?.date_of_expiry, expired ? "(EXPIRED)" : "");

What gets redacted?

Each request applies your organization's default redaction profile unioned with the country's legally-required minimum (BSN and MRZ for Dutch passports and ID cards). Configure the profile in Settings → Redaction rules.

Watermark

Pass purpose to burn a diagonal red "KOPIE – {purpose}" stamp across every page at ~50% opacity and −30° rotation, repeated three times top-to-bottom. The stamp is normalized to ASCII (WinAnsi-safe) and truncated to 80 characters. It's intended for visual deterrence and audit — it is not cryptographic proof and can be cropped out of a re-scanned print. For tamper-evident distribution, ship the returned PDF together with the X-Document-Id so it can be verified against your AnonID audit log.