> ## 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. # Datenbankvalidierungs-API: Abgleich nationaler ID > Didit prüft Identitätsdaten via POST /v3/database-validation/ gegen 100+ nationale und globale Quellen (1x1/2x2-Waterfall). Abrechnung pro Aufruf. ## Adressbasierte Dienste Für Dienste, die eine Wohn- oder Versorgungsadresse prüfen, können Sie eine einzelne `address` senden. Didit zerlegt sie vor der Prüfung. Für die beste Trefferquote übermitteln Sie die strukturierten Adressfelder von Didit direkt: | Feld | Bedeutung | | - | - | | `address_element_1` | Straßenadresse einschließlich Hausnummer und Straßentyp | | `address_element_2` | Optional: Wohnungs-, Gebäude- oder Etagennummer oder eine zusätzliche Adresszeile | | `address_element_3` | Ortsteil, Bezirk, Ortschaft oder Stadtviertel | | `address_element_4` | Stadt, Gemeinde, Bundesland, Provinz oder Region | | `address_element_5` | Postleitzahl | Strukturierte Felder überschreiben den Wert von `address`. `postal_code` wird als Alias für `address_element_5` akzeptiert. ## Einwilligung Einige Datenbankdienste erfordern die ausdrückliche Einwilligung des Endbenutzers, bevor der Anbieter abgefragt werden darf. Im Dienstkatalog sind diese Zeilen mit `requires_consent=true` gekennzeichnet. Senden Sie `consent=true`, wenn die Einwilligung des Benutzers für die ausgewählten Dienste gilt. Didit lehnt die Anfrage ab, bevor ein Anbieteraufruf oder ein Abrechnungsereignis erfolgt, wenn ein ausgewählter Dienst eine Einwilligung erfordert und Sie diese nicht übermitteln. ## Datei-Uploads Die Datenbankvalidierung verwendet `multipart/form-data`. Biometrische Dienste, die `selfie` erfordern, stellen dieses Feld im API-Playground als Datei-Upload-Feld bereit. Sie können ein Bild direkt auswählen, statt einen Pfad oder einen Base64-String einzufügen. Laden Sie die Datei im Code mit der üblichen Multipart-Syntax hoch: ```bash theme={null} -F "selfie=@./selfie.jpg" ``` ## Validierungsfehler Didit prüft Pflichtfelder, die Struktur der Adresse und dienstspezifische Formate, bevor der Anbieter aufgerufen wird. Zum Beispiel erwarten die chinesischen Registerdienste `chn_national_id` und `chn_passport_verification` den Wert `full_name` in chinesischer Originalschrift. `chn_national_id` verlangt außerdem eine gültige chinesische nationale Ausweisnummer mit 15 oder 18 Zeichen und einer korrekten Prüfsumme. Wenn eine Anfrage nicht ausgeführt werden kann, gibt die API eindeutige Feldfehler zurück und es wird keine Nutzung abgerechnet. Schlägt ein Anbieter nach der Vorabprüfung fehl, enthält die Antwort `validation_errors`. Bei gespeicherten API-Anfragen werden diese Fehler im Ergebnis der Datenbankvalidierung gespeichert. ## Abgelehnte Eingaben und nicht verfügbare Ergebnisse Wenn kein Dienst ein brauchbares Ergebnis liefert, prüfen Sie jeden Eintrag in `validation_errors`, bevor Sie entscheiden, ob Sie es erneut versuchen. Der HTTP-Statuscode allein entscheidet nicht, ob ein erneuter Versuch sinnvoll ist. Eine Antwort `400` mit `code: "provider_rejected_input"` und `retryable: false` bedeutet, dass jeder unbeantwortete Versuch die Eingabe ausdrücklich abgelehnt hat. Korrigieren Sie die übermittelten Daten, bevor Sie es erneut versuchen. Diese Versuche werden nicht abgerechnet. Eine Antwort `502` mit `code: "empty_provider_response"` und `retryable: true` bedeutet, dass der Dienst aus einem anderen Grund kein brauchbares Ergebnis liefern konnte. Dazu gehört eine abgelehnte Eingabe, auf die ein nicht verfügbarer Ausweichdienst folgt, oder ein Ausweichdienst, der keine Begründung liefert. Versuchen Sie es später erneut. Die Antwort belegt nicht, dass die Eingabe fehlerhaft ist. Wenn eine Datenbank dauerhaft ausfällt, sendet Didit den Organisationen, die sie kürzlich verwendet haben, eine E-Mail, sobald die Störung anhält, und eine weitere, sobald tatsächliche Prüfungen bestätigen, dass sie wieder antwortet (siehe [Verfügbarkeitsbenachrichtigungen](https://docs.didit.me/de/core-technology/database-validation/overview.md#benachrichtigungen-zur-verfügbarkeit)). Wenn nur einige der ausgewählten Dienste fehlschlagen, ist die Anfrage dennoch erfolgreich: Die Antwort hat den Statuscode `200`, und die fehlgeschlagenen Dienste werden unter `database_validation.errors[]` aufgelistet, jeweils mit denselben Feldern `code` und `retryable`. `database_validation.status` richtet sich dann nach den Diensten, die geantwortet haben, und kann `Approved` lauten. Prüfen Sie `errors[]` deshalb bei jeder Antwort und nicht nur bei einem Fehler `4xx` oder `5xx`. Ein dort gemeldeter Dienst fehlt in `validations` und `services_used` und wird nicht abgerechnet. Wiederholen Sie die Anfrage für diesen Dienst allein. Andere `502`-Fehler können korrigierte Eingaben erfordern. Zum Beispiel beschreiben `provider_invalid_input` und `provider_validation_error` Eingaben, die die Quelle abgelehnt hat. Sie dürfen nicht unverändert erneut gesendet werden, auch wenn die Legacy-Antwort kein `retryable` enthält. Die Hinweise zum erneuten Versuch bei `empty_provider_response` gelten für diese Codes nicht. Ein eindeutiges Ergebnis ohne Übereinstimmung ist eine abgeschlossene Prüfung und kein Verfügbarkeitsfehler. ## OpenAPI ````yaml de/openapi-25.json POST /v3/database-validation/ 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/database-validation/: post: tags: - Standalone APIs summary: Datenbankvalidierung (eigenständig) description: >- Validieren Sie die Identitätsdaten einer Person anhand offizieller Behörden- und Registerquellen – CPF in Brasilien, RENAPER in Argentinien, DNI-Register in Spanien und Peru, INE in Mexiko und 100+ weitere Dienste in 60+ Ländern. **Dienstauswahl.** Jedes Land stellt einen oder mehrere Katalogdienste bereit, die durch eine `service_id` identifiziert werden (z. B. `bra_cpf`, `arg_renaper`, `pan_cedula_sib`). Legen Sie die gewünschten Dienste mit dem Array `services` fest – wenn Sie es weglassen, wird genau **ein** Standarddienst ausgeführt (der am längsten etablierte Live-Dienst für das jeweilige Land). Das Senden von `services` schaltet die Antwort zudem auf das erweiterte Format mit `services_used` und `match_score` um. Dienste, ihre erforderlichen Felder und Preise können Sie über `GET /v1/organization/database-validation-countries/` (ein Katalog-Endpoint, der nicht in dieser Spezifikation dokumentiert ist) oder den Workflow-Editor der Business Console abrufen. Einige Dienste sind im Katalog mit `requires_consent=true` markiert und erfordern `consent=true`; andere erfordern ein Onboarding für Ihre Organisation, bevor sie aufgerufen werden können. **Eingabefelder.** `identification_number` ist ein universelles Feld, das automatisch dem passenden länderspezifischen Feld zugeordnet wird (siehe Beschreibung). Formatregeln der Länder werden durchgesetzt, bevor ein Anbieter aufgerufen wird (z. B. muss BRA CPF genau 11 Ziffern lang sein), und Formatfehler werden niemals in Rechnung gestellt. Biometrische Dienste erfordern den Upload eines `selfie` (nur als Multipart); Argentinien RENAPER erfordert zusätzlich `gender`. **Ergebnisse.** Jeder Dienst gibt ein feldweises `validation`-Mapping sowie einen anbieterneutralen `outcome_code` zurück (`MATCH`, `PARTIAL_MATCH`, `NO_MATCH`, `DOCUMENT_NOT_FOUND`, `INVALID_DOCUMENT_FORMAT`, `INVALID_INPUT`, `MINOR_BLOCKED`, `DECEASED`, `BIOMETRIC_NO_MATCH`, `BIOMETRIC_IMAGE_UNUSABLE`, `INCONCLUSIVE`, `DOCUMENT_SUPERSEDED`, `REGISTRY_UNAVAILABLE`, `REGISTRY_ERROR`). Beachten Sie die Unterschiede: `NO_MATCH` ist eine definitive Nichtübereinstimmung, `INCONCLUSIVE` bedeutet, dass das Register weder bestätigen noch verwerfen konnte (manuelle Prüfung, keine Ablehnung), und `BIOMETRIC_IMAGE_UNUSABLE` ist ein technisches Problem mit dem Selfie (erneut aufnehmen), im Gegensatz zum definitiven `BIOMETRIC_NO_MATCH`. Der übergeordnete `match_type` aggregiert über alle Dienste (jede vollständige → `full_match`, sonst jede teilweise → `partial_match`, sonst `no_match`), und `no_match_action`/`partial_match_action` übersetzen ihn in den endgültigen `status`. `validation_type` wird abgeleitet: `two_by_two`, wenn zwei oder mehr unterschiedliche Dienste eine vollständige Übereinstimmung geliefert haben (bei der Identifikationsnummer, bei vollständigem Namen + Geburtsdatum zusammen oder bei der Adresse ohne Widersprüche), andernfalls `one_by_one`. **Persistenz.** `save_api_request` ist standardmäßig **true**: Das Ergebnis wird als Sitzung gespeichert (`request_id` funktioniert mit `GET /v3/session/{sessionId}/decision/`), erscheint in der Console und löst ein `status.updated`-Webhook-Ereignis aus. Es steuert auch das Format von `validations` – dienstspezifische Objekte beim Speichern, ein zusammengeführtes `{field: match}`-Mapping, wenn nicht gespeichert wird. **Abrechnung.** Pro Dienst: Jedem Dienst, der ein abrechenbares Ergebnis zurückgibt, wird sein eigener Katalogpreis berechnet. Fehlgeschlagene oder übersprungene Dienste werden nicht abgerechnet, und mit `400` abgewiesene Anfragen kosten nichts. Die vorab durchgeführte Guthabenprüfung deckt die Summe der Preise der ausgewählten Dienste ab (`403` bei unzureichendem Guthaben). **Fehler.** Wenn kein ausgewählter Dienst ein nutzbares Ergebnis zurückgibt, gibt die API `400` mit `validation_errors` zurück, sofern jeder unbeantwortete Versuch die Eingabe explizit abgelehnt hat (`provider_rejected_input`, `retryable: false`). Korrigieren Sie die Eingabe, bevor Sie es erneut versuchen. Andernfalls gibt sie `502` mit `validation_errors` zurück (`empty_provider_response`, `retryable: true`), einschließlich gemischter Eingabeablehnungen und nicht verfügbarer Fallback-Versuche; es wird nichts abgerechnet (eine Sitzung wird weiterhin mit dem Status `Not Finished` erfasst, wenn `save_api_request=true`). Wenn nur einige Dienste fehlschlagen, enthält die `200`-Antwort deren Fehler in `database_validation.errors`. **Sandbox.** Schlüssel aus Sandbox-Anwendungen überspringen die Registeraufrufe sowie die Abrechnung und geben eine statische `full_match`-Antwort zurück – die Sandbox-Payload enthält immer `services_used` und `match_score: 100`, unabhängig davon, wie `services` übermittelt wurde. Validieren Sie daher weder die Aktivierung des erweiterten Live-Formats noch den `match_score`-Bruchwert im Bereich von 0.0–1.0 anhand von Sandbox-Antworten. Senden Sie die Anfrage als `application/json`, oder als `multipart/form-data`, wenn Sie ein `selfie` hochladen. operationId: post_v3database-validation parameters: [] requestBody: required: true content: application/json: schema: type: object required: - issuing_state properties: issuing_state: type: string description: >- ISO 3166-1-**Alpha-3**-Ländercode des Registers, anhand dessen validiert werden soll (z. B. `BRA`, `ESP`, `COL`). Bestimmt, welche Dienste verfügbar sind. Nicht unterstützte Codes geben `400` mit der vollständigen Liste der gültigen Optionen zurück. example: BRA services: type: array items: type: string description: >- Katalog-`service_id`s, die für dieses Land ausgeführt werden sollen (z. B. `["bra_cpf"]`). Akzeptiert auch eine einzelne Zeichenkette oder eine kommagetrennte/JSON-codierte Zeichenkette. **Wird sie weggelassen oder ist sie leer, wird genau ein Standarddienst ausgeführt** — der am längsten etablierte Live-Dienst für das Land; neuere, biometrische und nutzungsbasierte Dienste müssen explizit benannt werden. Das Senden von `services` stellt die Antwort auf die erweiterte Struktur um (fügt `services_used` und `match_score` hinzu). Jede ID muss für den `issuing_state` existieren und live sein; Dienste, die ein Onboarding erfordern, geben `400` zurück, bis sie für Ihre Organisation aktiviert sind. Entdecken Sie verfügbare Dienste pro Land über `GET /v1/organization/database-validation-countries/` (ein Katalog-Endpoint, der in dieser Spezifikation nicht dokumentiert ist) oder den Workflow-Editor der Business Console. example: - bra_cpf validation_type: type: string deprecated: true description: >- VERALTET. Aus Gründen der Abwärtskompatibilität akzeptiert, aber ignoriert – der `validation_type` der Antwort wird jetzt daraus abgeleitet, wie viele Dienste eine vollständige Übereinstimmung ergaben. Verwenden Sie `services`, um bestimmte Dienste festzulegen. consent: type: boolean default: false description: >- Auf `true` setzen, wenn der Endbenutzer ausdrücklich in die ausgewählten Validierungsdienste eingewilligt hat. Erforderlich für Dienste, die im Katalog mit `requires_consent=true` gekennzeichnet sind – ohne dies geben diese Dienste `400` mit `services_requiring_consent` zurück. identification_number: type: string description: >- Universelle Identifikationsnummer — wird automatisch dem korrekten länderspezifischen Feld zugeordnet, sodass Sie sie anstelle von `personal_number`/`tax_number`/`document_number` verwenden können: ARG→document_number (DNI), BOL→document_number (CI), BRA→tax_number (CPF, 11 Ziffern), CHL→personal_number (RUT), COL→personal_number (Cédula), CRI→personal_number (Cédula), DOM→personal_number (Cédula, 11 Ziffern), ECU→personal_number (Cédula, 10 Ziffern), ESP→personal_number (DNI/NIE), GTM→document_number (DPI), HND→document_number (DNI), MEX→personal_number (CURP, 18 Zeichen), PAN→personal_number (Cédula), PER→personal_number (DNI, 8 Ziffern), PRY→document_number (CI), SLV→document_number (DUI), URY→personal_number (CI), VEN→document_number (Cédula). Sie überschreibt niemals ein explizit angegebenes länderspezifisches Feld. first_name: type: string description: >- Der Vorname der Person. Von einigen Diensten/Ländern erforderlich. example: John last_name: type: string description: >- Der Nachname der Person. Von einigen Diensten/Ländern erforderlich. example: Doe middle_name: type: string description: >- Zweitname, der von einigen Länderdiensten verwendet wird (AUS, NZL, …). full_name: type: string description: >- Vollständiger Name – einige Dienste akzeptieren diesen anstelle von Vor-/Nachname (z. B. CHN-Dienste, die den Namen im nativen Schriftsystem abgleichen). date_of_birth: type: string format: date description: Geburtsdatum, `YYYY-MM-DD`. Von vielen Diensten verlangt. example: '1980-01-01' personal_number: type: string description: >- Staatlich ausgestellte eindeutige Personen-ID. Verwendet von: CHL (RUT), COL (Cédula), CRI, DOM, ECU, ESP (DNI/NIE), MEX (CURP), PAN (Cédula), PER (DNI), URY. Ziehen Sie stattdessen `identification_number` in Betracht. tax_number: type: string description: >- Steueridentifikationsnummer. Verwendet von: BRA (CPF, 11 Ziffern). Ziehen Sie stattdessen `identification_number` in Betracht. document_number: type: string description: >- Dokumentennummer. Verwendet von: ARG (DNI), BOL (CI), GTM (DPI), HND (DNI), PRY (CI), SLV (DUI), VEN (Cédula). Ziehen Sie stattdessen `identification_number` in Betracht. document_type: type: string enum: - P - DL - ID - RP - SSC - HIC - WP - TC - VISA - PSC - BC - OTHER description: >- Art des validierten Dokuments: `P` Reisepass, `DL` Führerschein, `ID` Personalausweis, `RP` Aufenthaltstitel (sowie `SSC`, `HIC`, `WP`, `TC`, `VISA`, `PSC`, `BC`, `OTHER`). Erforderlich für einige Dienste (z. B. ESP). expiration_date: type: string format: date description: >- Dokumentenablaufdatum, `YYYY-MM-DD`. Erforderlich für die ESP-Validierung (Spanien). example: '2030-01-15' date_of_issue: type: string format: date description: >- Dokumentenausstellungsdatum, `YYYY-MM-DD` (fecha de expedición). Erforderlich für die COL-Validierung der Cédula (Kolumbien). example: '2015-06-20' nationality: type: string description: >- Staatsangehörigkeit nach ISO 3166-1 alpha-3. Von einigen Diensten benötigt. gender: type: string enum: - M - F - X description: >- Geschlecht: `M`, `F` oder `X` (sonstiges/unbekannt). Erforderlich für die argentinische RENAPER-Validierung (`arg_renaper`). address: description: >- Wohnadresse. Bevorzugen Sie das strukturierte Objekt `{"street_1":"123 Main St","street_2":"Apt 4B","city":"Springfield","region":"IL","postal_code":"62701","country":"US"}`; ein vollständiger einzeiliger String wird weiterhin akzeptiert. Erforderlich für Adressverifizierungsdienste; wenn ein Dienst Adressanforderungen definiert, geben fehlende Teile `400` mit `address_fields_required_by` zurück. oneOf: - type: object properties: street_1: type: string street_2: type: string city: type: string region: type: string postal_code: type: string country: type: string - type: string description: Vollständige einzeilige Adresse (Legacy). address_element_1: type: string description: >- Straßenadresse einschließlich Hausnummer und Straßentyp. Falls weggelassen, wird sie aus `address` abgeleitet. address_element_2: type: string description: >- Wohnung, Einheit, Gebäude, Etage oder zusätzliche Adresszeile. Nur senden, wenn explizit vorhanden. address_element_3: type: string description: >- Stadt, Vorort, Bezirk, Ortschaft oder Stadtteil. Falls weggelassen, wird der Wert aus `address` abgeleitet. address_element_4: type: string description: >- Bundesland, Provinz, Region oder Ort. Falls weggelassen, abgeleitet aus `address`. address_element_5: type: string description: Postleitzahl. `postal_code` wird als Alias akzeptiert. postal_code: type: string description: >- Postleitzahl für adressbasierte Dienste (Alias von `address_element_5`). driver_license_number: type: string description: >- Führerscheinnummer für staatliche Dokumentenprüfungsdienste (AUS, NZL, IND). driver_license_card_number: type: string description: >- Physische Führerscheinkartennummer, sofern separat von der Führerscheinnummer erforderlich (AUS). driver_license_state: type: string description: Ausstellungsstaat oder -territorium des Führerscheins (AUS). driver_license_version: type: string description: Führerschein-Versionscode (NZL). passport_number: type: string description: >- Reisepassnummer für behördliche Reisepass-Verifizierungsdienste (AUS, NZL, IND, CHN). passport_expiration_date: type: string format: date description: >- Ablaufdatum des Reisepasses, `YYYY-MM-DD`, für Reisepass-Verifizierungsdienste. passport_file_number: type: string description: Reisepass-Aktenzeichen (IND). passport_issue_country: type: string description: >- Ausstellungsland des Reisepasses (ISO 3166-1 Alpha-3) für Passverifizierungsdienste. medicare_card_number: type: string description: Medicare-Kartennummer (AUS). immi_card_number: type: string description: Nummer der australischen ImmiCard. immi_card_expiry_date: type: string format: date description: Ablaufdatum der australischen ImmiCard. citizenship_certificate_number: type: string description: Staatsbürgerschaftszertifikatsnummer (AUS). birth_registration_number: type: string description: Registrierungsnummer der Geburtsurkunde (AUS). birth_registration_date: type: string format: date description: Registrierungsdatum der Geburtsurkunde (AUS). birth_registration_state: type: string description: Registrierungsstaat der Geburtsurkunde (AUS). marriage_certificate_number: type: string description: Nummer der Heiratsurkunde (AUS). change_of_name_certificate_number: type: string description: Nummer der Namensänderungsurkunde (AUS). first_partner_name: type: string description: Vorname des Partners auf einer Heiratsurkunde (AUS). last_partner_name: type: string description: Nachname des Partners auf einer Heiratsurkunde (AUS). voter_id: type: string description: Wählerregisternummer (IND EPIC, IRL). epic_card: type: string description: Indische EPIC-Wählerausweisnummer. pan: type: string description: Indische PAN (Permanent Account Number). national_id: type: string description: >- Nationale Identifikationsnummer (CHN, MYS, KEN, KHM, NGA, ZAF, …). cic: type: string description: >- Mexikanischer INE/IFE Código de Identificación de Credencial (CIC), 9 Ziffern. Wird vom mexikanischen INE-Ausweisgültigkeitsdienst (`mex_ine_vigencia`) verwendet. identificador_ciudadano: type: string description: >- Mexikanischer INE Identificador del Ciudadano (9 Ziffern). Wird zusammen mit `cic` für moderne INE-Modelle (E/F/G/H) in `mex_ine_vigencia` verwendet. ocr: type: string description: >- Mexikanische INE-OCR-Nummer (13 Ziffern, Rückseite der Karte). Wird zusammen mit `cic` für Modell D in `mex_ine_vigencia` verwendet. voter_number: type: string description: >- Mexikanische INE Clave de Elector (18 Zeichen). Wird zusammen mit `emission_number` für ältere IFE-Modelle (A/B/C) in `mex_ine_vigencia` verwendet. emission_number: type: string description: >- Mexikanische INE Número de Emisión. Wird zusammen mit `voter_number` für ältere IFE-Modelle (A/B/C) in `mex_ine_vigencia` verwendet. bvn: type: string description: Nigerianische Bank Verification Number. bank_card_number: type: string description: Bankkartennummer (CHN-Bankkartenverifizierung). company_registration_number: type: string description: >- Vom Unternehmensregister ausgestellte Unternehmensregisternummer: der CNPJ in Brasilien (z. B. `11222333000181`), die Registernummer in Südafrika (z. B. `1936/007721/06`). Erforderlich für die Dienste für Unternehmensregister und Unternehmensgeschäftsführer (`bra_company_registry`, `bra_company_directors`, `zaf_company_registry`, `zaf_company_directors`). company_name: type: string description: >- Eingetragener Unternehmensname, abgeglichen mit dem Registereintrag. Optional für `zaf_company_registry`. initials: type: string description: >- Die Initialen der Person, wie auf dem Dokument aufgedruckt. Erforderlich für `zaf_drivers_license`; akzeptiert von `zaf_bank_account_holder`. licence_number: type: string description: >- Führerscheinnummer wie auf der Karte aufgedruckt, für `zaf_drivers_license`. Bei Weglassen wird `document_number` verwendet. refugee_file_number: type: string description: >- Flüchtlingsaktennummer, ausgestellt vom Department of Home Affairs in Südafrika. Erforderlich für `zaf_refugee`. bank_name: type: string description: >- Name der kontoführenden Bank. Erforderlich für `zaf_bank_account_holder`. bank_account_number: type: string description: >- Bankkontonummer. Erforderlich für `zaf_bank_account_holder`; akzeptiert von `zaf_fraud_prevention`. account_type: type: string description: >- Bankkontotyp für `zaf_bank_account_holder`: `current`, `savings`, `transmission`, `subscriptionShare` oder `notKnown`, ohne Berücksichtigung der Groß-/Kleinschreibung. Jeder andere Wert gibt `400` zurück. Lassen Sie das Feld weg, wenn Sie den Typ nicht kennen: Der Kontotyp-Abgleich wird dann als nicht bestätigt gemeldet. phone_number: type: string description: >- Mobiltelefonnummer des Kontakts für die Dienste, die die Erreichbarkeit überprüfen (`zaf_bank_account_holder`, `zaf_fraud_prevention`, `zaf_refugee`). right_thumb: type: string description: >- Base64-kodierter rechter Daumenabdruck für `zaf_dha_fingerprint_match`, zusammen mit `left_thumb` oder alleinstehend. left_thumb: type: string description: >- Base64-kodierter linker Daumenabdruck für `zaf_dha_fingerprint_match`, zusammen mit `right_thumb` oder alleinstehend. score_level: type: integer description: >- Minimale biometrische Score-Stufe für `zaf_criminal_face_screening`. Standardwert ist `3`. max_matches: type: integer description: >- Maximale Anzahl potenzieller Treffer, die `zaf_criminal_face_screening` zurückgibt. Standardwert ist `1`. vehicle_register_number: type: string description: >- Fahrzeugregisternummer. Erforderlich, zusammen mit `vehicle_licence_plate` und `vin`, für `zaf_vehicle_ownership`. vehicle_licence_plate: type: string description: >- Kfz-Kennzeichen. Erforderlich, zusammen mit `vehicle_register_number` und `vin`, für `zaf_vehicle_ownership`. vin: type: string description: >- Fahrzeug-Identifizierungsnummer (FIN bzw. Fahrgestellnummer). Erforderlich, zusammen mit `vehicle_register_number` und `vehicle_licence_plate`, für `zaf_vehicle_ownership`. ssn: type: string description: Social Security Number (USA). phone: type: string description: Telefonnummer für Telefonverifizierungsdienste. landline: type: string description: Festnetznummer für Telefonverifizierungsdienste. email: type: string format: email description: E-Mail-Adresse für Identitätsverifizierungsdienste. country_of_residence: type: string description: >- ISO 3166-1-Alpha-2-Wohnsitzland. Wird von globalen Identitätsanreicherungsdiensten (z. B. `glb_identity_enrichment`) verwendet, um die Abfrage einzugrenzen. example: US partial_match_action: type: string enum: - DECLINE - NO_ACTION default: NO_ACTION description: >- Auswirkung von `partial_match` auf `database_validation.status`. Standardwert ist `NO_ACTION` (Status bleibt `Approved`, mit einer Warnung). no_match_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- Auswirkung von `no_match` auf `database_validation.status`. Standardwert ist `DECLINE`. save_api_request: type: boolean default: true description: >- Die Validierung als Sitzung beibehalten (Sichtbarkeit in der Konsole, Entscheidungs-Endpoint, `status.updated`-Webhook). Ändert auch die Struktur der `validations`-Antwort: Pro-Dienst-Objekte bei `true` (Standard), eine zusammengeführte Feldzuordnung bei `false`. vendor_data: type: string description: >- Ihre Kennung für den validierten Benutzer; wird zurückgegeben und mit der Sitzung gespeichert. metadata: type: object nullable: true description: >- Freiform-JSON, das mit der Anfrage gespeichert und zurückgegeben wird. example: issuing_state: BRA services: - bra_cpf identification_number: '12345678900' first_name: John last_name: Doe date_of_birth: '1980-01-01' vendor_data: user-1234 multipart/form-data: schema: type: object required: - issuing_state properties: issuing_state: type: string description: >- ISO 3166-1-**Alpha-3**-Ländercode des Registers, anhand dessen validiert werden soll (z. B. `BRA`, `ESP`, `COL`). Bestimmt, welche Dienste verfügbar sind. Nicht unterstützte Codes geben `400` mit der vollständigen Liste der gültigen Optionen zurück. example: BRA services: type: array items: type: string description: >- Katalog-`service_id`s, die für dieses Land ausgeführt werden sollen (z. B. `["bra_cpf"]`). Akzeptiert auch eine einzelne Zeichenkette oder eine kommagetrennte/JSON-codierte Zeichenkette. **Wird sie weggelassen oder ist sie leer, wird genau ein Standarddienst ausgeführt** — der am längsten etablierte Live-Dienst für das Land; neuere, biometrische und nutzungsbasierte Dienste müssen explizit benannt werden. Das Senden von `services` stellt die Antwort auf die erweiterte Struktur um (fügt `services_used` und `match_score` hinzu). Jede ID muss für den `issuing_state` existieren und live sein; Dienste, die ein Onboarding erfordern, geben `400` zurück, bis sie für Ihre Organisation aktiviert sind. Entdecken Sie verfügbare Dienste pro Land über `GET /v1/organization/database-validation-countries/` (ein Katalog-Endpoint, der in dieser Spezifikation nicht dokumentiert ist) oder den Workflow-Editor der Business Console. example: - bra_cpf validation_type: type: string deprecated: true description: >- VERALTET. Aus Gründen der Abwärtskompatibilität akzeptiert, aber ignoriert – der `validation_type` der Antwort wird jetzt daraus abgeleitet, wie viele Dienste eine vollständige Übereinstimmung ergaben. Verwenden Sie `services`, um bestimmte Dienste festzulegen. consent: type: boolean default: false description: >- Auf `true` setzen, wenn der Endbenutzer ausdrücklich in die ausgewählten Validierungsdienste eingewilligt hat. Erforderlich für Dienste, die im Katalog mit `requires_consent=true` gekennzeichnet sind – ohne dies geben diese Dienste `400` mit `services_requiring_consent` zurück. identification_number: type: string description: >- Universelle Identifikationsnummer — wird automatisch dem korrekten länderspezifischen Feld zugeordnet, sodass Sie sie anstelle von `personal_number`/`tax_number`/`document_number` verwenden können: ARG→document_number (DNI), BOL→document_number (CI), BRA→tax_number (CPF, 11 Ziffern), CHL→personal_number (RUT), COL→personal_number (Cédula), CRI→personal_number (Cédula), DOM→personal_number (Cédula, 11 Ziffern), ECU→personal_number (Cédula, 10 Ziffern), ESP→personal_number (DNI/NIE), GTM→document_number (DPI), HND→document_number (DNI), MEX→personal_number (CURP, 18 Zeichen), PAN→personal_number (Cédula), PER→personal_number (DNI, 8 Ziffern), PRY→document_number (CI), SLV→document_number (DUI), URY→personal_number (CI), VEN→document_number (Cédula). Sie überschreibt niemals ein explizit angegebenes länderspezifisches Feld. first_name: type: string description: >- Der Vorname der Person. Von einigen Diensten/Ländern erforderlich. example: John last_name: type: string description: >- Der Nachname der Person. Von einigen Diensten/Ländern erforderlich. example: Doe middle_name: type: string description: >- Zweitname, der von einigen Länderdiensten verwendet wird (AUS, NZL, …). full_name: type: string description: >- Vollständiger Name – einige Dienste akzeptieren diesen anstelle von Vor-/Nachname (z. B. CHN-Dienste, die den Namen im nativen Schriftsystem abgleichen). date_of_birth: type: string format: date description: Geburtsdatum, `YYYY-MM-DD`. Von vielen Diensten verlangt. example: '1980-01-01' personal_number: type: string description: >- Staatlich ausgestellte eindeutige Personen-ID. Verwendet von: CHL (RUT), COL (Cédula), CRI, DOM, ECU, ESP (DNI/NIE), MEX (CURP), PAN (Cédula), PER (DNI), URY. Ziehen Sie stattdessen `identification_number` in Betracht. tax_number: type: string description: >- Steueridentifikationsnummer. Verwendet von: BRA (CPF, 11 Ziffern). Ziehen Sie stattdessen `identification_number` in Betracht. document_number: type: string description: >- Dokumentennummer. Verwendet von: ARG (DNI), BOL (CI), GTM (DPI), HND (DNI), PRY (CI), SLV (DUI), VEN (Cédula). Ziehen Sie stattdessen `identification_number` in Betracht. document_type: type: string enum: - P - DL - ID - RP - SSC - HIC - WP - TC - VISA - PSC - BC - OTHER description: >- Art des validierten Dokuments: `P` Reisepass, `DL` Führerschein, `ID` Personalausweis, `RP` Aufenthaltstitel (sowie `SSC`, `HIC`, `WP`, `TC`, `VISA`, `PSC`, `BC`, `OTHER`). Erforderlich für einige Dienste (z. B. ESP). expiration_date: type: string format: date description: >- Dokumentenablaufdatum, `YYYY-MM-DD`. Erforderlich für die ESP-Validierung (Spanien). example: '2030-01-15' date_of_issue: type: string format: date description: >- Dokumentenausstellungsdatum, `YYYY-MM-DD` (fecha de expedición). Erforderlich für die COL-Validierung der Cédula (Kolumbien). example: '2015-06-20' nationality: type: string description: >- Staatsangehörigkeit nach ISO 3166-1 alpha-3. Von einigen Diensten benötigt. gender: type: string enum: - M - F - X description: >- Geschlecht: `M`, `F` oder `X` (sonstiges/unbekannt). Erforderlich für die argentinische RENAPER-Validierung (`arg_renaper`). address: description: >- Wohnadresse. Bevorzugen Sie das strukturierte Objekt `{"street_1":"123 Main St","street_2":"Apt 4B","city":"Springfield","region":"IL","postal_code":"62701","country":"US"}`; ein vollständiger einzeiliger String wird weiterhin akzeptiert. Erforderlich für Adressverifizierungsdienste; wenn ein Dienst Adressanforderungen definiert, geben fehlende Teile `400` mit `address_fields_required_by` zurück. oneOf: - type: object properties: street_1: type: string street_2: type: string city: type: string region: type: string postal_code: type: string country: type: string - type: string description: Vollständige einzeilige Adresse (Legacy). address_element_1: type: string description: >- Straßenadresse einschließlich Hausnummer und Straßentyp. Falls weggelassen, wird sie aus `address` abgeleitet. address_element_2: type: string description: >- Wohnung, Einheit, Gebäude, Etage oder zusätzliche Adresszeile. Nur senden, wenn explizit vorhanden. address_element_3: type: string description: >- Stadt, Vorort, Bezirk, Ortschaft oder Stadtteil. Falls weggelassen, wird der Wert aus `address` abgeleitet. address_element_4: type: string description: >- Bundesland, Provinz, Region oder Ort. Falls weggelassen, abgeleitet aus `address`. address_element_5: type: string description: Postleitzahl. `postal_code` wird als Alias akzeptiert. postal_code: type: string description: >- Postleitzahl für adressbasierte Dienste (Alias von `address_element_5`). driver_license_number: type: string description: >- Führerscheinnummer für staatliche Dokumentenprüfungsdienste (AUS, NZL, IND). driver_license_card_number: type: string description: >- Physische Führerscheinkartennummer, sofern separat von der Führerscheinnummer erforderlich (AUS). driver_license_state: type: string description: Ausstellungsstaat oder -territorium des Führerscheins (AUS). driver_license_version: type: string description: Führerschein-Versionscode (NZL). passport_number: type: string description: >- Reisepassnummer für behördliche Reisepass-Verifizierungsdienste (AUS, NZL, IND, CHN). passport_expiration_date: type: string format: date description: >- Ablaufdatum des Reisepasses, `YYYY-MM-DD`, für Reisepass-Verifizierungsdienste. passport_file_number: type: string description: Reisepass-Aktenzeichen (IND). passport_issue_country: type: string description: >- Ausstellungsland des Reisepasses (ISO 3166-1 Alpha-3) für Passverifizierungsdienste. medicare_card_number: type: string description: Medicare-Kartennummer (AUS). immi_card_number: type: string description: Nummer der australischen ImmiCard. immi_card_expiry_date: type: string format: date description: Ablaufdatum der australischen ImmiCard. citizenship_certificate_number: type: string description: Staatsbürgerschaftszertifikatsnummer (AUS). birth_registration_number: type: string description: Registrierungsnummer der Geburtsurkunde (AUS). birth_registration_date: type: string format: date description: Registrierungsdatum der Geburtsurkunde (AUS). birth_registration_state: type: string description: Registrierungsstaat der Geburtsurkunde (AUS). marriage_certificate_number: type: string description: Nummer der Heiratsurkunde (AUS). change_of_name_certificate_number: type: string description: Nummer der Namensänderungsurkunde (AUS). first_partner_name: type: string description: Vorname des Partners auf einer Heiratsurkunde (AUS). last_partner_name: type: string description: Nachname des Partners auf einer Heiratsurkunde (AUS). voter_id: type: string description: Wählerregisternummer (IND EPIC, IRL). epic_card: type: string description: Indische EPIC-Wählerausweisnummer. pan: type: string description: Indische PAN (Permanent Account Number). national_id: type: string description: >- Nationale Identifikationsnummer (CHN, MYS, KEN, KHM, NGA, ZAF, …). cic: type: string description: >- Mexikanischer INE/IFE Código de Identificación de Credencial (CIC), 9 Ziffern. Wird vom mexikanischen INE-Ausweisgültigkeitsdienst (`mex_ine_vigencia`) verwendet. identificador_ciudadano: type: string description: >- Mexikanischer INE Identificador del Ciudadano (9 Ziffern). Wird zusammen mit `cic` für moderne INE-Modelle (E/F/G/H) in `mex_ine_vigencia` verwendet. ocr: type: string description: >- Mexikanische INE-OCR-Nummer (13 Ziffern, Rückseite der Karte). Wird zusammen mit `cic` für Modell D in `mex_ine_vigencia` verwendet. voter_number: type: string description: >- Mexikanische INE Clave de Elector (18 Zeichen). Wird zusammen mit `emission_number` für ältere IFE-Modelle (A/B/C) in `mex_ine_vigencia` verwendet. emission_number: type: string description: >- Mexikanische INE Número de Emisión. Wird zusammen mit `voter_number` für ältere IFE-Modelle (A/B/C) in `mex_ine_vigencia` verwendet. bvn: type: string description: Nigerianische Bank Verification Number. bank_card_number: type: string description: Bankkartennummer (CHN-Bankkartenverifizierung). company_registration_number: type: string description: >- Vom Unternehmensregister ausgestellte Unternehmensregisternummer: der CNPJ in Brasilien (z. B. `11222333000181`), die Registernummer in Südafrika (z. B. `1936/007721/06`). Erforderlich für die Dienste für Unternehmensregister und Unternehmensgeschäftsführer (`bra_company_registry`, `bra_company_directors`, `zaf_company_registry`, `zaf_company_directors`). company_name: type: string description: >- Eingetragener Unternehmensname, abgeglichen mit dem Registereintrag. Optional für `zaf_company_registry`. initials: type: string description: >- Die Initialen der Person, wie auf dem Dokument aufgedruckt. Erforderlich für `zaf_drivers_license`; akzeptiert von `zaf_bank_account_holder`. licence_number: type: string description: >- Führerscheinnummer wie auf der Karte aufgedruckt, für `zaf_drivers_license`. Bei Weglassen wird `document_number` verwendet. refugee_file_number: type: string description: >- Flüchtlingsaktennummer, ausgestellt vom Department of Home Affairs in Südafrika. Erforderlich für `zaf_refugee`. bank_name: type: string description: >- Name der kontoführenden Bank. Erforderlich für `zaf_bank_account_holder`. bank_account_number: type: string description: >- Bankkontonummer. Erforderlich für `zaf_bank_account_holder`; akzeptiert von `zaf_fraud_prevention`. account_type: type: string description: >- Bankkontotyp für `zaf_bank_account_holder`: `current`, `savings`, `transmission`, `subscriptionShare` oder `notKnown`, ohne Berücksichtigung der Groß-/Kleinschreibung. Jeder andere Wert gibt `400` zurück. Lassen Sie das Feld weg, wenn Sie den Typ nicht kennen: Der Kontotyp-Abgleich wird dann als nicht bestätigt gemeldet. phone_number: type: string description: >- Mobiltelefonnummer des Kontakts für die Dienste, die die Erreichbarkeit überprüfen (`zaf_bank_account_holder`, `zaf_fraud_prevention`, `zaf_refugee`). right_thumb: type: string description: >- Base64-kodierter rechter Daumenabdruck für `zaf_dha_fingerprint_match`, zusammen mit `left_thumb` oder alleinstehend. left_thumb: type: string description: >- Base64-kodierter linker Daumenabdruck für `zaf_dha_fingerprint_match`, zusammen mit `right_thumb` oder alleinstehend. score_level: type: integer description: >- Minimale biometrische Score-Stufe für `zaf_criminal_face_screening`. Standardwert ist `3`. max_matches: type: integer description: >- Maximale Anzahl potenzieller Treffer, die `zaf_criminal_face_screening` zurückgibt. Standardwert ist `1`. vehicle_register_number: type: string description: >- Fahrzeugregisternummer. Erforderlich, zusammen mit `vehicle_licence_plate` und `vin`, für `zaf_vehicle_ownership`. vehicle_licence_plate: type: string description: >- Kfz-Kennzeichen. Erforderlich, zusammen mit `vehicle_register_number` und `vin`, für `zaf_vehicle_ownership`. vin: type: string description: >- Fahrzeug-Identifizierungsnummer (FIN bzw. Fahrgestellnummer). Erforderlich, zusammen mit `vehicle_register_number` und `vehicle_licence_plate`, für `zaf_vehicle_ownership`. ssn: type: string description: Social Security Number (USA). phone: type: string description: Telefonnummer für Telefonverifizierungsdienste. landline: type: string description: Festnetznummer für Telefonverifizierungsdienste. email: type: string format: email description: E-Mail-Adresse für Identitätsverifizierungsdienste. country_of_residence: type: string description: >- ISO 3166-1-Alpha-2-Wohnsitzland. Wird von globalen Identitätsanreicherungsdiensten (z. B. `glb_identity_enrichment`) verwendet, um die Abfrage einzugrenzen. example: US partial_match_action: type: string enum: - DECLINE - NO_ACTION default: NO_ACTION description: >- Auswirkung von `partial_match` auf `database_validation.status`. Standardwert ist `NO_ACTION` (Status bleibt `Approved`, mit einer Warnung). no_match_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- Auswirkung von `no_match` auf `database_validation.status`. Standardwert ist `DECLINE`. save_api_request: type: boolean default: true description: >- Die Validierung als Sitzung beibehalten (Sichtbarkeit in der Konsole, Entscheidungs-Endpoint, `status.updated`-Webhook). Ändert auch die Struktur der `validations`-Antwort: Pro-Dienst-Objekte bei `true` (Standard), eine zusammengeführte Feldzuordnung bei `false`. vendor_data: type: string description: >- Ihre Kennung für den validierten Benutzer; wird zurückgegeben und mit der Sitzung gespeichert. metadata: type: object nullable: true description: >- Freiform-JSON, das mit der Anfrage gespeichert und zurückgegeben wird. selfie: type: string format: binary description: >- Selfie-Bild (`jpg`, `jpeg`, `png`, `webp`; max. 2 MB – Bilder werden vor dem Hochladen in das Register auf ~1,5 MB komprimiert) für biometrische Validierungsdienste, z. B. argentinische RENAPER (`arg_renaper`) und Panama SIB (`pan_cedula_sib`, `pan_cedula_sib_plus`). Erforderlich, wenn ein ausgewählter Dienst dies als Pflichtfeld auflistet. Nur über `multipart/form-data` verfügbar. responses: '200': description: >- Validierung abgeschlossen – mindestens ein ausgewählter Dienst hat ein verwertbares Ergebnis zurückgegeben. Prüfen Sie `database_validation.match_type` für das Gesamtergebnis, `validations` für die feldbezogenen Vergleiche und `outcome_code`s pro Dienst sowie `errors` (sofern vorhanden) für Dienste, die fehlgeschlagen sind. content: application/json: 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. database_validation: type: object properties: status: type: string enum: - Approved - Declined - In Review description: >- `Declined`, wenn der übergreifende `match_type` eine `DECLINE`-Aktion auslöst (`no_match_action` ist standardmäßig `DECLINE`, `partial_match_action` ist standardmäßig `NO_ACTION`); `In Review`, wenn kein Dienst einen verwertbaren Abgleich geliefert hat, beispielsweise wenn der einzige ausgewählte Dienst `REGISTRY_UNAVAILABLE` oder `INCONCLUSIVE` zurückgegeben hat; andernfalls `Approved`. Eine Anfrage, bei der mehrere Dienste ausgewählt wurden, kann bei der Übereinstimmung eines Dienstes `Approved` sein, während ein anderer nicht verfügbar war; prüfen Sie daher auch `errors` und die `outcome_code`-Werte der einzelnen Dienste. issuing_state: type: string description: >- Echo des ISO-3166-1-Alpha-3-Ländercodes, gegen den validiert wurde. example: BRA validation_type: type: string enum: - one_by_one - two_by_two description: >- Aus den Ergebnissen abgeleitet: `two_by_two`, wenn ≥2 unterschiedliche Dienste eine vollständige Übereinstimmung geliefert haben (bei der Identifikationsnummer, beim vollständigen Namen und Geburtsdatum zusammen oder bei der Adresse ohne Widersprüche); andernfalls `one_by_one`. (Das gleichnamige Anfragefeld ist veraltet und wird ignoriert.) screened_data: type: object description: >- Wiedergabe der Eingabefelder, die an die ausgewählten Dienste gesendet wurden (Datumsangaben normalisiert auf `YYYY-MM-DD`; ein `selfie` wird, sofern gesendet, als vorab signierte URL zurückgegeben; `consent_obtained: true` wird hinzugefügt, wenn eine Einwilligung erteilt wurde). match_type: type: string nullable: true enum: - full_match - partial_match - no_match description: >- Gesamtergebnis aggregiert über Dienste mit Vergleichen auf Feldebene: ein `full_match` → `full_match`; andernfalls ein `partial_match` → `partial_match`; andernfalls `no_match`. Dienste, die nur ein Ergebnis liefern, wie z. B. biometrisches strafrechtliches Screening, können `null` zurückgeben; prüfen Sie jeden Eintrag in `validations` auf seinen `outcome_code`. validations: description: >- Die Struktur hängt von `save_api_request` ab. **`true` (Standard):** ein Array von Objekten pro Dienst (`service_id`, `service_name`, `validation`, `outcome_code`, `outcome_detail`, `source_data`). **`false`:** ein einzelnes flaches Objekt, das die Ergebnisse aller Dienste auf Feldebene zusammenführt (`{"full_name": "full_match", ...}`). oneOf: - type: array items: type: object description: >- Validierungsergebnis pro Dienst (wird zurückgegeben, wenn `save_api_request=true`, der Standardwert). properties: service_id: type: string description: >- Katalog-ID des Dienstes, der dieses Ergebnis erzeugt hat (z. B. `bra_cpf`). example: bra_cpf service_name: type: string description: Lesbarer Katalogname des Dienstes. example: Brazil - CPF status check validation: type: object description: >- Feldweiser Abgleich zwischen Ihrer Eingabe und dem Registereintrag. Schlüssel sind kanonische Feldnamen (`full_name`, `date_of_birth`, `identification_number`, `address`, …); Werte sind `full_match`, `partial_match` oder `no_match`. additionalProperties: type: string enum: - full_match - partial_match - no_match outcome_code: type: string enum: - MATCH - PARTIAL_MATCH - NO_MATCH - DOCUMENT_NOT_FOUND - INVALID_DOCUMENT_FORMAT - INVALID_INPUT - MINOR_BLOCKED - DECEASED - BIOMETRIC_NO_MATCH - BIOMETRIC_IMAGE_UNUSABLE - INCONCLUSIVE - DOCUMENT_SUPERSEDED - REGISTRY_UNAVAILABLE - REGISTRY_ERROR description: >- Anbieterunabhängiges Ergebnis des Registerabgleichs. `MATCH`/`PARTIAL_MATCH`/`NO_MATCH` beschreiben den Abgleich; `DOCUMENT_NOT_FOUND` bedeutet, dass die Kennung nicht im Register vorhanden ist; `INCONCLUSIVE` bedeutet, dass das Register dies weder bestätigen noch verneinen konnte (zur Prüfung weitergeleitet – KEINE Nicht-Übereinstimmung); `BIOMETRIC_NO_MATCH` ist eine eindeutige Nicht-Übereinstimmung des Gesichts, während `BIOMETRIC_IMAGE_UNUSABLE` ein technisches Bildproblem darstellt (Selfie erneut aufnehmen); `DECEASED`/`MINOR_BLOCKED` sind richtlinienbasierte Registerergebnisse; `DOCUMENT_SUPERSEDED` bedeutet, dass die Identität übereinstimmte, aber die vorgelegte Version des Dokuments nicht der hinterlegten entspricht (es wurde eine neuere Version ausgestellt); `INVALID_DOCUMENT_FORMAT`/`INVALID_INPUT` bedeuten, dass das Register selbst die gesendeten Daten abgelehnt hat; `REGISTRY_UNAVAILABLE`/`REGISTRY_ERROR` weisen auf Upstream-Fehler hin. outcome_detail: type: string nullable: true description: >- Unverarbeitete Upstream-Statusdetails, die dem Ergebniscode zugrunde liegen (z. B. ein HTTP- oder Register-Statuscode). source_data: type: object nullable: true description: >- Bereinigte, normalisierte Ansicht des Registerdatensatzes unter Verwendung kanonischer Feldnamen (`identification_number`, `first_name`, `last_name`, `date_of_birth` sowie registerspezifischer Flags). Bildfelder werden, sofern vorhanden, als vorab signierte URLs zurückgegeben. - type: object additionalProperties: type: string enum: - full_match - partial_match - no_match description: >- Zusammengeführte Ergebnisse auf Feldebene (zustandslose Struktur bei `save_api_request=false`). warnings: type: array items: type: object properties: feature: type: string description: Funktion, die die Warnung ausgelöst hat. risk: type: string description: Maschinenlesbare Risiko-Kennung. additional_data: type: object nullable: true description: >- Zusätzlicher Kontext für die Warnung, sofern verfügbar. log_type: type: string description: >- `warning`, `information` oder `error` – wie sich das Risiko auf das Ergebnis ausgewirkt hat. short_description: type: string description: Einzeilige, lesbare Zusammenfassung. long_description: type: string description: Vollständige menschenlesbare Erklärung. description: >- `DATABASE_VALIDATION_NO_MATCH` oder `DATABASE_VALIDATION_PARTIAL_MATCH`, falls zutreffend; leer bei vollständiger Übereinstimmung. errors: type: array description: >- Nur vorhanden, wenn einige (aber nicht alle) ausgewählten Dienste fehlgeschlagen sind. Jeder Eintrag enthält `service_id`, `code`, `message` und `retryable`. Ein hier gemeldeter Dienst fehlt in `validations` sowie `services_used` und wird nicht abgerechnet. Dieses Array ist der einzige Ort, an dem er erscheint; prüfen Sie es daher auch dann, wenn `status` auf `Approved` steht. items: type: object properties: service_id: type: string code: type: string example: empty_provider_response message: type: string retryable: type: boolean description: >- `true`, wenn der Dienst keine Antwort geliefert hat und ein späterer Wiederholungsversuch erfolgreich sein kann; `false`, wenn die Quelle die gesendeten Daten verweigert hat und die Eingabe zuerst korrigiert werden muss. example: true services_used: type: array items: type: string description: >- Katalog-IDs der Dienste, die ein abrechenbares Ergebnis zurückgegeben haben. **Nur vorhanden, wenn die Anfrage explizit `services` gesendet hat.** match_score: type: number description: >- Anteil (0.0–1.0) der versuchten Dienste, die eine vollständige Übereinstimmung ergaben (bei der Identifikationsnummer, beim vollständigen Namen + Geburtsdatum zusammen oder bei der Adresse ohne Widersprüche). **Nur vorhanden, wenn in der Anfrage explizit `services` gesendet wurde.** vendor_data: type: string nullable: true description: Wiedergabe der von Ihnen gesendeten `vendor_data`. metadata: type: object nullable: true description: Rückgabe der von Ihnen gesendeten `metadata`. created_at: type: string format: date-time examples: Full match (Approved): summary: >- Standard save_api_request=true – dienstspezifische `validations`-Objekte value: request_id: 7f9a1c0e-1f2b-4f6e-9d3a-2b1c0e7f9a1c database_validation: status: Approved issuing_state: BRA validation_type: one_by_one screened_data: tax_number: '12345678900' first_name: John last_name: Doe date_of_birth: '1980-01-01' match_type: full_match validations: - validation: full_name: full_match date_of_birth: full_match identification_number: full_match outcome_code: MATCH outcome_detail: '200' service_id: bra_cpf service_name: Brazil - CPF status check source_data: identification_number: '12345678900' first_name: JOHN last_name: DOE date_of_birth: '1980-01-01' lgpd_minor: false minor_under_16: false minor_under_18: false warnings: [] vendor_data: user-1234 metadata: null created_at: '2026-06-11T10:30:00.000000+00:00' Explicit services (extended shape): summary: >- Anfrage mit `services` gesendet — Antwort ergänzt `services_used` und `match_score` value: request_id: b3e7c1a2-9d4f-4f0b-8a6c-5e2d1f0a9b3e database_validation: status: Approved issuing_state: BRA validation_type: one_by_one screened_data: tax_number: '12345678900' first_name: John last_name: Doe date_of_birth: '1980-01-01' match_type: full_match validations: - validation: full_name: full_match date_of_birth: full_match identification_number: full_match outcome_code: MATCH outcome_detail: '200' service_id: bra_cpf service_name: Brazil - CPF status check source_data: identification_number: '12345678900' first_name: JOHN last_name: DOE date_of_birth: '1980-01-01' lgpd_minor: false minor_under_16: false minor_under_18: false warnings: [] services_used: - bra_cpf match_score: 1 vendor_data: user-1234 metadata: null created_at: '2026-06-11T10:30:00.000000+00:00' No match (Declined): summary: >- Registereintrag stimmt nicht überein — Standardwert `no_match_action=DECLINE` value: request_id: 0a1b2c3d-4e5f-6789-abcd-ef0123456789 database_validation: status: Declined issuing_state: BRA validation_type: one_by_one screened_data: tax_number: '12345678900' first_name: John last_name: Doe date_of_birth: '1980-01-01' match_type: no_match validations: - validation: full_name: no_match date_of_birth: no_match identification_number: no_match outcome_code: NO_MATCH outcome_detail: '200' service_id: bra_cpf service_name: Brazil - CPF status check source_data: identification_number: '00987654321' first_name: TOTALLY last_name: DIFFERENT NAME date_of_birth: '1999-01-01' lgpd_minor: false minor_under_16: false minor_under_18: false warnings: - feature: DATABASE_VALIDATION risk: DATABASE_VALIDATION_NO_MATCH additional_data: null log_type: error short_description: Database validation no match long_description: >- The system identified a no match in the database validation, requiring further investigation. vendor_data: null metadata: null created_at: '2026-06-11T10:31:00.000000+00:00' Stateless (save_api_request=false): summary: >- `validations` wird zu einer zusammengeführten Feld-Map zusammengefasst; es wird nichts gespeichert value: request_id: c4d5e6f7-8901-2345-6789-abcdef012345 database_validation: status: Approved issuing_state: BRA validation_type: one_by_one screened_data: tax_number: '12345678900' first_name: John last_name: Doe date_of_birth: '1980-01-01' match_type: full_match validations: full_name: full_match date_of_birth: full_match identification_number: full_match warnings: [] vendor_data: null metadata: null created_at: '2026-06-11T10:32:00.000000+00:00' '400': description: >- Validierungsfehler – es wird nichts abgerechnet. Preflight-Feldfehler treten vor jedem externen Aufruf auf. Wenn jeder unbeantwortete Versuch die Eingabe explizit ablehnt, enthält die Antwort stattdessen `validation_errors` mit `code: provider_rejected_input` und `retryable: false`; korrigieren Sie die Eingabe vor einem Wiederholungsversuch. Probleme auf Feldebene nutzen den Standard-Envelope von DRF; Katalogprobleme geben ein `services`-Array zurück (plus `requires_onboarding` oder `services_requiring_consent`, falls relevant); Fehler zu fehlenden Feldern enthalten `fields_required_by`, das jedes fehlende Feld den Diensten zuordnet, die es erfordern; Dienste, die mindestens eine zusätzliche Kennung benötigen (z. B. `usa_states_credit_bureau`, das einen Namen allein nicht verifizieren kann), geben `any_field_required_by` zurück, das jeden Dienst den Feldern zuordnet, von denen mindestens eines vorhanden sein muss; Formatprobleme, die pro Dienst geprüft werden, geben `invalid_fields_by_service` zurück. content: application/json: examples: Invalid issuing_state: summary: >- Land nicht unterstützt – Meldung listet alle gültigen Alpha-3-Codes auf value: error: - >- Invalid issuing state. Valid options are: ARE, ARG, AUS, AUT, BEL, BGD, BOL, BRA, CAN, CHE, CHL, CHN, CIV, COL, CRI, CZE, DEU, DNK, DOM, ECU, ESP, FIN, FRA, GBR, GHA, GLB, GRC, GTM, HKG, HND, IDN, IND, IRL, ITA, KEN, KHM, MAR, MEX, MYS, NGA, NLD, NOR, NZL, OMN, PAN, PER, PHL, POL, PRT, PRY, QAT, SGP, SLV, SVK, SWE, THA, UGA, URY, USA, VEN, ZAF, ZMB, ZWE Missing required fields: summary: >- Vereinigung der erforderlichen Felder über ausgewählte Dienste hinweg mit dem Hinweis für universelle Felder value: error: - >- Missing required fields: tax_number (or use 'identification_number' which maps to 'tax_number' for BRA) fields_required_by: tax_number: - bra_cpf Unknown service id: summary: >- `services` enthält eine ID, die nicht im Katalog vorhanden ist value: services: - 'Unknown service_id(s): [''bogus_service'']' Service not live for country: summary: >- `services` nennt einen Dienst aus einem anderen Land (oder einen Dummy-Eintrag) value: services: - >- Services not currently live for PER: ['bra_cpf']. Available services: ['per_dni', 'per_residential', 'per_tax_registration'] Service requires onboarding: summary: >- Dienst existiert, ist aber für Ihre Organisation noch nicht aktiviert value: services: - >- Services require onboarding before they can be enabled for AUS: ['aus_australia_driver_licence']. Contact Didit support to activate them. requires_onboarding: - aus_australia_driver_licence Consent missing: summary: >- Ein ausgewählter Dienst ist mit requires_consent=true gekennzeichnet und `consent` war nicht `true` value: consent: - >- Explicit end-user consent is required for these database validation services: ['chn_national_id']. Send `consent=true`. services_requiring_consent: - chn_national_id Country format rule violation: summary: >- Kennung entspricht nicht der Formatregel des Landes (Länge/Ziffern/Regex) value: tax_number: - >- Invalid tax number for BRA: Brazilian CPF (exactly 11 digits). Must be exactly 11 characters long (got 10). Service-specific format violation: summary: >- Ein Feld erfüllt nicht die Formatierungsanforderungen des ausgewählten Dienstes value: error: - >- One or more fields do not match the format required by the selected service. invalid_fields_by_service: chn_national_id: - national_id_format Input refused by every attempt: summary: Korrigieren Sie die Eingabe vor dem Wiederholungsversuch value: error: >- The source refused to run this query with the supplied input. validation_errors: - service_id: bra_cpf code: provider_rejected_input message: >- The source refused to run this query with the supplied input. retryable: false schema: type: object additionalProperties: true properties: error: description: Erklärung auf Anfrageebene oder Preflight-Feldfehler. oneOf: - type: string - type: array items: type: string validation_errors: type: array description: >- Vorhanden, wenn jeder unbeantwortete Versuch die Eingabe nach dem Preflight abgelehnt hat. items: type: object properties: service_id: type: string code: type: string message: type: string retryable: type: boolean description: >- Gibt an, ob ein späterer Wiederholungsversuch diesen Dienstfehler beheben kann. False bedeutet, dass zuerst die bereitgestellte Eingabe korrigiert werden muss. '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 ein Screening- oder Anbieteraufruf 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 '502': description: >- Kein ausgewählter Dienst hat ein brauchbares Ergebnis zurückgegeben. Prüfen Sie jeden validation_errors-Eintrag vor einem erneuten Versuch; HTTP 502 allein begründet keinen vorübergehenden Fehler. Ein empty_provider_response mit retryable: true weist auf nicht verfügbare oder unerklärte Ergebnisse hin, einschließlich eines abgelehnten primären Anbieters gefolgt von einem nicht verfügbaren Fallback. Legacy-Einträge von provider_invalid_input und provider_validation_error erfordern stattdessen korrigierte Eingaben und lassen retryable möglicherweise weg. Es wird nichts in Rechnung gestellt. Wenn save_api_request=true gesetzt ist, wird der fehlgeschlagene Versuch als Sitzung mit dem Status Not Finished erfasst. Bei Teilfehlern wird 200 mit database_validation.errors zurückgegeben. content: application/json: schema: type: object properties: error: type: string validation_errors: type: array items: type: object properties: service_id: type: string code: type: string message: type: string retryable: type: boolean description: >- Gibt an, ob ein späterer Wiederholungsversuch diesen Dienstfehler beheben kann. False bedeutet, dass zuerst die bereitgestellte Eingabe korrigiert werden muss. examples: Provider returned no result: summary: Jeder ausgewählte Dienst ist fehlgeschlagen value: error: >- Database validation could not be performed. The external validation service did not return a result. Please try again later. validation_errors: - service_id: bra_cpf code: empty_provider_response message: >- The provider did not return a database validation result. retryable: true security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: |- curl -X POST https://verification.didit.me/v3/database-validation/ \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "issuing_state": "BRA", "services": ["bra_cpf"], "identification_number": "12345678900", "first_name": "John", "last_name": "Doe", "date_of_birth": "1980-01-01", "vendor_data": "user-1234" }' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.database_validation.validate( issuing_state="BRA", services=["bra_cpf"], identification_number="12345678900", first_name="John", last_name="Doe", date_of_birth="1980-01-01", vendor_data="user-1234", ) print(result) - lang: javascript label: Node.js source: |- import Didit from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.databaseValidation.validate({ issuing_state: "BRA", services: ["bra_cpf"], identification_number: "12345678900", first_name: "John", last_name: "Doe", date_of_birth: "1980-01-01", vendor_data: "user-1234", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.DatabaseValidation.Validate(ctx, didit.DatabaseValidationValidateParams{\n\tIssuingState: \"BRA\",\n\tServices: didit.Some([]string{\"bra_cpf\"}),\n\tIdentificationNumber: didit.String(\"12345678900\"),\n\tFirstName: didit.String(\"John\"),\n\tLastName: didit.String(\"Doe\"),\n\tDateOfBirth: didit.String(\"1980-01-01\"),\n\tVendorData: didit.String(\"user-1234\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import java.time.LocalDate; import java.util.List; import me.didit.Didit; import me.didit.types.DatabaseValidationValidateParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.databaseValidation().validate(DatabaseValidationValidateParams.builder() .issuingState("BRA") .services(List.of("bra_cpf")) .identificationNumber("12345678900") .firstName("John") .lastName("Doe") .dateOfBirth(LocalDate.parse("1980-01-01")) .vendorData("user-1234") .build()); System.out.println(result); - lang: php label: PHP source: |- databaseValidation->validate([ 'issuing_state' => 'BRA', 'services' => ['bra_cpf'], 'identification_number' => '12345678900', 'first_name' => 'John', 'last_name' => 'Doe', 'date_of_birth' => '1980-01-01', 'vendor_data' => 'user-1234', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.database_validation.validate( issuing_state: "BRA", services: ["bra_cpf"], identification_number: "12345678900", first_name: "John", last_name: "Doe", date_of_birth: "1980-01-01", vendor_data: "user-1234" ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.DatabaseValidation.ValidateAsync(new DatabaseValidationValidateParams { IssuingState = "BRA", Services = new string[] { "bra_cpf" }, IdentificationNumber = "12345678900", FirstName = "John", LastName = "Doe", DateOfBirth = "1980-01-01", VendorData = "user-1234", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: 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.