Zum Hauptinhalt springen
POST
Python
Dieser Leitfaden hilft Ihnen, den richtigen Importpfad zu wählen, wenn Sie Daten von einem anderen Anbieter in Didit übernehmen. Unter „Import“ werden häufig zwei verschiedene Vorgänge verstanden:
  • Historische Verifizierungsvorgänge importieren: Abgeschlossene KYC-, KYB-, Transaktionsüberwachungs- oder Workflow-Regeldatensätze werden neu angelegt, damit Didit die bisherige Anbieterhistorie anzeigt. Verwenden Sie POST /v3/session/imports/.
  • Betriebsdaten importieren: Benutzer, Unternehmen, Profilgesichter, Einträge auf der Sperrliste oder auf der Zulassungsliste werden angelegt, damit Didit sie bei künftigen Prüfungen nutzen kann. Verwenden Sie die APIs für Entitäten, Gesichter und Listen.
Verifizierungsimporte erstellen historische Datensätze mit session_type: "MIGRATED" für KYC und KYB. Sie senden keine E-Mails an Endbenutzer, leiten Benutzer nicht in den gehosteten Ablauf weiter und führen die ursprüngliche Verifizierung nicht erneut aus. Die importierten Datensätze erscheinen, sofern zutreffend, in Sitzungslisten, in Entitätsprofilen, in Transaktionsansichten und unter GET /v3/session/{session_id}/decision/.

Welchen Import sollten Sie verwenden?

Wenn Sie für künftige Prüfungen nur ein Benutzer- oder Unternehmensprofil benötigen, importieren Sie keine historische Verifizierungssitzung. Verwenden Sie stattdessen die APIs für die Entitäten Benutzer und Unternehmen. Wenn die Entscheidung, die Dokumentfelder, Warnungen oder Nachweise des bisherigen Anbieters in Didit als Compliance-Historie erscheinen sollen, verwenden Sie POST /v3/session/imports/.

Welche Daten lassen sich von welchem Anbieter migrieren

Didit akzeptiert eine kanonische CSV- oder NDJSON-Datei. Sie können also von jedem Anbieter migrieren, sobald Sie die Daten exportiert und umgewandelt haben. Das Importformat ist immer das kanonische Schema von Didit.

Migrationsablauf

  1. Entscheiden Sie, ob Sie Verlauf, Profile, Gesichter, Listen, Transaktionen oder Regeln importieren möchten.
  2. Exportieren Sie die Daten selbst aus dem alten Anbieter. Senden Sie keine API-Schlüssel des alten Anbieters an Didit.
  3. Wandeln Sie den Export des Anbieters in die passende kanonische CSV- oder NDJSON-Vorlage von Didit um.
  4. Bei großen Migrationen sollten Sie NDJSON bevorzugen und die Daten in Dateien aufteilen, die sich unabhängig voneinander erneut verarbeiten lassen.
  5. Erstellen Sie den Importauftrag und fragen Sie den Fortschritt ab.
  6. Rufen Sie die Zeilenfehler ab, korrigieren Sie nur die fehlgeschlagenen Zeilen und wiederholen Sie deren Import. Alle Importaufträge sind über ihre natürliche externe ID idempotent.

Importauftrag erstellen

Erstellen Sie einen Importauftrag mit einer einzigen Multipart-Anfrage:
Verwenden Sie CSV für kleinere, tabellenbasierte Migrationen und NDJSON für große Migrationen. Bei 100k+ Zeilen lässt sich NDJSON leichter streamen, aufteilen, validieren und wiederholen. Eine Anwendung kann bis zu 4 Importaufträge gleichzeitig ausführen. Teilen Sie große Migrationen daher auf mehrere Dateien auf und starten Sie für jede Datei einen Auftrag. Jeder Auftrag lädt die Mediendateien einer Zeile parallel herunter. Ein Auftrag, der durch ein Deployment oder einen Neustart des Workers unterbrochen wird, setzt sich automatisch ab der zuletzt importierten Zeile fort. Sie müssen ihn daher nicht neu starten. Bei Transaktionsimporten lassen Sie workflow_id weg:

Anfragefelder

Wie Datensätze erfasst und dedupliziert werden

Es gibt kein Anfragefeld für die Datenquelle: Jeder Import verwendet das kanonische Schema von Didit. Zur Nachvollziehbarkeit speichert jeder importierte Datensatz metadata.imported_from = "generic". Importe mit user_verification und business_verification deduplizieren Zeilen innerhalb der Anwendung anhand von external_id. Ein erneuter Import derselben Datei erzeugt daher keine Duplikate. Importe mit transactions deduplizieren stattdessen anhand von transaction_id. Eine Anbieter-Migration (source=provider) speichert jeden Datensatz als <provider>:<id>, zum Beispiel sumsub:5f8c0e2a9b1d4c3e2f1a0b9c. Ein Dateiimport für Benutzerverifizierung, der die reine ID des Anbieters (5f8c0e2a9b1d4c3e2f1a0b9c) übermittelt hat, wird als derselbe Datensatz erkannt, und zwar in beide Richtungen. Sie können daher eine Migration über Dateien beginnen und über eine Anbieter-Migration abschließen oder umgekehrt, ohne einen Datensatz doppelt zu importieren.

Import document photos, videos, and selfie evidence

Bei import_type=user_verification können Sie die Originalfotos der Dokumente, die Videos der Dokument- und Liveness-Aufnahmen sowie das Selfie-Bild vom bisherigen Anbieter importieren. Verwenden Sie diese kanonischen Spalten: Für große Migrationen verwenden Sie HTTPS-URLs. Didit lädt jede Datei herunter, prüft, dass die URL sicher ist, speichert eine eigene Kopie bei Didit und verknüpft sie mit der importierten Sitzung. Bilder werden komprimiert; Videos werden unverändert gespeichert. Bei kleinen Importen werden Bilder auch als Base64-Inline-Daten akzeptiert, Videos müssen jedoch immer als URL angegeben werden. Base64 würde jedes Video um etwa 33 % vergrößern und die Obergrenze pro Datei für Importe schnell überschreiten. Beispiel für eine NDJSON-Zeile mit beim Anbieter gehosteten Medien-URLs:
Wichtige Regeln für Medien:
  • URLs müssen https verwenden.
  • URLs dürfen nicht auf private IP-Adressen, localhost, Link-Local-Bereiche oder interne Metadaten-Hosts auflösen.
  • Bei Bildern können Sie entweder eine URL-Spalte oder die zugehörige *_base64-Ersatzspalte verwenden; wenn beide gesetzt sind, hat Base64 Vorrang. Videos sind nur als URL möglich. Es gibt keine Spalte *_video_base64.
  • Videos müssen mp4, webm oder mov sein, und jedes Video darf höchstens 10 MB groß sein. Größere Dateien oder Dateien, die keine Videos sind, werden als Zeilenfehler abgelehnt.
  • Didit setzt Zeitüberschreitungen für Verbindungsaufbau und Lesevorgänge sowie eine maximale Dateigröße durch und führt keine unbegrenzten Wiederholungsversuche aus.
  • Fehler beim Herunterladen von Medien werden als Zeilenfehler gespeichert, damit der restliche Import fortgesetzt werden kann.
  • Wenn Sie keine Medien vom Anbieter haben, lassen Sie diese Spalten leer. Didit importiert trotzdem die strukturierte Entscheidung und die Dokumentfelder.
  • Importierte Bilder und Videos dienen als Nachweise für die historische Prüfung. Didit führt bei importierten historischen Medien standardmäßig keine OCR-, Liveness- oder Dokumentbetrugsanalyse erneut aus.

Fortschritt abfragen

Die Antwort enthält status, import_type, total_rows, processed_rows, created_count, updated_count, skipped_count, failed_count und checkpoint_row.

Zeilenfehler herunterladen

Jeder Fehler enthält row_number, external_id, error und raw_row, damit Sie nur die fehlgeschlagenen Zeilen korrigieren und erneut ausführen können.

Schutz vor Missbrauch

Historische Import-Jobs über POST /v3/session/imports/ sind standardmäßig deaktiviert. Didit aktiviert diese Funktion nach einer Prüfung pro Organisation, weil solche Jobs Millionen Zeilen verarbeiten und Medien herunterladen können. Die regulären Betriebsdatenimporte in dieser Anleitung, also das Anlegen von Benutzern und Unternehmen, das Hochladen von Profilgesichtern und Gesichts-Sperrlisten sowie das Hinzufügen von Listeneinträgen, erfordern über die normalen API-Schlüssel-Berechtigungen, die Produktverfügbarkeit und die Rate-Limits dieser Endpunkte hinaus keine besondere Freischaltung für Migrationen. Historische Import-Jobs laufen außerdem auf isolierten Workern mit Dateigrößenbeschränkungen, Zeilenbudgets, nur HTTPS-Medien-URLs, Blockierung privater Netzwerk-URLs, einem Limit von 4 aktiven Import-Jobs pro Anwendung und einer Erfassung von Fehlern pro Zeile.

Kanonische Statuswerte

Idempotenz

Didit verwendet external_id als Idempotenz-Schlüssel für Importe von Benutzerverifizierungen und Unternehmensverifizierungen, jeweils bezogen auf die Anwendung. Transaktionsimporte verwenden transaction_id pro Anwendung. Wenn Sie dieselbe Datei erneut ausführen, werden bereits importierte Zeilen übersprungen und noch nicht verarbeitete Zeilen angelegt.

Benutzer, Profilgesichter und Sperrlisten importieren

Verwenden Sie diese Wege, wenn Sie keine abgeschlossene Verifizierungssitzung nachbilden möchten:

Benutzerprofile importieren

Legen Sie Benutzer mit POST /v3/users/create/ oder über den CSV-Import in der Business Console an, siehe „Benutzer importieren und exportieren“. Dabei wird nur das VendorUser-Profil erstellt oder aktualisiert. Es wird keine Verifizierungssitzung, KYC-Entscheidung, kein Dokumentenbericht, keine Warnung und kein Webhook-Verlauf erstellt. Das ist sinnvoll, wenn Didit den Kunden bereits kennen soll, bevor künftige Prüfungen stattfinden, oder wenn Sie CRM-ähnliche Felder wie display_name, Tags oder Metadaten nachträglich befüllen müssen.

Vertrauenswürdige Profilgesichter hochladen

Nachdem ein Benutzer angelegt wurde, laden Sie mit POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/ ein vertrauenswürdiges Gesicht für das Profil hoch. Dadurch werden die biometrischen Daten dem Benutzerprofil zugeordnet und für die Duplikatserkennung und die Gesichtssuche indexiert. Damit wird das Gesicht nicht auf die Sperrliste gesetzt. Die Funktion eignet sich, wenn Sie ein vertrauenswürdiges Profilbild von einem bisherigen KYC-Anbieter haben und möchten, dass künftige Didit-Prüfungen damit abgeglichen werden.

Gesichts-Sperrlisten und Allowlists importieren

Um ein Gesicht direkt zu sperren oder freizugeben, verwenden Sie POST /v3/lists/{list_uuid}/entries/face-upload/ mit einer Liste vom Typ „Gesicht“. Didit extrahiert das biometrische Embedding und speichert einen Listeneintrag. Das eignet sich für bekannte Betrüger-Fotos, vertrauenswürdige Gesichter auf der Allowlist oder die Migration von Betrugslisten von Anbietern. Stammt das Gesicht aus einer bestehenden Didit-Sitzung, verwenden Sie bevorzugt POST /v3/lists/{list_uuid}/entries/ mit reference_session_id. Didit extrahiert dann das passende Gesicht aus der Sitzung und verknüpft den Eintrag mit der Quelle.

Listen für Benutzer, Unternehmen, Dokumente, Wallets, E-Mail-Adressen, Telefonnummern, IP-Adressen oder Geräte importieren

Für Listenwerte, die keine Gesichter sind, verwenden Sie POST /v3/lists/{list_uuid}/entries/. Dieser Weg ist richtig für Sperrlisten, Allowlists und Chargeback-Listen von Anbietern sowie für Adressen von Wallets, bekannte riskante IP-Adressen, Geräte-Fingerprints, Dokumentnummern, E-Mail-Adressen, Telefonnummern, Benutzer oder Unternehmen.

Nächste Schritte

Benutzer importieren

Benutzerprofile laden und vertrauenswürdige Profilgesichter zuordnen.

Unternehmen importieren

Unternehmensprofile laden, bevor Sie KYB durchführen.

Profilgesicht hochladen

Vertrauenswürdige Gesichtsbilder importierten Benutzern zuordnen.

Gesicht in Liste hochladen

Gesichter zu Sperrlisten oder Allowlists hinzufügen.

Listeneintrag erstellen

Telefonnummern, E-Mail-Adressen, Wallets, Dokumente, IP-Adressen, Geräte, Benutzer oder Unternehmen in Listen importieren.

Rate-Limits

Sichere Migrationsschleifen und Wiederholungsversuche gestalten.

Autorisierungen

x-api-key
string
header
erforderlich

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.

Body

import_type
enum<string>
Standard:user_verification

Was importiert werden soll: historische Sitzungen der Benutzerverifizierung, historische Sitzungen der Unternehmensverifizierung, benutzerdefinierte Statusregeln für Workflows oder historische Datensätze der Transaktionsüberwachung.

Verfügbare Optionen:
user_verification,
business_verification,
status_rules,
transactions
workflow_id
string<uuid>

Workflow-UUID, mit der importierte Sitzungen oder Statusregeln verknüpft werden sollen. Erforderlich für user_verification, business_verification und status_rules. Bei Transaktionen weglassen.

source_format
enum<string>

Optional. Wird anhand der Dateiendung der hochgeladenen Datei abgeleitet, wenn sie weggelassen wird.

Verfügbare Optionen:
csv,
ndjson
file
file

Kanonische CSV- oder NDJSON-Datei. Verwenden Sie NDJSON für große Importe. Maximale Upload-Größe 25 MB (verwenden Sie source_file_url für größere Dateien). Ist mit source_file_url nicht kombinierbar.

source_file_url
string<uri>

Alternative zum Datei-Upload. Muss eine HTTPS-URL sein, die auf eine öffentliche Adresse auflöst (private/Loopback-Netzwerke werden abgelehnt). Schließt sich mit file gegenseitig aus.

source
enum<string>

provider kennzeichnet dies als Migration von einem anderen Anbieter für Ausweisverifizierung. Für einen Datei-Import weglassen.

Verfügbare Optionen:
file,
provider
provider
enum<string>

Migrationsquelle, aus GET /v3/session/imports/providers/. Erforderlich, wenn source den Wert provider hat.

Verfügbare Optionen:
sumsub,
jumio,
veriff,
onfido,
persona,
metamap,
socure,
idnow,
shufti,
idenfy,
ondato,
trulioo,
au10tix,
complycube,
other
credentials
object

Der schreibgeschützte Schlüssel des Anbieters mit den von credential_fields aufgelisteten Feldnamen. Im Ruhezustand verschlüsselt, wird niemals zurückgegeben und nach Abschluss des Imports gelöscht. Senden Sie ihn als JSON-String in multipart.

options
object
status_mapping
object

Anpassungen des Standard-Status-Mappings des Anbieters: Quellstatus zu Didit-Status. Not Finished und Abandoned werden übersprungen und gezählt, jedoch niemals importiert.

dry_run
boolean
Standard:false

Zählen, was die Migration importieren würde (nach Status, bereits in Didit, dieselbe Person, nicht abgeschlossen) und nichts schreiben. Der Auftrag endet als READY; starten Sie ihn mit POST /v3/session/imports/{importId}/start/.

face_templates
boolean
Standard:false

Erstellen Sie biometrische Templates aus den importierten Selfies und gleichen Sie diese mit den Gesichtern und der Sperrliste der Anwendung ab. Übereinstimmungen werden nur zur Prüfung markiert. Erfordert lawful_basis_confirmed.

lawful_basis_confirmed
boolean
Standard:false

Bestätigt, dass Sie über eine Rechtsgrundlage verfügen, um diese Selfies mit Didit als Auftragsverarbeiter zu teilen.

Antwort

Import-Job akzeptiert. Fragen Sie die zurückgegebene uuid regelmäßig ab, bis der status COMPLETED oder FAILED lautet.

uuid
string<uuid>
erforderlich

ID des Import-Jobs. Verwenden Sie diesen Wert, um den Fortschritt abzufragen und Zeilenfehler abzurufen.

status
enum<string>
erforderlich
Verfügbare Optionen:
PENDING,
PROCESSING,
COMPLETED,
FAILED,
PAUSED,
CANCELLED,
READY
import_type
enum<string>
erforderlich
Verfügbare Optionen:
user_verification,
business_verification,
status_rules,
transactions
source_format
enum<string>
erforderlich
Verfügbare Optionen:
csv,
ndjson
source_filename
string
erforderlich
total_rows
integer<int64>
erforderlich
processed_rows
integer<int64>
erforderlich
created_count
integer<int64>
erforderlich
updated_count
integer<int64>
erforderlich
skipped_count
integer<int64>
erforderlich
failed_count
integer<int64>
erforderlich
checkpoint_row
integer<int64>
total_media_bytes
integer<int64>
last_error
string | null
created_at
string<date-time>
updated_at
string<date-time>
started_at
string<date-time> | null
completed_at
string<date-time> | null
state
enum<string>

Der Status des Jobs, wie er in der Konsole angezeigt wird; errors ist ein abgeschlossener Job mit abgelehnten Zeilen.

Verfügbare Optionen:
ready,
queued,
running,
paused,
completed,
errors,
failed,
cancelled
source
enum<string>
Verfügbare Optionen:
file,
api,
provider
provider
string

Migrationsquelle; leer bei einem Datei- oder API-Import.

provider_options
object
credential_hint
string

Die ersten Zeichen des Schlüssels, den die Migration enthält. Der Schlüssel selbst wird niemals zurückgegeben.

credentials_expires_at
string<date-time> | null
resumes_at
string<date-time> | null

Wenn ein durch das Rate-Limit des Anbieters pausierter Auftrag von selbst fortgesetzt wird.

status_mapping
object
is_dry_run
boolean
dry_run_summary
object

Was ein Testlauf ergeben hat: total, by_status, already_in_didit, same_person, not_finished, failed, unmapped_statuses.

face_templates_enabled
boolean
lawful_basis_confirmed_at
string<date-time> | null
not_finished_count
integer<int64>
same_person_count
integer<int64>
face_templates_count
integer<int64>
face_duplicates_count
integer<int64>
face_blocklist_hits_count
integer<int64>
created_by_name
string | null
created_by_email
string | null
Zuletzt geändert am 7. November 2026