> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # Ausweisverifizierung API: Dokument-OCR & Echtheit > Didit verifiziert Ausweisdokumente aus über 220 Ländern und 14.000+ Dokumententypen: Echtheit, OCR, MRZ, Antwort unter 2 s, Pay-per-Use, keine Verträge. ## OpenAPI ````yaml de/openapi-25.json POST /v3/id-verification/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API für Ausweisverifizierung. Authentifizierung über den x-api-key-Header. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/id-verification/: post: tags: - Standalone APIs summary: Ausweisverifizierung (Dokumenten-OCR + Betrugsprüfungen) description: >- Führen Sie die OCR-Erfassung eines Ausweisdokuments durch und prüfen Sie es auf Dokumentenbetrug in einem einzigen Aufruf – liefert die extrahierten Inhaberfelder, die geparste MRZ, einen `status` (`Approved`/`Declined`/`In Review`) sowie eine `warnings`-Liste zurück, die jedes gefundene Problem erläutert. Unterstützt 14,000+ Dokumenttypen aus 220+ Ländern und Gebieten. **Funktionsweise.** Senden Sie das `front_image` des Dokuments (erforderlich) und bei zweiseitigen Dokumenten das `back_image`. Laden Sie unbeschnittene Fotos hoch, auf denen alle vier Ecken des Dokuments sichtbar sind – der Dienst erkennt, richtet aus und beschneidet das Dokument selbst, schneiden Sie es daher nicht vorab zu. Das Dokument wird automatisch klassifiziert (Sie müssen Land oder Dokumenttyp niemals angeben), die visuelle Zone wird per OCR ausgelesen und die MRZ sowie eventuelle Barcodes werden dekodiert. Durch Gegenprüfungen werden anschließend Datumsangaben, Zahlenformate und MRZ-Prüfziffern validiert und die visuelle Zone mit der MRZ abgeglichen. Mit `perform_document_liveness=true` werden die Bilder zusätzlich auf Bildschirmwiedergaben, gedruckte Kopien und Porträtmanipulationen geprüft. **Entscheidungslogik.** `status` ist `Approved`, sofern nicht mindestens eine Warnung zu einer Ablehnung führt. Betrugs- und Hard-Failure-Risiken führen immer zu einer Ablehnung: `DOCUMENT_EXPIRED`, `SCREEN_CAPTURE_DETECTED`, `PRINTED_COPY_DETECTED`, `PORTRAIT_MANIPULATION_DETECTED`, `PUBLIC_DOCUMENT_IMAGE_DETECTED` sowie Extraktionsfehler (`NAME_NOT_DETECTED`, `DATE_OF_BIRTH_NOT_DETECTED`, `DOCUMENT_NUMBER_NOT_DETECTED`). (`PORTRAIT_IMAGE_NOT_DETECTED`, `INVALID_DATE` und `MRZ_NOT_DETECTED` existieren in Workflow-Sitzungen, werden jedoch von diesem eigenständigen Endpoint niemals erzeugt. `COULD_NOT_DETECT_DOCUMENT_TYPE` wird hier zurückgegeben, wenn das Vorderseitenbild keinem bekannten offiziellen Dokumentendesign mit hoher Konfidenz entspricht, und lehnt die Anfrage ab.) Drei Risikogruppen sind pro Anfrage über `invalid_mrz_action`, `inconsistent_data_action` und `expiration_date_not_detected_action` konfigurierbar (`DECLINE` oder `NO_ACTION`). Alle anderen Warnungen (z. B. `POSSIBLE_DUPLICATED_USER`) sind rein informativ und führen für sich allein niemals zu einer Ablehnung. Wenn `perform_document_liveness=true` (Standardeinstellung) und die Fälschungsprüfung keinen verwertbaren Score liefert – der Anbieter ist ausgefallen, hat nicht mit 200 geantwortet oder hat HTTP 200 mit `status="ERR"` zurückgegeben –, gibt der Aufruf `200` mit `status: "In Review"` und einer Warnung `DOCUMENT_LIVENESS_NOT_COMPUTED` (`log_type: "warning"`) anstelle von `Approved` zurück: Eine Prüfung, die nicht ausgeführt wurde, ist kein Beweis dafür, dass das Dokument echt ist. Diese Eskalation ist nicht konfigurierbar und setzt ein `Declined` niemals außer Kraft; mit `perform_document_liveness=false` wird die Prüfung übersprungen und der Status richtet sich wie bisher nach den verbleibenden Warnungen. Ein Dokument, das überhaupt nicht verarbeitet werden kann, gibt `400` mit `{"error": "COULD_NOT_RECOGNIZE_DOCUMENT"}` zurück; ein lesbares, aber problematisches Dokument gibt `200` mit `status: "Declined"` zurück – prüfen Sie stets `id_verification.status` und `id_verification.warnings`, nicht nur den HTTP-Code. **Abrechnung.** Jede `200`-Antwort verbraucht einen Ausweisverifizierungs-API-Credit (abgerechnet über Ihr Tarif-Guthaben oder Aufladeguthaben). Wenn das Guthaben der Organisation den Aufruf nicht deckt, gibt der Endpoint vor jeder Bildverarbeitung `403` mit dem Fehler für unzureichende Credits zurück. **Sitzungspersistenz (`save_api_request`, Standard `true`).** Bei `true` wird der Aufruf als Sitzung vom Typ API persistiert: Er erscheint in der Business Console, die zurückgegebene `request_id` ist eine echte Sitzungs-ID, die Sie an `GET /v3/session/{sessionId}/decision/` übergeben können, die zugeschnittenen Dokumenten-/Porträtbilder werden gespeichert und als kurzlebige Medien-URLs (`https:///ocr/...`) zurückgegeben, und ein Webhook `status.updated` wird an Ihre konfigurierten Webhook-Ziele gesendet. Bei `false` wird nichts gespeichert, `request_id` ist eine einmalige Korrelations-UUID und `portrait_image`/`front_image`/`back_image` werden inline als base64-codierte JPEG-Strings zurückgegeben. **Sandbox.** Sandbox-API-Schlüssel überspringen sämtliche Verarbeitungen und Abrechnungen: Nach der Anfragevalidierung (fehlerhafte Eingaben geben weiterhin `400` zurück) liefert der Endpoint eine statische `Approved`-Mock-Payload zurück (einen fiktiven US-amerikanischen Personalausweis für einen „Sandbox User“), es wird keine Sitzung persistiert und es werden keine Credits verbraucht. **Authentifizierung.** Senden Sie den API-Schlüssel Ihrer Anwendung im Header `x-api-key`. Fehlende oder ungültige Anmeldedaten geben `403` zurück (`{"detail": "You do not have permission to perform this action."}`) – diese API gibt niemals `401` zurück. **Rate-Limit.** Geteiltes Schreibkontingent von 300 Anfragen/Min. pro API-Schlüssel über alle POST/PATCH/DELETE-Endpoints hinweg; bei Überschreitung wird `429` zurückgegeben. operationId: post_v3id-verification parameters: [] requestBody: required: true content: multipart/form-data: schema: type: object required: - front_image properties: front_image: type: string format: binary description: >- Vorderseite des Ausweisdokuments. Zulässige Dateiendungen: `tiff`, `jpg`, `jpeg`, `png`, `webp`, `pdf`. Maximale Upload-Größe: **10 MB** (größere Dateien werden mit `400` abgelehnt). PDFs werden vor der OCR in ein Bild gerendert; verschlüsselte PDFs erfordern `front_image_password`. Bilder werden automatisch auf ca. 0,5 MB komprimiert und die EXIF-Ausrichtung wird angewendet. Laden Sie die vollständige, unbeschnittene Aufnahme hoch, auf der alle vier Ecken des Dokuments sichtbar sind. front_image_password: type: string description: >- Passwort zur Entschlüsselung von `front_image`, wenn es sich um eine verschlüsselte PDF-Datei handelt. Das Senden einer verschlüsselten PDF-Datei ohne (oder mit einem falschen) Passwort gibt `400` zurück. writeOnly: true back_image: type: string format: binary description: >- Rückseite des Dokuments – senden Sie diese immer, wenn das Dokument eine hat (viele Ausweise tragen die MRZ oder einen Barcode auf der Rückseite; das Weglassen führt lediglich dazu, dass die MRZ und Felder der Rückseite in der Antwort leer bleiben – dieser Endpoint löst keine Warnung wegen fehlender MRZ aus). Gleiche Format- und Größenbeschränkungen wie bei `front_image`. Wenn weggelassen, sind `back_image` und Felder der Rückseite in der Antwort `null`. back_image_password: type: string description: >- Passwort zur Entschlüsselung von `back_image`, wenn es sich um eine verschlüsselte PDF-Datei handelt. writeOnly: true perform_document_liveness: type: boolean default: true description: >- Überprüft beide Bilder auf Präsentationsbetrug: Bildschirmwiedergaben (`SCREEN_CAPTURE_DETECTED`), gedruckte Kopien (`PRINTED_COPY_DETECTED`) und Porträtmanipulation (`PORTRAIT_MANIPULATION_DETECTED`). Jeder dieser Fälle führt zur automatischen Ablehnung. Standardmäßig aktiviert; setzen Sie den Wert auf `false`, um das Betrugsscreening zu überspringen und die Latenz zu verringern. Wenn die Funktion aktiviert ist und der Anbieter keinen verwertbaren Score zurückgibt, lautet die Antwort `In Review` mit einer `DOCUMENT_LIVENESS_NOT_COMPUTED`-Warnung anstelle von `Approved`. example: true minimum_age: type: integer nullable: true default: null minimum: 1 maximum: 120 description: >- Akzeptiert und validiert (1–120), wird jedoch **derzeit von diesem Endpoint nicht angewendet** – es erzeugt über dieses Feld niemals eine `MINIMUM_AGE_NOT_MET`-Warnung. Setzen Sie Altersregeln anhand des zurückgegebenen `date_of_birth`/`age` durch oder verwenden Sie einen Verifizierungssitzungs-Workflow mit Altersbeschränkungen. expiration_date_not_detected_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- Was zu tun ist, wenn kein Ablaufdatum gelesen werden kann (`EXPIRATION_DATE_NOT_DETECTED`). Standardwert ist `NO_ACTION`, da viele Ausweisdokumente kein Ablaufdatum aufgedruckt haben. Hinweis: Ein *erkanntes und abgelaufenes* Ablaufdatum führt immer zu einer Ablehnung (`DOCUMENT_EXPIRED`), unabhängig von dieser Option. invalid_mrz_action: type: string enum: - NO_ACTION - DECLINE default: DECLINE description: >- Was zu tun ist, wenn die extrahierte MRZ die Prüfziffernvalidierung nicht besteht (`MRZ_VALIDATION_FAILED`). Eine fehlende MRZ löst an diesem Endpoint keine Warnung aus. Nur relevant für Dokumente, die eine MRZ enthalten. `REVIEW` wird an diesem Endpoint nicht unterstützt und gibt `400` zurück. inconsistent_data_action: type: string enum: - NO_ACTION - DECLINE default: DECLINE description: >- Was zu tun ist, wenn extrahierte Daten in sich inkonsistent sind: `DATA_INCONSISTENT`, `MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME` (visuelle Zone stimmt nicht mit der MRZ überein) oder `DOCUMENT_NAME_DIFFERENT_FROM_OTHER_APPROVED_DOCUMENTS`. critical_field_occlusion_action: type: string enum: - NO_ACTION - DECLINE default: DECLINE description: >- Was zu tun ist, wenn ein kritisches gedrucktes Feld auf der Aufnahme physisch verdeckt war (`CRITICAL_FIELD_OCCLUSION_DETECTED`) - eine Identifikationsnummer, ein Name, das Geburtsdatum oder das Ablaufdatum. Lehnt standardmäßig ab, wie die anderen Dokumentintegritätsrisiken dieses Endpoints: Das Verdecken von Nummern, mit denen ein Bericht abgeglichen wird, entspricht einem geschwärzten Dokument. Der für ein verdecktes Feld ausgelesene Wert wird bei der Extraktion ohnehin verworfen, sodass die passende Warnung `*_NOT_DETECTED` üblicherweise hinzukommt. `REVIEW` wird auf diesem Endpoint nicht unterstützt und gibt `400` zurück. document_or_personal_number_format_mismatch_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- Was zu tun ist, wenn eine Nummer nicht dem Format entspricht, das die ausstellende Behörde für diesen Dokumenttyp verwendet (`DOCUMENT_NUMBER_FORMAT_MISMATCH`, `PERSONAL_NUMBER_FORMAT_MISMATCH`). Standardwert ist `NO_ACTION`, wodurch die Warnung gemeldet wird, ohne den Status zu ändern. `REVIEW` wird auf diesem Endpoint nicht unterstützt und gibt `400` zurück. preferred_characters: type: string enum: - latin - non_latin default: latin description: >- Bevorzugtes Schriftsystem für Namens-/Adressfelder auf Dokumenten, die sowohl lateinischen als auch nicht-lateinischen Text enthalten (Arabisch, Kyrillisch, CJK, …). `latin` gibt transliterierte/lateinische Werte zurück; `non_latin` bevorzugt das native Schriftsystem. save_api_request: type: boolean default: true description: >- Wenn `true` (Standard), wird der Aufruf als Sitzung vom Typ API persistent gespeichert — sichtbar in der Business Console, abrufbar über `GET /v3/session/{sessionId}/decision/` unter Verwendung der zurückgegebenen `request_id`, angekündigt über einen `status.updated`-Webhook und mit Dokumentenbildern, die als Medien-URLs zurückgegeben werden. Wenn `false`, wird nichts gespeichert, `request_id` ist eine flüchtige UUID und Bilder werden inline als Base64-JPEG-Strings zurückgegeben. example: true vendor_data: type: string description: >- Optionale opake Zeichenfolge (Ihre interne Benutzer-ID, E-Mail, UUID…), die in der gespeicherten Sitzung hinterlegt und in der Antwort zurückgegeben wird. Verwenden Sie sie, um API-Aufrufe mit Ihren eigenen Datensätzen abzugleichen und Sitzungen später zu filtern. example: user-123 metadata: type: object additionalProperties: true description: >- Optionales JSON-Objekt, das mit der Sitzung gespeichert (wenn `save_api_request=true`) und in der Antwort zurückgegeben wird. Senden Sie es bei Multipart-Anfragen als JSON-codiertes String-Feld (z. B. `metadata={"flow":"onboarding"}`) – es wird in ein Objekt geparst. example: flow: onboarding example: front_image: (binary JPEG/PNG/PDF of the document front) back_image: (binary JPEG/PNG/PDF of the document back) perform_document_liveness: true save_api_request: true vendor_data: user-123 metadata: flow: onboarding responses: '200': description: >- Dokument verarbeitet. `id_verification.status` ist `Approved`, `Declined` oder `In Review`; jedes erkannte Problem wird einzeln in `id_verification.warnings` aufgeführt. `In Review` wird zurückgegeben, wenn eine angeforderte Dokumenten-Liveness-Prüfung kein verwertbares Ergebnis geliefert hat (`DOCUMENT_LIVENESS_NOT_COMPUTED`). Ein problematisches Dokument gibt dennoch `200` mit `status: "Declined"` zurück – prüfen Sie den Body, nicht nur den HTTP-Code. Wenn `save_api_request=true`, ist `request_id` die persistierte Sitzungs-ID und Bildfelder sind kurzlebige Medien-URLs; bei `save_api_request=false` sind sie Inline-Base64-JPEG-Strings. content: application/json: examples: Approved: summary: >- Beidseitiger Ausweis sauber gelesen (gespeichert — Bilder als Medien-URLs) value: request_id: 11d219ed-d59c-4b1d-8d65-9b933f12d5b8 id_verification: status: Approved document_type: Identity Card document_subtype: ID_CARD_GENERIC document_number: CBX164224 personal_number: 20446581H portrait_image: >- https:///ocr/11d219ed-d59c-4b1d-8d65-9b933f12d5b8-portrait_image-8c2f.jpg?signature=... front_image: >- https:///ocr/11d219ed-d59c-4b1d-8d65-9b933f12d5b8-front_image-4a1e.jpg?signature=... back_image: >- https:///ocr/11d219ed-d59c-4b1d-8d65-9b933f12d5b8-back_image-77b0.jpg?signature=... front_image_camera_front: null back_image_camera_front: null front_image_camera_front_face_match_score: null back_image_camera_front_face_match_score: null front_image_quality_score: focus_score: 78 brightness_score: 83.2 brightness_issue: ok is_document_fully_visible: true resolution_score: 40.7 overall_score: 70.2 back_image_quality_score: focus_score: 100 brightness_score: 95.6 brightness_issue: ok is_document_fully_visible: true resolution_score: 43 overall_score: 84.4 date_of_birth: '1980-01-13' age: 46 expiration_date: '2032-03-31' date_of_issue: '2022-03-31' issuing_state: ESP issuing_state_name: Spain first_name: Julio Francisco last_name: Fores Sena full_name: Julio Francisco Fores Sena gender: M address: >- Brda. Urb. El Cardonal 0052 52 Po3 B,Taco,San Cristobal De La Laguna,Santa Cruz De Tenerife formatted_address: >- Av. el Cardonal, 52, b, 38108 La Laguna, Santa Cruz de Tenerife, Spain place_of_birth: Valencia, Valencia marital_status: UNKNOWN nationality: ESP extra_fields: first_surname: Fores second_surname: Sena mrz: surname: FORES SENA name: JULIO FRANCISCO country: ESP nationality: ESP birth_date: '800113' expiry_date: '320331' sex: M document_type: ID document_number: CBX164224 optional_data: 20446581H optional_data_2: '' birth_date_hash: '9' expiry_date_hash: '8' document_number_hash: '3' final_hash: '3' personal_number: 20446581H warnings: [] errors: [] mrz_type: TD1 mrz_string: |- IDESPCBX164224320446581H<<<<<< 8001139M3203318ESP<<<<<<<<<<<3 FORES- Av. el Cardonal, 52, b, 38108 La Laguna, Santa Cruz de Tenerife, Spain raw_results: address_components: - long_name: b short_name: b types: - subpremise - long_name: '52' short_name: '52' types: - street_number - long_name: Avenida el Cardonal short_name: Av. el Cardonal types: - route - long_name: La Laguna short_name: La Laguna types: - locality - political - long_name: Spain short_name: ES types: - country - political - long_name: '38108' short_name: '38108' types: - postal_code formatted_address: >- Av. el Cardonal, 52, b, 38108 La Laguna, Santa Cruz de Tenerife, Spain geometry: location: lat: 28.4501161 lng: -16.3004407 location_type: ROOFTOP types: - street_address - subpremise document_location: latitude: 28.4501161 longitude: -16.3004407 label: Spain Identity Card Address is_verified: true category: Residential warnings: [] barcodes: [] vendor_data: user-123 metadata: flow: onboarding created_at: '2026-06-12T02:21:56.013573+00:00' Declined - expired document: summary: >- Upload nur der Vorderseite eines abgelaufenen Personalausweises value: request_id: f61681b8-9422-4378-ac3e-04c6a247fb45 id_verification: status: Declined document_type: Identity Card document_subtype: ID_CARD_GENERIC document_number: BNK123072 personal_number: 21771255F portrait_image: >- https:///ocr/f61681b8-9422-4378-ac3e-04c6a247fb45-portrait_image-1d9a.jpg?signature=... front_image: >- https:///ocr/f61681b8-9422-4378-ac3e-04c6a247fb45-front_image-5c2b.jpg?signature=... back_image: null front_image_camera_front: null back_image_camera_front: null front_image_camera_front_face_match_score: null back_image_camera_front_face_match_score: null front_image_quality_score: focus_score: 100 brightness_score: 95.7 brightness_issue: ok is_document_fully_visible: true resolution_score: 22.2 overall_score: 79.3 back_image_quality_score: null date_of_birth: '1997-01-30' age: 29 expiration_date: '2025-11-26' date_of_issue: null issuing_state: ESP issuing_state_name: Spain first_name: Lucia last_name: Marin Castro full_name: Lucia Marin Castro gender: F address: null formatted_address: null place_of_birth: null marital_status: UNKNOWN nationality: ESP extra_fields: first_surname: Marin second_surname: Castro mrz: {} parsed_address: null warnings: - risk: DOCUMENT_EXPIRED feature: ID_VERIFICATION additional_data: null log_type: error short_description: Document expired long_description: >- The document's expiration date has passed, rendering it no longer valid for use. barcodes: [] vendor_data: user-123 metadata: null created_at: '2026-06-12T02:25:48.117204+00:00' schema: type: object properties: request_id: type: string format: uuid description: >- Beibehaltene Sitzungs-ID, wenn `save_api_request=true` (verwendbar mit `GET /v3/session/{sessionId}/decision/`); andernfalls eine vorübergehende Korrelations-UUID. id_verification: type: object properties: status: type: string enum: - Approved - Declined - In Review description: >- `Approved`, wenn keine Warnung zu einer Ablehnung führt und die angeforderte Dokument-Liveness-Prüfung ein verwertbares Ergebnis geliefert hat; `In Review`, wenn diese angeforderte Prüfung kein verwertbares Ergebnis geliefert hat (`DOCUMENT_LIVENESS_NOT_COMPUTED`); `Declined`, wenn eine Warnung zu einer Ablehnung führt — die Liste `warnings` erklärt warum. document_type: type: string nullable: true description: >- Anzeigename des erkannten Dokumententyps: `Identity Card`, `Passport`, `Driver's License`, `Residence Permit`, `Health Insurance Card` oder `Tax Card`. `null`, wenn das Dokument nicht klassifiziert werden konnte. example: Identity Card document_subtype: type: string nullable: true description: >- Feinerer Subtyp, sofern verfügbar (z. B. `ID_CARD_GENERIC`, `EPASSPORT`). example: ID_CARD_GENERIC document_number: type: string nullable: true example: CBX164224 personal_number: type: string nullable: true description: >- Sekundäre persönliche/nationale Nummer, die auf einigen Dokumenten aufgedruckt ist. example: 20446581H portrait_image: type: string nullable: true description: >- Zugeschnittenes Porträtfoto aus dem Dokument. Eine kurzlebige Medien-URL (`https:///ocr/...`), wenn `save_api_request=true` (Standard); ein inline-Base64-kodierter JPEG-String, wenn `save_api_request=false`. `null`, wenn kein Porträt erkannt wurde. front_image: type: string nullable: true description: >- Ausgerichteter Zuschnitt der Dokumentvorderseite. Medien-URL, wenn gespeichert, andernfalls Inline-Base64-JPEG. back_image: type: string nullable: true description: >- Ausgerichteter Zuschnitt der Dokumentrückseite. `null`, wenn kein `back_image` hochgeladen wurde. front_image_camera_front: type: string nullable: true description: >- Auf diesem Endpoint immer `null` (nur in Verifizierungssitzungen mit Kameraerfassung ausgefüllt). back_image_camera_front: type: string nullable: true description: Auf diesem Endpoint immer `null`. front_image_camera_front_face_match_score: type: number nullable: true description: Auf diesem Endpoint immer `null`. back_image_camera_front_face_match_score: type: number nullable: true description: Auf diesem Endpoint immer `null`. front_image_quality_score: type: object nullable: true description: >- Erfassungsqualitätsdiagnose für das hochgeladene Bild (`null`, wenn die Seite nicht bereitgestellt wurde oder das Scoring fehlgeschlagen ist). Alle Werte liegen zwischen 0 und 100. properties: focus_score: type: number format: float description: >- Schärfe des Dokumentenzuschnitts (höher ist schärfer). brightness_score: type: number format: float description: Exposure-Qualität (höher ist besser). brightness_issue: type: string nullable: true description: >- `ok`, wenn die Belichtung in Ordnung ist, andernfalls das erkannte Problem (z. B. zu dunkel / zu hell). is_document_fully_visible: type: boolean nullable: true description: >- Gibt an, ob sich alle vier Ecken des Dokuments innerhalb des Rahmens befinden. resolution_score: type: number format: float description: Effektive Auflösung des Dokumentbereichs. overall_score: type: number format: float description: Aggregierter Qualitätswert. back_image_quality_score: type: object nullable: true description: >- Erfassungsqualitätsdiagnose für das hochgeladene Bild (`null`, wenn die Seite nicht bereitgestellt wurde oder das Scoring fehlgeschlagen ist). Alle Werte liegen zwischen 0 und 100. properties: focus_score: type: number format: float description: >- Schärfe des Dokumentenzuschnitts (höher ist schärfer). brightness_score: type: number format: float description: Exposure-Qualität (höher ist besser). brightness_issue: type: string nullable: true description: >- `ok`, wenn die Belichtung in Ordnung ist, andernfalls das erkannte Problem (z. B. zu dunkel / zu hell). is_document_fully_visible: type: boolean nullable: true description: >- Gibt an, ob sich alle vier Ecken des Dokuments innerhalb des Rahmens befinden. resolution_score: type: number format: float description: Effektive Auflösung des Dokumentbereichs. overall_score: type: number format: float description: Aggregierter Qualitätswert. date_of_birth: type: string format: date nullable: true example: '1980-01-13' age: type: integer nullable: true description: >- Alter des Inhabers in Jahren, berechnet aus `date_of_birth`. example: 46 expiration_date: type: string format: date nullable: true example: '2032-03-31' date_of_issue: type: string format: date nullable: true example: '2022-03-31' issuing_state: type: string nullable: true description: Ausstellungsland (ISO 3166-1 Alpha-3). example: ESP issuing_state_name: type: string nullable: true example: Spain first_name: type: string nullable: true example: Julio Francisco last_name: type: string nullable: true example: Fores Sena full_name: type: string nullable: true example: Julio Francisco Fores Sena gender: type: string nullable: true description: '`M`, `F` oder `null`, wenn nicht gedruckt/erkannt.' example: M address: type: string nullable: true description: Adresse genau wie auf dem Dokument aufgedruckt. formatted_address: type: string nullable: true description: Geocodierte, normalisierte Version von `address`. place_of_birth: type: string nullable: true example: Valencia, Valencia marital_status: type: string nullable: true description: >- `UNKNOWN`, es sei denn, auf dem Dokument ist der Familienstand aufgedruckt. example: UNKNOWN nationality: type: string nullable: true description: Staatsangehörigkeit des Inhabers (ISO 3166-1 alpha-3). example: ESP extra_fields: type: object nullable: true additionalProperties: true description: >- Dokumentspezifische Zusatzfelder ohne eigene Spalte (z. B. `first_surname`/`second_surname` bei spanischen Ausweisen, Führerscheinklassen bei Führerscheinen). mrz: type: object description: >- Geparste maschinenlesbare Zone. Ein **leeres Objekt** (`{}`), wenn das Dokument keine MRZ aufweist oder diese nicht gelesen werden konnte — prüfen Sie in diesem Fall auch die Liste `warnings`. Datumsangaben innerhalb der MRZ verwenden das Rohformat `YYMMDD`. properties: surname: type: string example: FORES SENA name: type: string example: JULIO FRANCISCO country: type: string description: Ausstellungsland (ISO 3166-1 Alpha-3). example: ESP nationality: type: string description: >- Staatsangehörigkeit des Inhabers (ISO 3166-1 alpha-3). example: ESP birth_date: type: string description: Unverarbeitetes MRZ-Geburtsdatum (`YYMMDD`). example: '800113' expiry_date: type: string description: Unverarbeitetes MRZ-Ablaufdatum (`YYMMDD`). example: '320331' sex: type: string example: M document_type: type: string description: MRZ-Dokumenttyp-Code (z. B. `ID`, `P`). example: ID document_number: type: string example: CBX164224 optional_data: type: string nullable: true example: 20446581H optional_data_2: type: string nullable: true example: '' birth_date_hash: type: string description: MRZ-Prüfziffer für das Geburtsdatum. example: '9' expiry_date_hash: type: string description: MRZ-Prüfziffer für das Ablaufdatum. example: '8' document_number_hash: type: string description: MRZ-Prüfziffer für die Dokumentnummer. example: '3' final_hash: type: string description: Zusammengesetzte MRZ-Prüfziffer. example: '3' personal_number: type: string nullable: true example: 20446581H warnings: type: array items: type: string description: Nicht-kritische MRZ-Parsing-Warnungen. errors: type: array items: type: string description: >- MRZ-Prüfziffer-/Parsing-Fehler. Nicht-leere Fehler werden als `MRZ_VALIDATION_FAILED`-Warnung ausgewiesen. mrz_type: type: string description: >- MRZ-Layout: `TD1` (Personalausweise, 3 Zeilen), `TD2` oder `TD3` (Reisepässe, 2 Zeilen). example: TD1 mrz_string: type: string description: >- Unverarbeiteter MRZ-Text wie ausgelesen, Zeilen getrennt durch `\n`. mrz_key: type: string description: >- Zusammengesetzter Schlüssel (Dokumentennummer + Prüfziffern), der für Querprüfungen verwendet wird. parsed_address: type: object nullable: true description: >- Strukturierte, geocodierte Aufschlüsselung von `address`. `null`, wenn das Dokument keine Adresse enthält oder sie nicht analysiert werden konnte. properties: street_1: type: string nullable: true example: Avenida el Cardonal 52 street_2: type: string nullable: true example: b city: type: string nullable: true example: La Laguna region: type: string nullable: true example: Canarias country: type: string nullable: true description: ISO 3166-1 Alpha-2-Ländercode. example: ES postal_code: type: string nullable: true example: '38108' address_type: type: string nullable: true example: Avenida formatted_address: type: string nullable: true description: Kanonischer geokodierter Adress-String. example: >- Av. el Cardonal, 52, b, 38108 La Laguna, Santa Cruz de Tenerife, Spain raw_results: type: object additionalProperties: true description: >- Unverarbeitete Geocoding-Payload (`address_components`, `geometry.location`, `place_id`, …) für fortgeschrittene Nutzer. document_location: type: object nullable: true properties: latitude: type: number longitude: type: number description: Geocodierte Koordinaten der Dokumentadresse. label: type: string nullable: true description: >- Aus welchem Dokumentenfeld die Adresse ausgelesen wurde. example: Spain Identity Card Address is_verified: type: boolean description: >- Gibt an, ob die Geokodierung die Existenz der Adresse bestätigt hat. category: type: string nullable: true description: >- Adresskategorie (z. B. `Residential`, `Commercial`). example: Residential warnings: type: array description: >- Leer bei einer fehlerfreien Genehmigung. Jeder Eintrag erläutert ein erkanntes Risiko; Einträge mit `log_type: "error"` setzen `status` auf `Declined`, und `DOCUMENT_LIVENESS_NOT_COMPUTED` (`log_type: "warning"`) setzt ihn auf `In Review`. items: type: object properties: risk: type: string description: >- Maschinenlesbarer Risiko-Code. Risiken, die immer zur Ablehnung führen: `DOCUMENT_EXPIRED`, `MINIMUM_AGE_NOT_MET`, `PORTRAIT_IMAGE_NOT_DETECTED`, `SCREEN_CAPTURE_DETECTED`, `PRINTED_COPY_DETECTED`, `PORTRAIT_MANIPULATION_DETECTED`, `PUBLIC_DOCUMENT_IMAGE_DETECTED`, `INVALID_DATE`, `COULD_NOT_RECOGNIZE_DOCUMENT` (nur 400, niemals eine Warnung), `DOCUMENT_NUMBER_NOT_DETECTED`, `COULD_NOT_DETECT_DOCUMENT_TYPE`, `NAME_NOT_DETECTED`, `DATE_OF_BIRTH_NOT_DETECTED`. Gesteuert über Anfrageoptionen: `MRZ_NOT_DETECTED` / `MRZ_VALIDATION_FAILED` (`invalid_mrz_action`), `DATA_INCONSISTENT` / `MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME` / `DOCUMENT_NAME_DIFFERENT_FROM_OTHER_APPROVED_DOCUMENTS` (`inconsistent_data_action`), `EXPIRATION_DATE_NOT_DETECTED` (`expiration_date_not_detected_action`). Andere Risiken (z. B. `POSSIBLE_DUPLICATED_USER`) sind rein informativ. `DOCUMENT_LIVENESS_NOT_COMPUTED` wird ausgelöst, wenn `perform_document_liveness=true` gesetzt ist, die Fälschungsprüfung jedoch keinen nutzbaren Wert zurückgegeben hat; dies setzt `status` auf `In Review`. `COULD_NOT_DETECT_DOCUMENT_TYPE` wird auch zurückgegeben, wenn die Vorderseite des Dokuments mit hoher Konfidenz keinem bekannten offiziellen Dokumentenmuster entspricht, beispielsweise bei einem bearbeiteten oder computergenerierten Dokument oder einem noch nicht unterstützten Muster. example: DOCUMENT_EXPIRED feature: type: string enum: - ID_VERIFICATION description: >- Funktion, die die Warnung ausgelöst hat. An diesem Endpoint immer `ID_VERIFICATION`. additional_data: type: object nullable: true additionalProperties: true description: >- Zusätzlicher Kontext für einige Risiken (z. B. enthält `POSSIBLE_DUPLICATED_USER` die `duplicated_session_id`); `null` für die meisten. log_type: type: string enum: - error - warning - information description: >- Schweregrad. `error`-Warnungen setzen `status` auf `Declined`; `warning` (nur `DOCUMENT_LIVENESS_NOT_COMPUTED`, wenn die angeforderte Fälschungsprüfung keinen verwertbaren Wert geliefert hat) setzt `status` auf `In Review`; `information`-Einträge sind hinweisend und ändern den Status nie. short_description: type: string description: >- Für Menschen lesbare einzeilige Zusammenfassung des Risikos. long_description: type: string description: Lesbare Erklärung des Risikos. barcodes: type: array description: >- Aus dem Dokument dekodierte Barcodes (PDF417, QR, …). Leer, wenn das Dokument keine enthält oder keine gelesen werden konnten. items: type: object properties: type: type: string description: >- Barcode-Typ (z. B. `PDF417`, `QR_CODE`, `UNKNOWN`). position: type: object nullable: true additionalProperties: true description: Position des Barcodes im Bild, sofern verfügbar. data: type: string description: Dekodierte Payload. data_raw: type: string description: >- Unverarbeitete (nicht decodierte) Payload, sofern abweichend. side: type: string nullable: true description: '`front` oder `back`.' vendor_data: type: string nullable: true description: >- Rückgabe der von Ihnen gesendeten `vendor_data` oder `null`. metadata: type: object nullable: true additionalProperties: true description: >- Rückgabe des von Ihnen gesendeten `metadata`-Objekts oder `null`. created_at: type: string format: date-time description: >- ISO 8601-Zeitstempel (UTC), wann die Antwort generiert wurde. '400': description: >- Validierungs- oder Verarbeitungsfehler. Probleme auf Feldebene geben das Standardantwortformat von DRF zurück (ein Array von Meldungen pro betroffenem Feld). Probleme mit verschlüsselten PDFs geben `{"detail": ...}` zurück. Ein Dokumentenbild, in dem überhaupt kein Dokument erkannt werden kann, gibt `{"error": "COULD_NOT_RECOGNIZE_DOCUMENT"}` zurück. PDF-Uploads können zusätzlich mit "The submitted PDF file is corrupted or invalid." oder einem Fehler wegen fehlender Seiten fehlschlagen. content: application/json: examples: Missing front image: summary: '`front_image` ist nicht in den Formulardaten enthalten' value: front_image: - No file was submitted. Unsupported file extension: summary: Dateiendung außerhalb von tiff/jpg/jpeg/png/webp/pdf value: front_image: - >- File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, webp, pdf. File too large: summary: Der Upload überschreitet das Limit von 10 MB value: front_image: - File size should not exceed 10 MB Invalid option value: summary: Optionen akzeptieren nur DECLINE oder NO_ACTION value: invalid_mrz_action: - '"REVIEW" is not a valid choice.' Encrypted PDF: summary: PDF ohne das erforderliche Passwort hochgeladen value: detail: >- The PDF is encrypted. Please upload a decrypted PDF or a photo instead. Wrong PDF password: summary: >- `front_image_password` / `back_image_password` entschlüsselt die PDF nicht value: detail: >- The PDF password is incorrect. Please provide the correct password. Document not recognized: summary: Im Bild konnte kein Ausweisdokument erkannt werden value: error: COULD_NOT_RECOGNIZE_DOCUMENT PDF conversion failure: summary: >- Hochgeladene PDF-Datei konnte nicht in ein Bild konvertiert werden value: error: Failed to convert front image PDF. '403': description: >- Zugriff verweigert. Wird zurückgegeben, wenn der Header `x-api-key` fehlt sowie wenn das Guthaben der aufrufenden Organisation den Aufruf nicht decken kann; ein falscher, widerrufener oder abgelaufener Schlüssel gibt `401` zurück. Ein fehlender Schlüssel gibt `403` mit `{"detail": ...}` zurück; ein falscher, widerrufener oder abgelaufener Schlüssel gibt `401` zurück. Unzureichende Credits geben `403` mit `{"error": ...}` zurück, bevor eine Bildverarbeitung stattfindet. content: application/json: examples: Missing or invalid API key: summary: >- Kein `x-api-key`-Header, oder der Schlüssel ist ungültig/widerrufen value: detail: You do not have permission to perform this action. Not enough credits: summary: >- Das Guthaben der Organisation reicht für den Aufruf nicht aus value: error: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me '429': description: >- Rate-Limit überschritten. POST/PATCH/DELETE-Endpoints teilen sich ein Budget von 300 Schreibanfragen pro Minute pro API-Schlüssel (Transaktionserstellungen und Ereignis-Ingestion haben ein separates Budget von 600). Die Antwort enthält die Header `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` und `Retry-After`. content: application/json: examples: Write rate limit exceeded: summary: Mehr als 300 Schreibanfragen in der aktuellen Minute value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. schema: type: object properties: detail: type: string '503': $ref: '#/components/responses/DocumentProcessingBusy' security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: cURL source: |- curl -X POST 'https://verification.didit.me/v3/id-verification/' \ -H 'x-api-key: YOUR_API_KEY' \ -F 'front_image=@./id_front.jpg' \ -F 'back_image=@./id_back.jpg' \ -F 'perform_document_liveness=true' \ -F 'save_api_request=true' \ -F 'vendor_data=user-123' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.id_verification.verify( front_image=open("front_image.jpg", "rb"), back_image=open("back_image.jpg", "rb"), perform_document_liveness=True, save_api_request=True, vendor_data="user-123", metadata={"flow": "onboarding"}, ) print(result) - lang: javascript label: Node.js source: |- import Didit, { fileFromPath } from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.idVerification.verify({ front_image: await fileFromPath("front_image.jpg"), back_image: await fileFromPath("back_image.jpg"), perform_document_liveness: true, save_api_request: true, vendor_data: "user-123", metadata: { flow: "onboarding" }, }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDVerification.Verify(ctx, didit.IDVerificationVerifyParams{\n\tFrontImage: didit.FileFromPath(\"front_image.jpg\"),\n\tBackImage: didit.Some(didit.FileFromPath(\"back_image.jpg\")),\n\tPerformDocumentLiveness: didit.Bool(true),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n\tMetadata: didit.Some(map[string]any{\"flow\": \"onboarding\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import java.nio.file.Path; import java.util.Map; import me.didit.Didit; import me.didit.types.IdVerificationVerifyParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.idVerification().verify(IdVerificationVerifyParams.builder() .frontImage(Path.of("front_image.jpg")) .backImage(Path.of("back_image.jpg")) .performDocumentLiveness(true) .saveApiRequest(true) .vendorData("user-123") .metadata(Map.of("flow", "onboarding")) .build()); System.out.println(result); - lang: php label: PHP source: |- idVerification->verify([ 'front_image' => File::fromPath('front_image.jpg'), 'back_image' => File::fromPath('back_image.jpg'), 'perform_document_liveness' => true, 'save_api_request' => true, 'vendor_data' => 'user-123', 'metadata' => ['flow' => 'onboarding'], ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.id_verification.verify( front_image: Pathname("front_image.jpg"), back_image: Pathname("back_image.jpg"), perform_document_liveness: true, save_api_request: true, vendor_data: "user-123", metadata: { flow: "onboarding" } ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Collections.Generic; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.IdVerification.VerifyAsync(new IdVerificationVerifyParams { FrontImage = FileUpload.FromPath("front_image.jpg"), BackImage = FileUpload.FromPath("back_image.jpg"), PerformDocumentLiveness = true, SaveApiRequest = true, VendorData = "user-123", Metadata = new Dictionary { ["flow"] = "onboarding" }, }); Console.WriteLine(JsonSerializer.Serialize(result)); components: responses: DocumentProcessingBusy: description: >- Zurzeit werden zu viele Dokumente verarbeitet, daher wurde dieser Upload nicht verarbeitet: Es wurde nichts gespeichert und kein Versuch verbraucht. Senden Sie dieselbe Datei nach der in `Retry-After` angegebenen Anzahl an Sekunden erneut. Verzweigen Sie anhand von `code`, nicht anhand des Nachrichtentexts. headers: Retry-After: description: >- Sekunden, die gewartet werden müssen, bevor dieselbe Anfrage erneut gesendet wird. schema: type: integer example: 10 content: application/json: schema: type: object required: - detail - code properties: detail: type: string code: type: string enum: - document_processing_busy example: detail: We are busy processing documents. Please try again in a moment. code: document_processing_busy securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- Der API-Schlüssel Ihrer Anwendung, aus Entwickler -> API-Schlüssel in der Business Console. Der Primärschlüssel hat Vollzugriff. Ein benannter Schlüssel kann im Geltungsbereich eingeschränkt werden: keine, Lese- oder Schreibberechtigung pro Ressource, beschränkt auf bestimmte Workflows oder genehmigte Sitzungen, auf eine Liste von IP-Adressen und auf ein Ablaufdatum. 401 bedeutet, dass der Schlüssel falsch, widerrufen oder abgelaufen ist; 403 bedeutet, dass kein Schlüssel gesendet wurde, der Schlüssel keinen Zugriff auf diese Ressource oder Aktion hat oder die Anfrage von einer Adresse außerhalb seiner IP-Liste stammte; 404 bei einer Sitzungsroute bedeutet, dass die Sitzung außerhalb der Workflows oder Status des Schlüssels liegt. Ein Schlüssel ohne Medienzugriff erhält Bild-, Video- und PDF-URLs als null, und ein Schlüssel ohne Schreibberechtigung für Sitzungen erhält Sitzungslinks und Token als null. Siehe https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.