Zum Hauptinhalt springen
POST
curl
Verwenden Sie diesen Endpoint zuerst, um passende Kandidaten im Unternehmensregister zu finden. Die Suche erstellt keine gespeicherte manuelle Prüfung. Erfolgreiche eigenständige Suchen mit einer kostenpflichtigen Unternehmensdatenquelle kosten $0.50 pro Anfrage, unabhängig von der Anzahl der Kandidaten. Leere Ergebnisse, fehlgeschlagene Suchen und Ergebnisse, die nur von anderen Quellen geliefert werden, werden nicht berechnet. Ein späterer Abruf des Registerprofils wird separat abgerechnet. Bei einer Suche, die eine kostenpflichtige Quelle nutzen kann, prüft und reserviert Didit den zutreffenden Suchpreis, bevor das Register kontaktiert wird. Bei unzureichendem Guthaben weist Didit Anfragen mit 403 und code: "insufficient_credits" zurück. Bei vertraglicher Abrechnung richtet sich die Abrechnung nach Ihrem vereinbarten Suchtarif. Ein nicht konfigurierter Vertragstarif wird vor der Suche abgelehnt. Sandbox-Suchen sind kostenlos. Jede wiederholte erfolgreiche Suche ist eine neue abrechnungspflichtige Anfrage. Die Zustellung eines Callbacks erzeugt keine weitere Suchgebühr. Wenn Sie webhook_url senden, kann Didit sofort antworten, während der Anbieter die Suche noch auflöst. Die Kandidaten werden dann an Ihre Callback-URL gesendet, sobald sie bereit sind. Der Callback ist bewusst nicht signiert. Für diese Suchbenachrichtigung müssen Sie also kein Webhook-Secret konfigurieren. Ein Beispiel finden Sie im Beispiel-Payload des Suchcallbacks. Nachdem Sie das richtige kyb_response_id ausgewählt haben, rufen Sie POST /v3/kyb/select/ (Lite), POST /v3/kyb/shareholders/ oder POST /v3/kyb/ubo/ auf, um das abrechnungspflichtige Registerprofil auf der benötigten Stufe abzurufen.
Der Status fetch_status jedes Kandidaten ist zum Zeitpunkt der Suche pending und bleibt pending, bis Sie diesen Kandidaten auswählen. Die Suche listet nur Kandidaten auf, und erst die Auswahl ruft das vollständige Profil ab. Fragen Sie die Suche nicht wiederholt ab, um auf eine Auflösung zu warten.kyb_response_id ist ein undurchsichtiges, flüchtiges Handle, das auf eine Suchanfrage beschränkt ist. Übergeben Sie es genau so zurück, wie Sie es erhalten haben, parsen Sie es nicht und leiten Sie nichts aus seinem Inhalt ab. Wiederholen Sie dieselbe Suche, ist mit neuen IDs zu rechnen. Wählen Sie den Kandidaten zeitnah nach der Suche aus. Wenn Sie eine stabile Kennung für das Unternehmen selbst benötigen, verwenden Sie registration_number.

Suchstufe

tier wählt die Registerstufe, auf deren Anbieterkette die Suche läuft: basic (der Standard, die Lite-Kette), shareholders oder ubo. Die Kandidatenliste stammt aus der Kette dieser Stufe. Diese Kette ist nicht immer dieselbe Quelle, die die Lite-Suche verwendet. Eine leere Lite-Suche beweist deshalb nicht, dass das Register das Unternehmen nicht führt. Suchen Sie in diesem Fall erneut auf der Stufe, die Sie benötigen. Bietet das Land die angegebene Stufe nicht an, läuft die Suche auf der höchsten Stufe, die das Land bis zu dieser Stufe anbietet. Ein Land ohne jegliche Registerdaten wird für Registerprüfungen nicht angeboten. Fahren Sie in diesem Fall mit der manuellen Eingabe des Unternehmens fort. Suchen Sie auf der Stufe, die Sie kaufen möchten, und rufen Sie den Kandidaten dann über den Endpoint ab, der ihn verkauft:

search_type

search_type akzeptiert nur contains, und das ist auch der Standardwert. Die Registerquellen hinter der Suche führen einen Enthaltenheitsabgleich von Firmennamen durch. Deshalb werden start_with und fuzzy mit 400 ("start_with" is not a valid choice) abgelehnt und nicht stillschweigend als contains behandelt. Senden Sie registration_number, um einen exakten Unternehmensabgleich durchzuführen.

Gehostete und eigenständige Suche

POST /v1/kyb/search/ ist die Suche, die ein gehosteter Verifizierungsablauf ausführt. Sie wird über die Verifizierungssitzung authentifiziert, weist Anfragen mit einem API-Schlüssel mit 403 zurück und nimmt keinen tier entgegen. Die KYB-Registerkonfiguration des Workflows wählt die Kette aus. Die eigenständige API ruft POST /v2/kyb/search/ oder POST /v3/kyb/search/ mit Ihrem x-api-key auf. Die Eingabe tier und die gestuften Select-Endpoints sind der Weg, über den eine eigenständige Integration dieselben Kandidaten auf der benötigten Stufe erreicht.

Ausfälle des Registers behandeln

Ist der Registeranbieter vorübergehend nicht verfügbar, gibt der Endpoint 502 mit einem stabilen, maschinenlesbaren Code zurück:
Wenn Sie diesen Code erhalten, lassen Sie den Benutzer mit der manuellen Eingabe des Unternehmens fortfahren oder bitten Sie ihn, es später erneut zu versuchen. Halten Sie Validierungsfehler davon getrennt: Ungültige Sucheingaben geben 400 zurück und verwenden diesen Ausfallcode nicht.

Nicht unterstützte Länder und Suchbeschränkungen behandeln

Zwei weitere stabile Codes zeigen an, dass Sie keine Wiederholungsversuche mehr unternehmen und mit der manuellen Eingabe des Unternehmens fortfahren sollten: Im gehosteten Ablauf erlaubt jeder Registerschritt 3 Suchen bei einer kostenpflichtigen Unternehmensdatenquelle. Nach der dritten wird dem Antragsteller die manuelle Eingabe angeboten. Wenn Sie einen Kandidaten auswählen, der eine Markenregistrierung und kein Unternehmen ist, gibt der Endpoint 400 mit code: "kyb_registry_entry_not_a_company" zurück. Wählen Sie stattdessen ein Unternehmen aus den Suchergebnissen aus.

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

application/json
country_code
string
erforderlich

ISO 3166-1 Alpha-2-Code des Landes, dessen Unternehmensregister durchsucht werden soll. Zum Beispiel GB. Wenn Unternehmensregister auf Bundesstaat- oder Provinzebene geführt werden, hängen Sie den ISO 3166-2-Unterteilungscode als XX-YY an: US-CA durchsucht das kalifornische Register. Suchanfragen in den Vereinigten Staaten erfordern immer die Unterteilung — ein einfaches US wird abgelehnt. Groß-/Kleinschreibung wird nicht beachtet; wird in Großbuchstaben normalisiert.

Maximum string length: 10
Beispiel:

"GB"

name
string

Zu suchender Unternehmensname. Entweder name oder registration_number ist erforderlich.

Maximum string length: 255
Beispiel:

"Tesco"

registration_number
string

Zu suchende Registernummer. Entweder name oder registration_number ist erforderlich.

Maximum string length: 100
tier
enum<string>
Standard:basic

Register-Stufe, auf deren Provider-Kette diese Suche ausgeführt wird. basic (Standard) durchsucht die Lite-Kette des Landes; shareholders und ubo durchsuchen die Eigentümerstruktur-Kette dieser Stufe, bei der es sich um eine andere Quelle handeln kann, sodass eine leere Lite-Suche nicht beweist, dass das Unternehmen im Register fehlt. Ein Land, das die genannte Stufe nicht anbietet, wird auf der höchsten Stufe durchsucht, die es bis zu dieser anbietet. Rufen Sie den Treffer über den Endpoint ab, der die von Ihnen gesuchte Stufe bereitstellt: POST /v3/kyb/select/ (Lite), POST /v3/kyb/shareholders/ oder POST /v3/kyb/ubo/.

Verfügbare Optionen:
basic,
shareholders,
ubo
Beispiel:

"basic"

search_type
enum<string>
Standard:contains

Strategie für den Namensabgleich, die bei der Registersuche angewendet wird. contains ist der einzige zulässige Wert: Keine Registerquelle hinter der Suche bietet einen Präfix- oder Fuzzy-Modus, daher werden start_with und fuzzy mit 400 (not a valid choice) abgelehnt.

Verfügbare Optionen:
contains
vendor_data
string

Ihre Kennung für diese Abfrage; wird zurückgegeben und im Webhook-Callback enthalten sein.

metadata
object | null

Freiform-JSON; wird zurückgegeben und im Webhook-Callback enthalten.

webhook_url
string<uri>

Schaltet die Suche in den asynchronen Modus um: Die API antwortet sofort und sendet einen nicht signierten kyb.registry_search.resolved-Callback per POST an diese URL, sobald die Kandidatenliste bereitsteht.

Maximum string length: 500

Antwort

Suche angenommen. Der synchrone Modus gibt die ermittelte Kandidatenliste zurück; der Webhook-Modus antwortet sofort (häufig search_status: "pending") und stellt die endgültige Liste über den Callback kyb.registry_search.resolved zu.

request_id
string<uuid>

Mit webhook_url: Die persistierte Suchanfrage-ID, die im kyb.registry_search.resolved-Callback als request_id zurückgegeben wird. Ohne webhook_url: Eine vorübergehende Korrelations-UUID (die Suche wird nicht gespeichert).

kyb_registry
object
vendor_data
string | null

Wiedergabe der von Ihnen gesendeten vendor_data.

metadata
object | null

Rückgabe der von Ihnen gesendeten metadata.

created_at
string<date-time>
Zuletzt geändert am 7. November 2026