> ## 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. # KYB-Gesellschafter-API für Unternehmensregister > Didit: POST /v3/kyb/shareholders/ mit kyb_response_id aus der Registersuche liefert Unternehmensprofil, Geschäftsführer und direkte Gesellschafter. Verwenden Sie diesen Endpoint, nachdem `POST /v3/kyb/search/` Kandidatenunternehmen zurückgegeben hat und Sie zusätzlich zum Lite-Profil die **direkten Gesellschafter** benötigen. Der Abruf wird zum Shareholders-Preis des jeweiligen Landes abgerechnet ([Preise je Land](https://docs.didit.me/de/getting-started/kyb-registry-pricing.md)). Wenn das Register für das Unternehmen keinen Gesellschafterdatensatz führt oder das Land überhaupt keine Eigentümerdaten bereitstellt, wird stattdessen das Lite-Profil geliefert und abgerechnet: `registry_tier_delivered` ist `basic` und `registry_ownership_status` ist `unavailable`, oder `not_held`, wenn die Eigentümerquelle bestätigt hat, dass sie dieses Unternehmen gar nicht führt ([Eigentümerstatus](https://docs.didit.me/de/standalone-apis/kyb-registry.md#status-der-eigentümerstruktur)). Wenn der Bericht noch erstellt wird oder der Eigentümerabschnitt noch nicht vom Register abgerufen wurde, gibt der Endpoint `202 Accepted`, `kyb_registry.fetch_status: "pending"`, `kyb_registry.registry_ownership_status: "pending"` und `registry_tier_delivered: null` zurück. Bewahren Sie die zurückgegebene `request_id` auf und rufen Sie `GET /v3/session/{request_id}/decision/` ab, bis `registry_checks[0].company.fetch_status` den Wert `resolved` hat. Didit schließt den ausstehenden Bericht automatisch ab und rechnet die gelieferte Stufe ab, sobald er fertig ist. Senden Sie die Kaufanfrage während der Wartezeit nicht erneut: Jede neue POST-Anfrage erzeugt eine separate Anfrage. Nur in v3 verfügbar. `POST /v2/kyb/select/` und `POST /v3/kyb/select/` behalten ihren Vertrag und ihren Preis bei. ## OpenAPI ````yaml de/openapi-25.json POST /v3/kyb/shareholders/ 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/kyb/shareholders/: post: tags: - Standalone APIs summary: KYB-Unternehmensabfrage im Register mit Gesellschaftern (eigenständig) description: >- Rufen Sie das Lite-Profil **zuzüglich der direkten Gesellschafter** (natürliche Personen und juristische Einheiten mit ihren Beteiligungsspannen) eines durch `POST /v3/kyb/search/` zurückgegebenen Kandidaten ab. **Kombination mit der Suche.** Übergeben Sie die `kyb_response_id` des Kandidaten genau so, wie sie von einer Suche derselben Anwendung zurückgegeben wurde. Suchen Sie auf der Stufe, die Sie kaufen möchten (`tier` bei `POST /v3/kyb/search/`), da die Suche auf der Registerkette ausgeführt wird, die diese Stufe bedient, und eine leere Lite-Suche kein Beweis dafür ist, dass das Unternehmensregister das Unternehmen nicht führt. Wenn sich die Eigentümerstruktur-Daten des Landes bei einem anderen Unternehmensregister befinden, sucht Didit das Unternehmen dort anhand der Registernummer ohne zusätzliche Kosten erneut. **Abrechnung.** Abgerechnet zum Gesellschafter-Preis des Landes – siehe [Preise für KYB-Unternehmensregister](/de/getting-started/kyb-registry-pricing). Wenn das Unternehmensregister keinen Gesellschafter-Eintrag für das Unternehmen führt (oder das Land überhaupt keine Eigentümerstruktur-Daten anbietet), wird stattdessen das Lite-Profil geliefert und abgerechnet: Lesen Sie `registry_tier_delivered` und `registry_ownership_status` aus. Das Guthaben wird vor jedem Registeraufruf mit dem Gesellschafter-Preis abgeglichen (`403`, wenn es nicht ausreicht). **Verfügbarkeit.** Nur v3. Jeder Aufruf erstellt eine Unternehmenssitzung (deren ID die `request_id` ist). **Ausstehende Berichte.** Wenn ein Bericht noch vorbereitet wird oder der Eigentümerstruktur-Abschnitt noch nicht aus dem Register abgerufen wurde, gibt der Endpoint 202 Accepted, kyb_registry.fetch_status=pending, kyb_registry.registry_ownership_status=pending und registry_tier_delivered=null zurück. Behalten Sie request_id und rufen Sie GET /v3/session/{request_id}/decision/ ab, bis registry_checks[0].company.fetch_status aufgelöst ist. Didit vervollständigt den Bericht automatisch und berechnet die gelieferte Stufe, sobald er bereit ist. Wiederholen Sie den Kauf nicht, während er aussteht; jedes neue POST erstellt eine separate Anfrage. operationId: post_v3_kyb_shareholders parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/KYBRegistryCandidateRequest' example: kyb_response_id: 69aeeb95febb0f1704042259 vendor_data: company-1234 responses: '200': description: >- Unternehmensbericht zurückgegeben und zur gelieferten Stufe abgerechnet. Eigentümerstruktur-Berichte, die noch vorbereitet werden, können 202 zurückgeben; behalten Sie request_id, um deren gespeicherte Entscheidung abzurufen. content: application/json: schema: type: object properties: request_id: type: string format: uuid description: >- ID der Unternehmenssitzung, die für diesen Abruf erstellt wurde. Der gespeicherte Datensatz (in der Konsole sichtbar) wird weiter aktualisiert, falls das Register die Abfrage erst nach der Antwort auflöst. registry_tier_requested: type: string enum: - basic - shareholders - ubo description: >- Die Stufe, die dieser Endpoint bereitstellt: `basic` (Lite) für ausgewählte, `shareholders`, `ubo`. registry_tier_delivered: type: string enum: - basic - shareholders - ubo - null description: >- Die tatsächlich gelieferte und abgerechnete Stufe. Niedriger als angefordert, wenn die Register des Landes keine Eigentümerdaten enthalten oder das Register keinen Eigentümereintrag für dieses Unternehmen führt. nullable: true kyb_registry: type: object description: Vollständiges Unternehmensprofil aus dem Register. properties: uuid: type: string format: uuid description: Didits ID für diesen Unternehmensdatensatz. node_id: type: string example: feature_kyb_registry status: type: string enum: - Not Finished - Approved - Declined - In Review description: >- Didits Bewertung der Registerprüfung (z. B. `In Review`, wenn das Unternehmen im Register nicht aktiv ist oder die Daten zur Eigentümerstruktur nicht abgeleitet werden konnten). registry_status: type: string nullable: true enum: - active - dissolved - deregistered - see full details - authorised - appointed representative - unauthorised - inactive - no longer authorised - closed - struck off - null description: >- Normalisierter Unternehmensstatus gemäß den Angaben des Registers. data_resolved: type: boolean description: >- `true`, sobald das Register das vollständige Profil zurückgegeben hat. `false`, wenn das Register nach dem Polling noch in Bearbeitung war – der gespeicherte Datensatz wird automatisch vervollständigt, sobald das Register den Vorgang abgeschlossen hat. company_name: type: string example: Tesco PLC registration_number: type: string nullable: true example: '00445790' country_code: type: string description: ISO 3166-1-Alpha-2. example: GB region: type: string nullable: true description: >- Unterteilungscode, wenn das Register regional ist (z. B. `CA` für `US-CA`); andernfalls leer. company_type: type: string nullable: true example: Public Limited Company incorporation_date: type: string format: date nullable: true example: '1947-11-27' registered_address: type: string nullable: true example: >- Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, United Kingdom, AL7 1GA tax_number: type: string nullable: true example: GB412 8925 93 risk_level: type: string nullable: true description: Vom Register gemeldete Risikostufe, sofern verfügbar. verification_status: type: string enum: - verified - failed - unknown nullable: true description: >- Status der jurisdiktionsübergreifenden Verifizierung: `verified`, wenn der Registerstatus den Fortbestand bestätigt (`active`), `failed`, wenn das Unternehmen laut Register nicht mehr besteht (z. B. `dissolved`), andernfalls `unknown`. `null` bei einem Unternehmen, das nicht aus einem Register stammt, sowie solange eine Auswahl noch `pending` ist. is_from_registry: type: boolean description: >- Für diesen Endpoint immer `true` – das Profil wurde aus einem offiziellen Register abgerufen. fetch_status: type: string enum: - pending - resolved description: >- Lebenszyklus des Registerabrufs. Gespiegelt durch `data_resolved`. alternative_names: type: string nullable: true description: >- Alternative Namen, Handelsnamen, frühere Namen oder Unternehmensnamen in der Originalsprache als Text, sofern gemeldet. nature_of_business: type: string nullable: true description: >- Tätigkeitsbeschreibung oder Klassifizierungscode, sofern gemeldet. registered_capital: type: string nullable: true registered_capital_amount: type: string nullable: true description: Dezimalbetrag als Zeichenkette, sofern gemeldet. registered_capital_currency: type: string nullable: true description: ISO 4217-Code, sofern gemeldet. website: type: string nullable: true example: https://www.tesco.com/ email: type: string nullable: true example: customer.service@tesco.co.uk phone: type: string nullable: true example: '03301231688' legal_entity_identifier: type: string nullable: true description: LEI, sofern gemeldet. location_of_registration: type: string nullable: true description: >- Register/Jurisdiktion, bei dem/der das Unternehmen eingetragen ist, sofern gemeldet. vat_number: type: string nullable: true description: >- EU-USt-IdNr., wenn während des gehosteten Registerschritts erfasst oder nachträglich bearbeitet. Zum Zeitpunkt der Auswahl ist dies normalerweise noch nicht festgelegt – die Validierung von USt-IdNr. und Steuernummer wird ausgeführt, wenn der Endbenutzer den Registerschritt im gehosteten Ablauf übermittelt. vat_validation_status: type: string enum: - valid - invalid - format_valid - invalid_format - could_not_validate - not_applicable description: >- Ergebnis der Validierung der USt-IdNr. oder, falls keine vorhanden ist, der `tax_number` bei der Registerübermittlung. `valid` / `invalid`: entschieden durch das offizielle Register des Landes (EU-VIES, Norwegen, Schweiz, Brasilien, Kolumbien, Costa Rica, Ecuador, Paraguay; Polen auch über sein nationales USt-Register). `format_valid` / `invalid_format`: entschieden durch die Format- und Prüfzifferregeln des Landes, wenn kein Register abgefragt werden kann. `could_not_validate`: das Register war nicht verfügbar. `not_applicable`: keine Nummer, ein Land ohne Register oder Regeln oder eine Sandbox-Sitzung. vat_validated_number: type: string nullable: true description: >- Die geprüfte Nummer, wie sie der Quelle bekannt ist (beispielsweise die aus einer französischen SIREN oder einer niederländischen RSIN abgeleitete Umsatzsteuer-Identifikationsnummer). `null`, wenn keine Prüfung durchgeführt wurde. vat_validation_source: type: string nullable: true enum: - eu_vies - pl_vat_white_list - no_brreg - ch_uid_register - br_receita_federal - co_rues - cr_hacienda - ec_sri - py_dnit - format_rules - null description: >- Die Quelle, die `vat_validation_status` festgelegt hat: ein offizielles Register oder `format_rules`. `null`, wenn keine Prüfung durchgeführt wurde. vat_validated_name: type: string nullable: true description: >- Name, der bei der Quelle registriert ist, die die Nummer validiert hat, sofern sie einen offenlegt. Wird nur gesetzt, wenn der Status `valid` ist. vat_validated_address: type: string nullable: true description: >- Bei der Quelle registrierte Adresse, die die Nummer validiert hat, sofern diese eine offenlegt. Wird nur festgelegt, wenn der Status `valid` ist. vat_checked_at: type: string format: date-time nullable: true description: >- Zeitstempel der Prüfung. `null`, wenn keine Prüfung durchgeführt wurde. financial_summary: type: object nullable: true description: >- Vom Register gemeldete Anteils-/Kapitaldetails (Währung, Gesamtaktien, Anteilsklassen), sofern verfügbar. officers: type: array items: type: object properties: uuid: type: string format: uuid name: type: string example: MELISSA BETHELL designation: type: string nullable: true description: >- Unverarbeitete Registerbezeichnung (z. B. `Director`, `Secretary`). role: type: string description: >- Normalisierte Rolle, abgeleitet aus der Bezeichnung. Vollständiges Modellset mit 17 Werten; das Register-Parsing an diesem Endpoint gibt typischerweise director, non_executive_director, secretary, chairman oder company_officer aus. enum: - director - non_executive_director - secretary - chairman - ubo - shareholder - representative - founder - legal_advisor - authorized_signatory - trustee - beneficiary - company_officer - settlor - protector - investor - other nationality: type: string nullable: true is_active: type: boolean description: >- `false`, wenn das Register vermerkt, dass die Bestellung niedergelegt wurde. kyc_status: type: string nullable: true enum: - Approved - Declined - Pending - null description: >- Status einer zugehörigen KYC-Sitzung, sofern für diesen Officer eine gestartet wurde. Andernfalls `null`. kyc_session_url: type: string nullable: true description: >- Verifizierungs-URL der zugehörigen KYC-Sitzung, sofern vorhanden. first_name: type: string nullable: true description: >- Vorname, wenn vom Register ausdrücklich gemeldet; nicht aus dem vollständigen Namen abgeleitet. last_name: type: string nullable: true description: Nachname, sofern vom Register explizit gemeldet. address: type: string nullable: true description: Vom Register gemeldete Adresse des Amtsträgers. appointment_date: type: string nullable: true description: Datum, an dem die Führungskraft bestellt wurde. format: date termination_date: type: string nullable: true description: >- Datum, an dem die Bestellung endete, sofern gemeldet. format: date date_of_birth: type: string nullable: true description: >- Vollständiges, vom Unternehmensregister gemeldetes Geburtsdatum. Null, wenn nur ein Geburtsjahr oder -monat bekannt ist. format: date date_of_birth_year: type: integer nullable: true minimum: 1 maximum: 9999 description: >- Vom Register gemeldetes Geburtsjahr, auch wenn das vollständige Datum nicht verfügbar ist. date_of_birth_month: type: integer nullable: true minimum: 1 maximum: 12 description: >- Vom Register gemeldeter Geburtsmonat. Null, wenn nur das Jahr bekannt ist. description: >- Geschäftsführer, Sekretäre und andere Funktionsträger, die aus dem Register extrahiert wurden. beneficial_owners: type: array items: type: object properties: uuid: type: string format: uuid name: type: string first_name: type: string nullable: true last_name: type: string nullable: true entity_type: type: string enum: - person - company description: >- Gibt an, ob der Eigentümer eine natürliche Person oder eine juristische Person ist. roles: type: array items: type: string description: >- Normalisierte Rollen (z. B. `ubo`, `shareholder`). ownership_min_shares: type: string nullable: true description: >- Untergrenze der vom Register gemeldeten Eigentumsspanne (z. B. `25%`). ownership_max_shares: type: string nullable: true description: >- Obergrenze des vom Register gemeldeten Eigentumsbereichs. is_active: type: boolean kyc_status: type: string nullable: true enum: - Approved - Declined - Pending - null kyc_session_url: type: string nullable: true effective_ownership_percent: type: number nullable: true description: >- Geparster Eigentumsanteil (Obergrenze, mit Fallback auf Untergrenze). company_name: type: string nullable: true registration_number: type: string nullable: true country_of_birth: type: string nullable: true email: type: string nullable: true nationality: type: string nullable: true designation: type: string nullable: true voting_min_shares: type: string nullable: true voting_max_shares: type: string nullable: true date_of_birth: type: string nullable: true description: Vollständiges Geburtsdatum, sofern gemeldet. format: date appointment_date: type: string nullable: true description: Datum der Bestellung, sofern gemeldet. format: date shareholding: $ref: '#/components/schemas/KYBRegistryShareholding' description: >- Aus dem Register extrahierte wirtschaftlich Berechtigte / Personen mit maßgeblichem Einfluss. Kann leer sein, wenn das Register die Eigentümerstruktur nicht offenlegt. addresses: type: array nullable: true description: >- Jede vom Register angegebene Adresse in einheitlicher Form. Null, wenn keine angegeben ist. items: $ref: '#/components/schemas/KYBRegistryAddress' industries: type: array nullable: true description: >- Die Tätigkeiten, unter denen das Register das Unternehmen einstuft, in einem kanonischen Format. Null, wenn keine angegeben sind. items: $ref: '#/components/schemas/KYBRegistryIndustry' accounts: type: object nullable: true additionalProperties: true description: >- Register-Einreichungsdaten, sofern verfügbar. Jahresmeldungen und Hauptversammlungen verwenden last_annual_return_date und last_agm_date; sie unterscheiden sich von Finanzabschlüssen. registry_data: $ref: '#/components/schemas/KYBRegistryData' user_provided_data: type: object nullable: true description: >- Auf diesem Endpoint immer `null` (wird vom gehosteten KYB-Workflow verwendet, wenn Endbenutzer Registerdaten bearbeiten). confirmed_by_user_at: type: string format: date-time nullable: true description: Auf diesem Endpoint immer `null`. last_console_edit_at: type: string format: date-time nullable: true description: >- Wird gesetzt, wenn ein Prüfer in der Konsole den Datensatz später bearbeitet. is_editable: type: boolean description: >- Gibt an, ob die aus Registern stammenden Daten im gehosteten Ablauf bzw. der Konsole noch bearbeitet werden können. registry_tier_delivered: type: string enum: - basic - shareholders - ubo - null description: >- Identisch mit dem `registry_tier_delivered` auf oberster Ebene. nullable: true registry_ownership_status: type: string nullable: true enum: - not_requested - delivered - not_held - unavailable - pending - null description: >- `delivered`, wenn die Daten zur Eigentümerstruktur zurückgegeben wurden; `not_held`, wenn das Unternehmensregister geantwortet hat und dieses Unternehmen nicht führt (siehe `registry_data.ownership_error`); `unavailable`, wenn eine Eigentümerstruktur-Stufe angefordert wurde, das Register jedoch keine Daten für dieses Unternehmen hatte oder nicht abgefragt werden konnte (siehe `registry_data.ownership_error`); `pending`, wenn der Abschnitt zur Eigentümerstruktur noch nicht aus dem Register abgerufen wurde und Didit ihn noch vervollständigt; `not_requested` in der Stufe Lite. ownership: $ref: '#/components/schemas/KYBRegistryOwnership' registry_tier: type: string nullable: true description: >- Die vom Workflow angeforderte Register-Stufe: `basic`, `shareholders` oder `ubo`. Auch in `ownership.tier_requested`. registry_monitoring: type: object nullable: true description: >- Der neueste Register-Monitor für das Unternehmen oder `null`, wenn keiner vorhanden ist. properties: uuid: type: string format: uuid status: type: string unavailable_reason: type: string nullable: true enrolled_at: type: string format: date-time nullable: true cancelled_at: type: string format: date-time nullable: true last_bill_date: type: string format: date nullable: true next_bill_date: type: string format: date nullable: true last_event_at: type: string format: date-time nullable: true events_count: type: integer watched_fields: description: Die Unternehmensfelder, die der Monitor überwacht. 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: Resolved company: summary: >- Vollständiges Registerprofil (Liste der Funktionsträger aus Platzgründen gekürzt) value: request_id: 9d4f2c7a-1b3e-4a5c-8d6f-0e9a8b7c6d5e kyb_registry: uuid: f1e2d3c4-b5a6-4789-9c0d-1e2f3a4b5c6d node_id: feature_kyb_registry status: In Review registry_status: active data_resolved: true company_name: Tesco PLC registration_number: '00445790' country_code: GB region: '' company_type: Public Limited Company incorporation_date: '1947-11-27' registered_address: >- Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, United Kingdom, AL7 1GA tax_number: GB412 8925 93 risk_level: low risk verification_status: verified is_from_registry: true fetch_status: resolved alternative_names: TESCO STORES (HOLDINGS) PUBLIC LIMITED COMPANY nature_of_business: null registered_capital: null registered_capital_amount: null registered_capital_currency: null website: https://www.tesco.com/ email: customer.service@tesco.co.uk phone: '03301231688' legal_entity_identifier: null location_of_registration: null financial_summary: currency: Pound (£) total_number_of_shares: '8174378721' meta_detail: Class_Of_Share: Ordinary officers: - uuid: a1b2c3d4-e5f6-4789-9a0b-1c2d3e4f5a6b name: CHRISTOPHER JON TAYLOR designation: Secretary role: secretary nationality: null is_active: true kyc_status: null kyc_session_url: null - uuid: b2c3d4e5-f6a7-4890-8b1c-2d3e4f5a6b7c name: MELISSA BETHELL designation: Director role: director nationality: British is_active: true kyc_status: null kyc_session_url: null beneficial_owners: [] addresses: - address: >- Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, United Kingdom, AL7 1GA type: legal_entity_registry_address description: registered office address industries: null accounts: last_account: 26 February 2025 next_account: 26 February 2026 due_by_date: 26 August 2026 registry_data: {} user_provided_data: null confirmed_by_user_at: null last_console_edit_at: null is_editable: true vendor_data: company-1234 metadata: null created_at: '2026-06-11T10:45:00.000000+00:00' '202': description: >- Bericht akzeptiert und wird noch verarbeitet. Wenn ein Bericht noch vorbereitet wird, gibt der Endpoint 202 Accepted, kyb_registry.fetch_status=pending und registry_tier_delivered=null zurück. Behalten Sie request_id und rufen Sie GET /v3/session/{request_id}/decision/ ab, bis registry_checks[0].company.fetch_status aufgelöst ist. Didit schließt den Bericht automatisch ab und stellt die gelieferte Stufe in Rechnung, sobald er bereit ist. Wiederholen Sie den Kauf nicht, während er aussteht; jedes neue POST erstellt eine separate Anfrage. content: application/json: schema: $ref: b3476782-980b-428b-9968-7677ee0b87d4 examples: Pending (registry still resolving): summary: >- Bericht zur Eigentümerstruktur wird noch verarbeitet; die gespeicherte Entscheidung abrufen value: request_id: 9d4f2c7a-1b3e-4a5c-8d6f-0e9a8b7c6d5e kyb_registry: uuid: 7c0a4f7e-2b1d-4f6a-9c3e-8d5b2a1f0e9d node_id: feature_kyb_registry status: Not Finished registry_status: null data_resolved: false company_name: Example Holdings Limited registration_number: '12345678' country_code: HK region: null company_type: null incorporation_date: null registered_address: null tax_number: null risk_level: null verification_status: null is_from_registry: true fetch_status: pending alternative_names: null nature_of_business: null registered_capital: null registered_capital_amount: null registered_capital_currency: null website: null email: null phone: null legal_entity_identifier: null location_of_registration: null financial_summary: {} officers: [] beneficial_owners: [] addresses: null industries: null accounts: null registry_data: {} user_provided_data: null confirmed_by_user_at: null last_console_edit_at: null is_editable: true registry_tier_delivered: null registry_ownership_status: pending vendor_data: company-1234 metadata: null created_at: '2026-06-11T10:45:00.000000+00:00' registry_tier_delivered: null registry_tier_requested: shareholders '400': description: >- Validierungsfehler. Probleme auf Feldebene verwenden die Standard-Envelope von DRF. content: application/json: examples: Missing kyb_response_id: summary: '`kyb_response_id` ist erforderlich' value: kyb_response_id: - This field is required. save_api_request=false rejected: summary: Auswahlen werden immer persistent gespeichert value: save_api_request: - >- KYB registry select must be saved so billing and retrieval can be tracked. '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 security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: |- curl -X POST https://verification.didit.me/v3/kyb/shareholders/ \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "kyb_response_id": "69aeeb95febb0f1704042259", "vendor_data": "company-1234" }' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.kyb.list_shareholders( kyb_response_id="69aeeb95febb0f1704042259", vendor_data="company-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.kyb.listShareholders({ kyb_response_id: "69aeeb95febb0f1704042259", vendor_data: "company-1234", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.KYB.ListShareholders(ctx, didit.KYBRegistryCandidateRequest{\n\tKYBResponseID: \"69aeeb95febb0f1704042259\",\n\tVendorData: didit.String(\"company-1234\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import me.didit.Didit; import me.didit.types.KYBRegistryCandidateRequest; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.kyb().listShareholders(KYBRegistryCandidateRequest.builder() .kybResponseId("69aeeb95febb0f1704042259") .vendorData("company-1234") .build()); System.out.println(result); - lang: php label: PHP source: |- kyb->listShareholders([ 'kyb_response_id' => '69aeeb95febb0f1704042259', 'vendor_data' => 'company-1234', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.kyb.list_shareholders( kyb_response_id: "69aeeb95febb0f1704042259", vendor_data: "company-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.Kyb.ListShareholdersAsync(new KYBRegistryCandidateRequest { KybResponseId = "69aeeb95febb0f1704042259", VendorData = "company-1234", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: KYBRegistryCandidateRequest: type: object required: - kyb_response_id properties: kyb_response_id: type: string maxLength: 1024 description: >- Kandidaten-Handle aus `POST /v3/kyb/search/` (`kyb_registry.companies[].kyb_response_id`). Flüchtig: Verwenden Sie es kurz nach der Suche, die es erzeugt hat. Handles können lang sein; speichern und senden Sie den Wert daher genau so, wie er zurückgegeben wurde, ohne ihn zu kürzen oder eine bestimmte Länge anzunehmen. example: 69aeeb95febb0f1704042259 vendor_data: type: string description: >- Ihre Kennung für dieses Unternehmen; wird zurückgegeben und mit der Unternehmenssitzung gespeichert. metadata: type: object nullable: true description: >- Freiform-JSON, das mit der Unternehmenssitzung gespeichert und zurückgegeben wird. save_api_request: type: boolean default: true description: >- Muss `true` sein (Standardwert). Auswahlen aus dem KYB-Register werden immer dauerhaft gespeichert, damit Abrechnung und Abruf nachverfolgt werden können; `false` gibt `400` zurück. KYBRegistryShareholding: type: object nullable: true description: >- Was ein Eigentümer hält, im selben Format für jedes Land und jede Registerquelle. Null, wenn das Register keine Beteiligung angibt. Eine Spanne (z. B. 25-50% bei einem britischen PSC) ist keine Beteiligung: `percentage` ist null und die Spanne verbleibt in `ownership_min_shares` / `ownership_max_shares`. properties: share_class: type: string nullable: true description: Aktienklasse oder -typ, wie im Register angegeben. number_of_shares: type: number nullable: true description: Anzahl der gehaltenen Anteile. currency: type: string nullable: true description: ISO 4217-Währung der untenstehenden Werte. nominal_value: type: number nullable: true description: Nennwert pro Aktie. total_value: type: number nullable: true description: Gesamtwert der Beteiligung. percentage: type: number nullable: true description: Exakter Anteil in Prozent auf vier Dezimalstellen genau. required: - share_class - number_of_shares - currency - nominal_value - total_value - percentage KYBRegistryAddress: type: object description: >- Eine vom Register angegebene Adresse, im selben Format für jedes Land und jede Registerquelle. Jeder Schlüssel ist immer vorhanden; ein Teil, den das Register nicht veröffentlicht, ist null. properties: type: type: string nullable: true description: >- Adresstyp in Kleinbuchstaben: `registered` für den eingetragenen Sitz; andere Typen so, wie das Register sie benennt (beispielsweise `postal`, `office`). `null`, wenn das Register nicht angibt, worum es sich bei der Adresse handelt. address: type: string description: >- Die vollständige Adresse in einer Zeile. Bei jeder Adresse stets vorhanden. street: type: string nullable: true description: Straße und Hausnummer. city: type: string nullable: true description: Stadt oder Ortschaft. postal_code: type: string nullable: true description: Postleitzahl. region: type: string nullable: true description: Region, Bundesstaat oder Provinz. country_code: type: string nullable: true description: ISO 3166-1 Alpha-2-Ländercode. description: type: string nullable: true description: >- Die registerspezifische Bezeichnung für die Adresse, sofern das Register eine angibt. required: - type - address - street - city - postal_code - region - country_code - description KYBRegistryIndustry: type: object description: >- Eine Aktivität, unter die das Register das Unternehmen einstuft, im selben Format für jedes Land und jede Registerquelle. properties: code: type: string nullable: true description: Tätigkeitscode, wie er im Register angegeben ist (z. B. `73110`). description: type: string nullable: true description: Tätigkeitsbezeichnung, sofern vom Register veröffentlicht. scheme: type: string nullable: true description: >- Klassifikationssystem, ein Name pro System, unabhängig von der meldenden Quelle: `UK SIC 2007`, `US SIC`, `NACE Rev. 2`, `NACE Rev. 2.1`, `NAF Rev. 2`, `CNAE`, `SBI`, `NOGA 2008`, `CAE Rev. 4`, `Canada SIC 1977`; andere nationale Systeme behalten die registereigene Bezeichnung bei. Null, wenn das Register das System nicht benennt. is_primary: type: boolean description: >- True für die Haupttätigkeit des Unternehmens. Genau ein Eintrag ist primär, wenn die Liste nicht leer ist. required: - code - description - scheme - is_primary KYBRegistryData: type: object nullable: true description: >- Didits normalisierte Registerdetails für das Unternehmen: das Ergebnis der Eigentümerstruktur (`ownership_error`, `section_errors`, `ubo_resolution`, `lite_enrichment`), die mit update-data vorgenommenen Korrekturen und Registerfakten, die kein eigenes Feld haben. Es enthält niemals den eigenen Datensatz der Registerquelle. Jeder Schlüssel ist optional und nur vorhanden, wenn das Unternehmen einen Wert dafür hat; neue Schlüssel können hinzugefügt werden. Lesen Sie die kanonischen Felder (`addresses`, `industries`, `ownership`, `beneficial_owners[].shareholding`) für alles, was diese abdecken. properties: company_name: type: string description: Unternehmensname wie in der Console korrigiert. registration_number: type: string description: Registernummer laut Register oder Console-Korrektur. country_code: type: string description: Land der Registrierung gemäß Register oder Korrektur in der Konsole. region: type: string description: Region oder Bundesstaat der Registrierung. incorporation_date: type: string description: Gründungsdatum (ISO 8601). registration_date: type: string description: >- Eintragungsdatum (ISO 8601), wenn das Register dieses getrennt vom Gründungsdatum ausweist. dissolution_date: type: string description: >- Auflösungsdatum (ISO 8601), sofern im Unternehmensregister angegeben. tax_number: type: string description: Steueridentifikationsnummer. vat_number: type: string description: Umsatzsteuer-Identifikationsnummer. legal_address: type: string description: Rechtliche Adresse, wie sie in der Konsole korrigiert wurde. registered_address: type: string description: Eingetragene Adresse laut Registerangabe. company_type: type: string description: Rechtsform. registry_status: type: string description: Unternehmensstatus im Unternehmensregister. verification_status: type: string description: Verifizierungsstatus. alternative_names: type: string description: >- Andere Namen, unter denen das Unternehmen firmiert oder firmiert hat. nature_of_business: type: string description: Tätigkeitsbeschreibung. registered_capital: type: string description: Eingetragenes Kapital wie abgedruckt. registered_capital_amount: type: string description: Eingetragenes Stammkapital als Dezimal-String. registered_capital_currency: type: string description: Währung des eingetragenen Stammkapitals (ISO 4217). website: type: string description: Website. email: type: string description: Kontakt-E-Mail. phone: type: string description: Telefonnummer des Kontakts. legal_entity_identifier: type: string description: Legal Entity Identifier (LEI). location_of_registration: type: string description: Registrierungsort. control_scheme: type: string description: Governance-Schema, sofern vom Register bereitgestellt. ownership_error: type: string enum: - no_owners_on_record - no_natural_person_owner - ownership_section_unavailable - company_not_found - ambiguous_company_match - missing_registration_number - entity_type_not_covered - provider_unavailable - other description: >- Warum eine angeforderte Eigentümerstruktur-Stufe nicht geliefert wurde, in denselben Codes wie `ownership.unavailable_reason`. `no_owners_on_record` (das Unternehmensregister hat geantwortet und nennt keine Eigentümer) und `ownership_section_unavailable` (das Unternehmensregister hat den Abschnitt zur Eigentümerstruktur nicht zurückgegeben) sind unterschiedliche Ergebnisse. section_errors: type: object description: >- Abschnitte, die das Register nicht zurückgegeben hat, aufgeschlüsselt nach Abschnitt (`officers`, `shareholders`, `group_structure`). Ein hier aufgeführter Abschnitt wurde nie übermittelt: Eine leere Liste daneben sagt nichts über das Unternehmen aus. additionalProperties: $ref: '#/components/schemas/KYBRegistrySectionError' ubo_resolution: $ref: '#/components/schemas/KYBRegistryUboResolution' lite_enrichment: $ref: '#/components/schemas/KYBRegistryLiteEnrichment' registry_metadata: type: object additionalProperties: oneOf: - type: string - type: number - type: boolean description: >- Die registerspezifischen Felder für das Unternehmen, mit den Bezeichnungen des Registers als Schlüssel, als einfache Werte (Legacy-Datensätze). Es sind nur Felder enthalten, die als Register-Fakten geprüft wurden. registry_sources: type: array description: >- Die offiziellen Register, aus denen der Datensatz gelesen wurde (Legacy-Datensätze). Andere Quellen werden nicht genannt. items: $ref: '#/components/schemas/KYBRegistrySource' previous_names: type: array items: type: string description: >- Namen, unter denen das Unternehmen zuvor registriert war (historische Datensätze). parent_companies: type: array items: type: string description: Muttergesellschaften, die das Register nennt (Altdaten). documents_available: type: integer description: >- Wie viele Einreichungen das Register für das Unternehmen anbietet (Altdaten). KYBRegistryOwnership: type: object description: >- Das Ergebnis der Eigentümerstruktur-Stufe (Gesellschafter / UBO), in derselben Form für jedes Land und jede Registerquelle. properties: status: type: string nullable: true enum: - not_requested - pending - delivered - not_held - unavailable - null description: >- `delivered`, wenn das Register die Eigentümerstruktur veröffentlicht hat; `not_held`, wenn das Unternehmensregister geantwortet hat und das Unternehmen überhaupt nicht führt (siehe `unavailable_reason`); `unavailable`, wenn es die Daten zur Eigentümerstruktur aus einem anderen Grund nicht bereitgestellt hat (siehe `unavailable_reason`); `pending`, während das Register diese noch abruft; `not_requested` für die Stufe Basic. tier_requested: type: string nullable: true enum: - basic - shareholders - ubo - null description: Die vom Workflow bestellte Stufe. tier_delivered: type: string nullable: true enum: - basic - shareholders - ubo - null description: >- Die vom Register gelieferte (und abgerechnete) Stufe. Eine UBO-Anfrage, die nur mit direkten Gesellschaftern beantwortet wird, lautet `shareholders`. unavailable_reason: type: string nullable: true enum: - no_owners_on_record - no_natural_person_owner - ownership_section_unavailable - company_not_found - ambiguous_company_match - missing_registration_number - entity_type_not_covered - provider_unavailable - other - null description: >- Warum eine angeforderte Eigentümerstruktur-Stufe nicht geliefert wurde. Null, es sei denn, `status` ist `unavailable` oder `pending`. direct_ownership_complete: type: boolean nullable: true description: >- True, wenn die angegebenen Anteile der direkten Gesellschafter in Summe 100% ergeben (innerhalb eines Prozentpunkts Rundungstoleranz); false, wenn dies nicht der Fall ist; null, wenn die Eigentümerstruktur nicht übermittelt wurde oder ein Anteil nicht angegeben ist. unresolved: type: array description: >- Teile der Eigentümerstruktur, die das Register nicht auflösen konnte, beispielsweise keine eingetragene Konzernstruktur über den direkten Eigentümern. items: type: object properties: reason: type: string section: type: string nullable: true required: - status - tier_requested - tier_delivered - unavailable_reason - direct_ownership_complete - unresolved KYBRegistrySectionError: type: object description: Ein Abschnitt, den das Unternehmensregister nicht zurückgegeben hat. properties: status_code: type: integer nullable: true description: Der Status, den das Register für den Abschnitt zurückgemeldet hat. required: - status_code KYBRegistryUboResolution: type: object description: >- Wie die UBO-Stufe die Eigentümerstruktur oberhalb des Unternehmens durchlaufen hat. properties: parent_chain: type: array description: >- Konzernmütter von der obersten Muttergesellschaft bis hin zum Unternehmen. items: $ref: '#/components/schemas/KYBRegistryGroupCompany' subsidiaries: type: array description: >- Unternehmen direkt unterhalb des Unternehmens in seiner Unternehmensgruppe. items: $ref: '#/components/schemas/KYBRegistryGroupCompany' unresolved: type: array description: >- Teile der Kette, die das Register nicht auflösen konnte (dieselben Einträge wie `ownership.unresolved`). items: type: object properties: reason: type: string description: >- Der Grund, zum Beispiel `no_group_structure_on_record`, `selected_company_not_in_group_structure` oder `section_error`. section: type: string nullable: true description: Der betroffene Abschnitt, zum Beispiel `group_structure`. required: - reason - section required: - parent_chain - subsidiaries - unresolved KYBRegistryLiteEnrichment: type: object description: >- Leere Lite-Profilfelder, die eine andere Registerquelle des Landes ausgefüllt hat. Die Quelle wird nicht benannt. properties: fields: type: array items: type: string description: Die Unternehmensfelder, die ausgefüllt wurden. people_added: type: integer description: Wie viele Geschäftsführer oder Eigentümer hinzugefügt wurden. required: - fields - people_added KYBRegistrySource: type: object description: >- Ein offizielles Register, aus dem der Datensatz ausgelesen wurde. Es werden nur offizielle staatliche Register, Regulierungsbehörden und das offizielle Identifikationssystem benannt; jede andere Quelle wird weggelassen. properties: name: type: string description: Name des Registers, zum Beispiel `UK Companies House`. source_type: type: string enum: - official description: Immer `official`. required: - name - source_type KYBRegistryGroupCompany: type: object description: Ein Unternehmen der Unternehmensgruppe anhand seiner Registeridentität. properties: name: type: string nullable: true description: Unternehmensname. country_code: type: string nullable: true description: Registrierungsland. registration_number: type: string nullable: true description: Registernummer. required: - name - country_code - registration_number 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.