KYB-Anfragen

KYB („Know Your Business“) verifiziert die Identität und Struktur eines Unternehmens. Der Lebenszyklus entspricht dem von KYC — anlegen, unterstützende Dokumente hochladen, einreichen, eine Entscheidung erhalten —, hat aber einen zusätzlichen Schritt: Sie übermitteln eine KYB-Entitäts-Nutzlast, die das Unternehmen und seine Hauptverantwortlichen beschreibt.

Legen Sie die Anfrage mit type: "BUSINESS" an und senden Sie anschließend einen POST an den Endpunkt /kyb, um die Entitätsdaten anzuhängen.

Die KYB-Erweiterung

POST /api/v1/kyc/requests/:id/kyb    Berechtigungsbereich: kyc:write

Hängt Unternehmensdaten, Geschäftsführer und wirtschaftlich Berechtigte (UBOs) an eine bestehende BUSINESS-Anfrage an.

Anfrage-Body

{
  "companyName": "Acme Holdings Ltd",
  "registrationNo": "12345678",
  "countryOfIncorp": "GB",
  "companyType": "private_limited",
  "directors": [
    {
      "fullName": "Jane Doe",
      "dateOfBirth": "1975-06-22",
      "nationality": "GB",
      "appointedAt": "2018-01-15"
    }
  ],
  "ubos": [
    {
      "fullName": "Jane Doe",
      "dateOfBirth": "1975-06-22",
      "nationality": "GB",
      "ownershipPercentage": 100
    }
  ]
}

Jeder Geschäftsführer und jeder UBO enthält fullName, dateOfBirth, nationality sowie rollenspezifische Felder (appointedAt bei Geschäftsführern, ownershipPercentage bei UBOs).

Antwort (201)

{ "id": "req_...", "status": "PENDING_UPLOAD" }

Die Antwort startet außerdem im Hintergrund eine Registerabfrage — Certivant fragt das zuständige Handelsregister ab (Companies House für GB, OpenCorporates für viele weitere) und speichert die Ergebnisse an der Anfrage. Die Registerergebnisse sehen Sie unter GET /kyb.

KYB-Daten abrufen

GET /api/v1/kyc/requests/:id/kyb    Berechtigungsbereich: kyc:read

Liefert die übermittelten Entitätsdaten zusammen mit allen Ergebnissen der Registerabfrage.

Antwort

{
  "id": "kyb_...",
  "requestId": "req_...",
  "companyName": "Acme Holdings Ltd",
  "registrationNo": "12345678",
  "countryOfIncorp": "GB",
  "companyType": "private_limited",
  "directors": [...],
  "ubos": [...],
  "registryLookup": {
    "status": "verified",
    "registryName": "Companies House",
    "registryUrl": "https://find-and-update.company-information.service.gov.uk/company/12345678",
    "registeredName": "Acme Holdings Ltd",
    "registeredAddress": "1 Example St, London",
    "status": "active",
    "incorporatedAt": "2018-01-15",
    "officerDelta": [],
    "raw": { ... }
  }
}

registryLookup.officerDelta listet alle Organverantwortlichen auf, die im Register gefunden wurden, aber nicht in Ihrem Array directors angegeben sind — nützlich, um fehlende Angaben aufzuspüren.

Erforderliche Dokumente

Eine BUSINESS-Anfrage benötigt in der Regel einen anderen Dokumentensatz als eine Privatperson:

• CERTIFICATE_OF_INCORPORATION — Nachweis, dass das Unternehmen existiert.
• PROOF_OF_ADDRESS — für den eingetragenen Sitz.
• GOVERNMENT_ID und SELFIE für jeden UBO und jeden Geschäftsführer (in manchen Konfigurationen auf Unteranfragen je Antragsteller).
• COMPANY_OWNERSHIP_STRUCTURE — Organigramm oder Gesellschafterliste.

Die genaue Liste erscheint nach dem Anhängen der KYB-Entität in pendingDocTypes der Anfrage. Die KYB-Einstellungen Ihrer Organisation bestimmen, was erforderlich ist.

KYC-Unteranfragen je Organverantwortlichem

Je nach Einstellungen Ihrer Organisation kann Certivant für jeden UBO und jeden Geschäftsführer automatisch individuelle KYC-Unteranfragen anlegen. Diese erscheinen als eigene Anfragen, die über das Feld parentRequestId mit der übergeordneten BUSINESS-Anfrage verknüpft sind. Dokumente laden Sie zu jeder Unteranfrage genauso hoch wie zu einer eigenständigen KYC-Anfrage — siehe Dokumente.

graph LR
  Parent[BUSINESS request<br/>req_parent] --> Co[Company docs<br/>incorporation, address]
  Parent --> Ubo1[UBO 1 sub-request<br/>req_ubo1]
  Parent --> Ubo2[UBO 2 sub-request<br/>req_ubo2]
  Parent --> Dir1[Director sub-request<br/>req_dir1]
  Ubo1 --> Id1[GOVERNMENT_ID + SELFIE]
  Ubo2 --> Id2[GOVERNMENT_ID + SELFIE]
  Dir1 --> Id3[GOVERNMENT_ID + SELFIE]

Die übergeordnete Anfrage bleibt im Status PENDING_UPLOAD, bis jede Unteranfrage mindestens PROCESSING erreicht hat. Danach durchläuft sie denselben Lebenszyklus wie eine Privatpersonen-Anfrage — PROCESSING → APPROVED / REJECTED / ESCALATED.

Einreichung und Entscheidung

Sobald die Unternehmensdokumente hochgeladen und alle Unteranfragen eingereicht sind, reichen Sie die übergeordnete Anfrage ein:

curl -X POST https://app.certivant.com/api/v1/kyc/requests/req_parent/submit \
  -H "Authorization: Bearer ck_live_..."

Die Risiko-Engine fasst die Unternehmensprüfungen der übergeordneten Anfrage zusammen mit dem Ergebnis jeder Unteranfrage zu einer einzigen Entscheidung zusammen. Die Webhook-Ereignisse werden für die übergeordnete Anfrage ausgelöst — Sie müssen jede Unteranfrage nicht separat verfolgen, es sei denn, Sie möchten eine detaillierte Sicht.

Fehler

• 400 BAD_REQUEST — die Anfrage ist nicht vom Typ BUSINESS. KYB-Endpunkte funktionieren nur bei Unternehmensanfragen.
• 409 CONFLICT — KYB-Daten wurden bereits angehängt. Wenn Sie sie ändern möchten, wenden Sie sich an den Support — die Entitätsdaten sind Teil des Audit-Protokolls und lassen sich nicht frei bearbeiten.

Verwandte Themen

• KYC-Anfragen — die zugrunde liegenden Anfrage-Endpunkte, gleicher Lebenszyklus.
• Dokumente — Hochladen des Gründungsnachweises und der Dokumente je Organverantwortlichem.
• Webhooks — dieselben Ereignisse kyc.request.* gelten.