Endpunkte

Alle Endpunkte erfordern einen API-Schlüssel. Siehe Authentifizierung.

Der Extract-Endpunkt antwortet mit flachem JSON ohne data-Hülle. Der Quota-Endpunkt verwendet eine Hülle aus data und meta. Fehlerantworten geben "success": false mit einem error-Objekt zurück. Siehe Fehlerbehandlung.

Extraktion

Lesen Sie die Daten eines Ausweisdokuments.

text

POST /v1/extract

Der Anfragekörper ist ein Multipart-Formular (multipart/form-data) mit genau einer Datei.

Parameter	Typ	Erforderlich	Beschreibung
`file`	Formulardatei	Ja	Die Dokumentdatei. Genau eine Datei, nicht leer, höchstens 25 MB

Eine hochgeladene Datei ist ein Scan, auch wenn sie mehrere Dokumente enthält.

Beispielanfrage:

bash

curl -s -X POST "https://api.idparse.com/v1/extract" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@passport.jpg"

Hinweis

Eine fehlende Datei, eine leere Datei oder mehr als eine Datei im Feld file führt zu 422 invalid_file. Eine Datei, die größer als 25 MB ist, führt zu 413 file_too_large. Beide Antworten sind kostenlos.

Unterstützte Dateien und Dokumente

Unterstützte Eingabedateien: JPEG, PNG, PDF, TIFF, BMP, WebP und HEIF/HEIC (iPhone-Fotos).

Dateityp	Hinweise
JPEG-, PNG-, TIFF-, BMP- und WebP-Bilder	Ein oder mehrere Dokumente pro Bild
HEIF/HEIC-Bilder	Das Format von iPhone-Fotos
PDF-Dateien	Es werden höchstens die ersten 3 Seiten gelesen

Der Dateityp wird am Inhalt der Datei erkannt, nicht am Dateinamen.

Unterstützte Dokumente:

Das Dokument muss eine MRZ (maschinenlesbare Zone, die Zeilen aus Buchstaben, Ziffern und <-Zeichen am unteren Rand des Dokuments) nach dem Standard ICAO 9303 tragen.

Dokument	MRZ-Format
Reisepässe	TD3
Personalausweise	TD1, TD2
Visa	MRV-A, MRV-B

Wichtig

Ein Dokument ohne MRZ kann nicht gelesen werden. Viele Führerscheine und ältere Ausweise haben keine MRZ.

Antwort: Erfolg

HTTP-Status 200 und "success": true. Mindestens ein Dokument wurde gefunden, und alle drei Prüfziffern dieses Dokuments (Kontrollzahlen, die in der MRZ aufgedruckt sind) haben gestimmt. Diese Antwort wird als ein Scan berechnet.

json

{
    "success": true,
    "documents": [
        {
            "success": true,
            "document_type": "TD3",
            "fields": {
                "surname": "ERIKSSON",
                "given_names": "ANNA MARIA",
                "birth_date": "1974-08-12",
                "sex": "F",
                "nationality": "UTO",
                "document_number": "L898902C3",
                "expiry_date": "2012-04-15",
                "issuing_country": "UTO"
            },
            "check_digits_valid": {
                "document_number": true,
                "birth_date": true,
                "expiry_date": true
            },
            "checksum_protected": {
                "surname": false,
                "given_names": false,
                "birth_date": true,
                "sex": false,
                "nationality": false,
                "document_number": true,
                "expiry_date": true,
                "issuing_country": false
            },
            "failure_reason": null,
            "notes": [
                "birth date century inferred",
                "expiry date century inferred"
            ],
            "page": 1,
            "region": { "x": 0.05, "y": 0.81, "width": 0.9, "height": 0.12 }
        }
    ],
    "document_count": 1,
    "verified_document_count": 1,
    "processing_complete": true,
    "truncation_reason": null,
    "failure_reason": null,
    "notes": ["engines tried: locator"],
    "duration_ms": 480,
    "service_version": "2.0.0"
}

Das Beispiel zeigt den öffentlichen ICAO-Musterpass. Die Bedeutung jedes Feldes ist unter Ergebnisse und Abrechnung erklärt.

Antwort: Mehrere Dokumente

Eine Datei kann mehrere Dokumente enthalten, zum Beispiel zwei Reisepässe, die auf einer Seite eingescannt wurden. Jedes ist ein Eintrag von documents, in der Reihenfolge der Seiten und von oben nach unten. Prüfen Sie success jedes Eintrags: Eine Datei ist ein Erfolg, wenn mindestens ein Dokument geprüft wurde. Die Datei wird als ein Scan berechnet.

json

{
    "success": true,
    "documents": [
        { "success": true, "document_type": "TD3", "page": 1, "...": "erster Reisepass, wie oben" },
        { "success": true, "document_type": "TD3", "page": 1, "...": "zweiter Reisepass, wie oben" }
    ],
    "document_count": 2,
    "verified_document_count": 2,
    "processing_complete": true,
    "truncation_reason": null,
    "failure_reason": null,
    "notes": ["engines tried: locator"],
    "duration_ms": 16000,
    "service_version": "2.0.0"
}

Die Schlüssel "..." stehen für die übrigen Dokumentfelder aus dem Erfolgsbeispiel. Wenn eine Grenze die Arbeit früher beendet hat, hat processing_complete den Wert false, und truncation_reason nennt die Grenze. Siehe Mehrere Dokumente in einer Datei.

Antwort: Nicht lesbares Dokument

HTTP-Status 200 und "success": false. Die Anfrage selbst war in Ordnung, aber kein Dokument konnte gelesen werden. Das Feld failure_reason enthält einen von zehn festen Texten, und documents ist in der Regel leer. Diese Antwort ist kostenlos.

json

{
    "success": false,
    "documents": [],
    "document_count": 0,
    "verified_document_count": 0,
    "processing_complete": true,
    "truncation_reason": null,
    "failure_reason": "no machine readable zone found",
    "notes": ["engines tried: locator, tesseract"],
    "duration_ms": 480,
    "service_version": "2.0.0"
}

Alle zehn Fehlergründe sind unter Ergebnisse und Abrechnung aufgelistet.

Antwort: Teilergebnis

HTTP-Status 200 und "success": false, aber in einem Dokument sind einige Felder gefüllt. Das passiert, wenn die MRZ gefunden wurde, aber nicht jede Prüfziffer gestimmt hat. Diese Antwort ist kostenlos.

json

{
    "success": false,
    "documents": [
        {
            "success": false,
            "document_type": "TD3",
            "fields": {
                "surname": "ERIKSSON",
                "given_names": "ANNA MARIA",
                "birth_date": "1974-08-12",
                "sex": "F",
                "nationality": "UTO",
                "document_number": "L898902C3",
                "expiry_date": null,
                "issuing_country": "UTO"
            },
            "check_digits_valid": {
                "document_number": true,
                "birth_date": true,
                "expiry_date": false
            },
            "checksum_protected": {
                "surname": false,
                "given_names": false,
                "birth_date": true,
                "sex": false,
                "nationality": false,
                "document_number": true,
                "expiry_date": true,
                "issuing_country": false
            },
            "failure_reason": "mrz found but check digits failed",
            "notes": [
                "partial read: trust only fields whose check digit passed"
            ],
            "page": 1,
            "region": null
        }
    ],
    "document_count": 1,
    "verified_document_count": 0,
    "processing_complete": true,
    "truncation_reason": null,
    "failure_reason": "mrz found but check digits failed",
    "notes": ["engines tried: locator, tesseract"],
    "duration_ms": 480,
    "service_version": "2.0.0"
}

Wichtig

Vertrauen Sie in einem Teilergebnis nur einem geschützten Feld, dessen Eintrag in check_digits_valid den Wert true hat. Ein geschütztes Feld, dem nicht vertraut wird, ist null, wie das Ablaufdatum im Beispiel oben. Das Array notes des Dokuments enthält den Text partial read: trust only fields whose check digit passed. Siehe Teilergebnisse.

Antwort-Header des Extract-Endpunkts:

Extract-Antworten tragen Cache-Control: no-store und die vier Nutzungs-Header X-IDParse-Scans-Included, X-IDParse-Scans-Used, X-IDParse-Scans-Remaining und X-IDParse-Period-Ends. Cache-Control: no-store ist in jeder Antwort vorhanden, die die Schlüsselprüfung und die Wartungsprüfung bestanden hat. Die vier Nutzungs-Header sind nur vorhanden, wenn die Prüfung der monatlichen Nutzung ein Ergebnis geliefert hat. Sie können fehlen bei frühen Ablehnungen (401, 403, 503 Wartung), bei 429 rate_limited, bei 503 service_unavailable, wenn die Nutzungsprüfung selbst fehlgeschlagen ist, und bei Konten ohne monatliches Limit. Siehe Limits und Kontingent.

Kontingent

Prüfen Sie Ihren Tarif, Ihre enthaltenen Scans und Ihre Nutzung im laufenden Monat.

text

GET /v1/quota

Dieser Endpunkt ist kostenlos. Er zählt nie als Scan, und er bleibt erreichbar, nachdem Ihre enthaltenen Scans verbraucht sind. Er hat keine Parameter.

Beispielanfrage:

bash

curl -s "https://api.idparse.com/v1/quota" \
  -H "Authorization: Bearer YOUR_API_KEY"

Beispielantwort:

json

{
    "success": true,
    "data": {
        "plan": "Starter",
        "quota": {
            "base_limit": 500,
            "effective_limit": 500,
            "used": 127,
            "remaining": 373,
            "overflow_allowed": false,
            "overflow_percent": 0
        },
        "period": "monthly",
        "resets_at": "2026-10-01T00:00:00+00:00"
    },
    "meta": {
        "timestamp": "2026-09-20T14:30:00+00:00"
    }
}

Feld	Beschreibung
`data.plan`	Der Name Ihres Tarifs. Er wird immer auf Englisch ausgegeben
`data.quota.base_limit`	Die Scans, die pro Monat in Ihrem Tarif enthalten sind
`data.quota.effective_limit`	Die höchste Zahl an Scans, die Sie in diesem Monat nutzen können. Sie ist gleich `base_limit`, außer wenn Mehrnutzung (Nutzung über die enthaltenen Scans hinaus) für Ihr Konto erlaubt ist
`data.quota.used`	Der Nutzungszähler des laufenden Monats. Er kann Scans enthalten, die noch verarbeitet werden
`data.quota.remaining`	`effective_limit` minus `used`, nie unter 0
`data.quota.overflow_allowed`	`true`, wenn Mehrnutzung für Ihr Konto erlaubt ist
`data.quota.overflow_percent`	Die erlaubte Mehrnutzung in Prozent von `base_limit`
`data.period`	`monthly`: Die enthaltenen Scans beginnen in jedem Kalendermonat neu. `lifetime`: Die Scans des kostenlosen Tests werden einmal vergeben und kommen nicht zurück
`data.resets_at`	Der Zeitpunkt, an dem die Nutzung auf 0 zurückgesetzt wird: der erste Tag des nächsten Kalendermonats, 00:00 UTC. `null` beim kostenlosen Test, weil dessen Scans nie neu beginnen
`meta.timestamp`	Die Zeit dieser Antwort

Hinweis

Wenn die monatliche Begrenzung für ein Konto abgeschaltet ist, sind effective_limit und remaining 0, obwohl Scans erlaubt bleiben. Der Nutzungszähler kann Scans enthalten, die noch verarbeitet werden. Er kann nicht bestätigen, ob eine einzelne unterbrochene Anfrage berechnet wurde.

Hinweis

Der Tarifname und die Zahlen im Beispiel sind Platzhalter. Der Quota-Endpunkt zählt zum Limit pro Minute.