Unternehmensregister-API: Firmensuche und Auswahl

Endpunkte und Abrechnung

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 ausschließlich von anderen Quellen geliefert werden, werden nicht berechnet. Ein späterer Abruf von Profilen wird separat abgerechnet. Der Abruf wird in drei Datenstufen mit jeweils einem Endpoint angeboten, die Preise richten sich nach dem Land (Preise je Land):

Endpoint	Leistung	Preis
`POST /v3/kyb/search/`	Kandidatenunternehmen: Name, Registernummer, Status, Typ	$0.50, wenn Ergebnisse aus der kostenpflichtigen Quelle zurückgegeben werden
`POST /v3/kyb/select/`	Lite: das Unternehmensprofil (Kennungen, Status, Rechtsform, Gründungsdatum, eingetragene Adresse, Tätigkeit, Kontaktdaten) und die Organmitglieder	Lite-Preis: $2.00-$3.00 je nach Land
`POST /v3/kyb/shareholders/`	Lite zuzüglich der direkten Gesellschafter mit ihren Beteiligungsspannen	Preis für Gesellschafter: $5.00-$22.00 je nach Land
`POST /v3/kyb/ubo/`	Gesellschafter zuzüglich der letztlich wirtschaftlich Berechtigten, die über die Eigentumskette ermittelt werden	UBO-Preis: $9.00-$96.00 je nach Land

select entspricht der Stufe Lite: Ein gehosteter KYB-Workflow berechnet diese Stufe für eine Registerprüfung auf Lite-Niveau, und der Endpoint behält den Vertrag, den er schon immer hatte. Europa umfasst den EWR, das Vereinigte Königreich und die Schweiz. Eine Shareholders- oder UBO-Suche fragt die Quelle für die Eigentümerstruktur ab, die die jeweilige Stufe bedient. Antwortet diese Quelle, dass sie das Unternehmen nicht führt, fragt die Suche zusätzlich die übrigen Registerquellen des Landes ab. So wird ein Unternehmen, das die Quelle für die Eigentümerstruktur nicht enthält, trotzdem als Kandidat angeboten und endet nicht bei der manuellen Eingabe. Kandidaten, die auf diesem Weg gefunden wurden, behalten die von Ihnen angeforderte Stufe. Beim Abruf wird die Quelle für die Eigentümerstruktur erneut geprüft. Führt sie das Unternehmen weiterhin nicht, werden das Lite-Profil geliefert und berechnet, und es gilt registry_ownership_status: "not_held".

Sie zahlen für die gelieferte Stufe. Jede Antwort enthält registry_tier_requested und registry_tier_delivered. Wenn die Register des Landes keine Daten zur Eigentümerstruktur haben oder das Register für das ausgewählte Unternehmen keinen Datensatz zur Eigentümerstruktur führt, wird eine Anfrage zur Eigentümerstruktur mit der höchsten verfügbaren Stufe geliefert und berechnet (meist Lite). registry_ownership_status zeigt den Grund an. Enthält der aufgelöste Bericht einer UBO-Anfrage keine natürliche Person als wirtschaftlich Berechtigte, wird sie als Shareholders geliefert und berechnet.

Versionierung. Die Endpoints Shareholders und UBO gibt es nur unter /v3/. Die Gebühr für die eigenständige Suche gilt auch für /v2/kyb/search/. Der Abruf von Profilen wird separat abgerechnet.

Status der Eigentümerstruktur

registry_ownership_status gibt an, was mit dem Eigentümerteil einer Shareholders- oder UBO-Anfrage geschehen ist:

Wert	Bedeutung
`not_requested`	Der Aufruf war ein Lite-Abruf, daher wurde keine Eigentümerstruktur angefragt.
`delivered`	Das Register hat die Eigentümerdaten geliefert, und die Stufe in `registry_tier_delivered` ist die Stufe, für die Sie zahlen.
`not_held`	Das Eigentümerregister hat geantwortet und führt dieses Unternehmen nicht, es hat also keinen Eigentümerdatensatz auszuliefern. Das Unternehmen wurde von einer anderen Registerquelle des Landes gefunden. Stattdessen werden das Lite-Profil geliefert und abgerechnet, mit `registry_data.ownership_error: "company_not_found"`.
`unavailable`	Die Eigentümerdaten wurden aus einem anderen Grund nicht geliefert: Der Datensatz des Registers nennt keinen Eigentümer, das Register hat den Eigentümerabschnitt gar nicht zurückgegeben oder konnte nicht abgefragt werden. `registry_data.ownership_error` gibt an, welcher Fall zutrifft. Stattdessen werden das Lite-Profil geliefert und abgerechnet.
`pending`	Der Eigentümerabschnitt wurde noch nicht vom Register abgerufen. Es fallen keine Kosten an, und `registry_tier_delivered` ist `null`, bis der Abschnitt abgerufen wurde.

not_held und unavailable werden beide als Lite geliefert und abgerechnet, sind aber nicht dasselbe Ergebnis: not_held bedeutet, dass die Eigentümerquelle das Unternehmen nicht abdeckt, also eine Lücke in der Abdeckung. unavailable bedeutet, dass die Daten nicht geliefert wurden, etwa wegen eines Ausfalls oder eines Abschnitts, den das Register leer gelassen hat. registry_data.ownership_error nennt den Grund. Auswahlvorgänge, die bisher unavailable meldeten, weil das Eigentümerregister das Unternehmen nicht aufführte, melden nun not_held. Wenn Sie den Status auswerten, behandeln Sie beide als dieselbe Lite-Lieferung. Zwei Werte bedeuten Unterschiedliches und dürfen nicht als derselbe Befund gelesen werden:

`ownership_error`	Bedeutung
`no_owners_on_record`	Das Register hat den Eigentümerabschnitt beantwortet, und er nennt keinen Eigentümer. Für das Unternehmen ist bei diesem Register keine Cap Table hinterlegt.
`ownership_section_unavailable`	Das Register hat den Eigentümerabschnitt nicht zurückgegeben, daher wurde dafür nichts geliefert. Die Liste fehlt, ist aber nicht leer. Sie sagt nichts darüber aus, wer das Unternehmen besitzt.

Ein Abschnitt, den das Register nicht zurückgegeben hat, wird außerdem strukturiert unter registry_data.section_errors erfasst, geordnet nach Abschnitt (officers, shareholders, group_structure) mit dem Status, den das Register zurückgegeben hat:

{
  "section_errors": {
    "shareholders": {
      "status_code": 404
    }
  }
}

section_errors beschreibt die Antwort, die Sie vorliegen haben, nicht die Vorgeschichte dazu. Ein Abschnitt, der bei der ersten Anfrage nicht zurückgegeben und bei einem späteren Durchlauf geliefert wird (siehe asynchroner Abruf unten), verliert seinen Eintrag. So stimmen registry_ownership_status, ownership_error und section_errors immer überein: Ein delivered-Abschnitt hat nie einen Eintrag, und no_owners_on_record wird nie von einem Eintrag für shareholders begleitet. Ein Abschnitt wird auch nie teilweise geliefert. Liefert das Register die erste Seite einer Liste und schlägt dann bei einer späteren Seite fehl, gilt der Abruf bei diesem Versuch nicht als abgeschlossen. Ein pending-Abruf wird beim nächsten Durchlauf erneut versucht, und eine neue Anfrage wird mit dem Fehler „Register nicht verfügbar“ beantwortet. Eine gelieferte Liste officers oder shareholders ist daher immer die vollständige Liste, die das Register führt. Behandeln Sie einen Abschnitt, der in section_errors aufgeführt ist, als nie gelieferte Daten, nie als leeres Ergebnis. Eine leere Liste officers oder shareholders neben einem section_errors-Eintrag dafür sagt nichts über das Unternehmen aus.

Eigentümerstruktur asynchron abgerufen

Einige Register werden auf Abruf abgefragt: Die erste Anfrage zu einem Unternehmen, über das die Quelle noch nie abgefragt wurde, liefert keinen Eigentümerabschnitt zurück, während die Daten geholt werden. Sie treffen innerhalb von ein paar Minuten ein. Dies als „keine Eigentümer im Register verzeichnet“ zu melden, würde die Eigentümerstruktur eines Unternehmens, das tatsächlich Gesellschafter hat, zu niedrig darstellen. Deshalb kommt die Anfrage stattdessen mit pending zurück. Solange ein Abruf pending ist, steht auch fetch_status auf pending, und der Antwortstatus lautet 202 Accepted. Didit wiederholt den Abschnitt selbstständig und schließt den Abruf ab, ohne dass Sie einen weiteren Aufruf tätigen müssen:

Sobald die Eigentümerdaten eintreffen, erscheinen die Gesellschafter und wirtschaftlich Berechtigten im gespeicherten Check. registry_tier_delivered wird zur gelieferten Stufe, und die Nutzung wird auf dieser Stufe berechnet.
Ist der Abschnitt bei Ablauf des Wiederholungsfensters noch leer, wechselt der Status zu unavailable, und die Anfrage wird als Lite geliefert und abgerechnet.

Behalten Sie die request_id bei und fragen Sie GET /v3/session/{request_id}/decision/ ab, bis registry_checks[0].company.fetch_status den Wert resolved hat. Wiederholen Sie die Abrufanfrage nicht, solange sie pending ist: Jeder neue POST ist eine eigene, separat abrechenbare Anfrage. Verwenden Sie POST /v3/kyb/search/, um Kandidatenunternehmen zu finden. Die Suche legt keinen gespeicherten Check an. Die Eingabe tier der Suche bestimmt die Kette, die durchsucht wird – siehe Suchstufe. Registersuchen können etwa 90 Sekunden dauern. Senden Sie webhook_url, wenn Didit sofort antworten und Ihre URL benachrichtigen soll, sobald die Kandidaten bereit sind. Der Such-Callback ist bewusst nicht signiert, daher müssen Sie für diese einfache Benachrichtigung kein gemeinsames Geheimnis konfigurieren. Verwenden Sie POST /v3/kyb/select/, POST /v3/kyb/shareholders/ oder POST /v3/kyb/ubo/ mit der zurückgegebenen kyb_response_id, um das Profil auf der gewünschten Stufe abzurufen. Der Abruf ist kostenpflichtig und speichert das Ergebnis als Manual Check in der Business Console.

Typischer Ablauf

Suchen Sie nach Firmenname, Registernummer und Land, mit dem tier, das Sie buchen möchten (basic ist die Standardkette für Lite; shareholders und ubo durchsuchen die Kette dieser Stufe).
Wenn search_resolved=false ist, warten Sie auf den optionalen Callback über webhook_url, statt abzufragen.
Zeigen Sie die zurückgegebenen Kandidaten Ihrem Bediener oder Kunden.
Rufen Sie die passende kyb_response_id auf der gewünschten Stufe ab (select für Lite, shareholders oder ubo).
Speichern Sie die zurückgegebene request_id und verwenden Sie sie, um das gespeicherte Ergebnis der Unternehmensverifizierung abzurufen.

Such-Callback

Sobald der Anbieter Didit mitteilt, dass die Suche abgeschlossen ist, sendet Didit einen POST an Ihre webhook_url:

{
  "event_id": "7f5a1c93-6a44-4f0e-9f2b-3d8a1c6f2e91",
  "event_type": "kyb.registry_search.resolved",
  "request_id": "b5ef9df5-bd9e-4d61-bbe5-5eb7a8fb6f85",
  "vendor_data": "business-123",
  "metadata": {
    "source": "onboarding"
  },
  "search_status": "resolved",
  "search_resolved": true,
  "kyb_registry": {
    "companies": [
      {
        "kyb_response_id": "kyb_resp_123",
        "name": "TESCO PLC",
        "registration_number": "00445790",
        "status": "active",
        "type": "Public Limited Company",
        "registered_address": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, AL7 1GA",
        "risk_level": null,
        "fetch_status": "pending"
      }
    ],
    "pagination": {
      "total": 1,
      "page": 1,
      "per_page": 25
    },
    "search_status": "resolved",
    "search_resolved": true
  },
  "timestamp": 1767225600,
  "created_at": 1767225600
}

Behandeln Sie den Callback als Zustellungsbenachrichtigung. Verwenden Sie die zurückgegebene kyb_response_id mit POST /v3/kyb/select/, POST /v3/kyb/shareholders/ oder POST /v3/kyb/ubo/, um den kostenpflichtigen Abruf des Registerprofils auszuführen.

Zuletzt geändert am 7. November 2026

​Endpunkte und Abrechnung

​Status der Eigentümerstruktur

​Eigentümerstruktur asynchron abgerufen

​Typischer Ablauf

​Such-Callback

Endpunkte und Abrechnung

Status der Eigentümerstruktur

Eigentümerstruktur asynchron abgerufen

Typischer Ablauf

Such-Callback