Organisations-KYC/KYB/IDV-Integration

Schritt 5 der Quickstart nennt zwei harte Gates für Live-Traffic: ein freigegebenes Organisations-KYC und ein aufgeladenes Guthaben. Organisations-KYC ist eine einmalige Prüfung pro Workspace — sie verifiziert das Unternehmen selbst, nicht seine Rufnummern (die per-Rufnummer-Dokumentbündel sind ein separater Punkt; vergleichen Sie am Ende). Der Guide behandelt die volle Schleife — Einreichung, optionale gehostete Identitätsprüfung, Abfrage des Ergebnisses, erneute Einreichung bei Ablehnung — danach die übrigen Go-live-Gates.

1. Warum Live-Traffic blockiert ist

Live-Sends bleiben eingeschränkt, bis ein Mitglied des Devotel-Betriebteams ein tatsächliches Unternehmenprofil geprüft hat. Bis die Freigabe vorliegt:

Rufnummern kaufen bleibt möglich, aber kein SMS-, WhatsApp- oder Sprachverkehr verlässt die Plattform.
Das Dashboard zeigt den Status in einem Banner; die hier behandelte Seite ist unter Einstellungen → KYC erreichbar.

Zwei Status treiben die Prüfung voran. not_started bedeutet, das Formular wurde nie eingereicht. pending_review bedeutet, eine Operator-Warteschlange hält die Einreichung (der E-Mail-Bestätigungs-Webhook stellt dies am Signup vor; das Formular unten ersetzt es durch reiche Details). Nach einer Entscheidung erhalten Sie approved oder rejected.

2. Reichen Sie das Formular ein

POST auf /api/v1/organization/kyc/submit mit dem Unternehmenprofil. Der API prüft: Firmenname und Land erforderlich, Website optional, Verwendungsbeschreibung mindestens zehn Zeichen, optional bis zu 20 beneficial-owner-Einträge.

curl -X POST https://api.orbit.devotel.io/api/v1/organization/kyc/submit \
  -H "X-API-Key: $ORBIT_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Acme Logistics Ltd.",
    "company_website": "https://acme-logistics.example",
    "country": "US",
    "industry": "Logistik",
    "use_case": "Lieferstatus-Benachrichtigungen an Kunden, die beim Checkout zugestimmt haben.",
    "estimated_monthly_volume": 45000,
    "registration_number": "DE-554433",
    "beneficial_owners": [
      { "name": "Maria Alvarez", "ownership_percentage": 100 }
    ]
  }'

import { Devotel } from '@devotel-orbit/node';

const orbit = new Devotel({ apiKey: process.env.ORBIT_API_KEY });

const result = await orbit.organization.kyc.submit({
  company_name: 'Acme Logistics Ltd.',
  company_website: 'https://acme-logistics.example',
  country: 'US',
  industry: 'Logistik',
  use_case: 'Lieferstatus an zustimmende Kunden.',
  estimated_monthly_volume: 45000,
});
console.log(result.data.status); // "pending_review"

Eine erfolgreiche Antwort stempelt pending_review und gibt den gespeicherten Datensatz plus das Screening-Verdict zurück — die Prüfung ist menschlich, nichts wird automatisch freigegeben oder abgelehnt. Antwort (200):

{
  "data": {
    "status": "pending_review",
    "kyc": {
      "status": "pending_review",
      "company_name": "Acme Logistics Ltd.",
      "country": "US",
      "submitted_at": "2026-09-04T09:12:33Z"
    },
    "kyb": {
      "status": "review",
      "matches": [],
      "legal_name": "Acme Logistics Ltd.",
      "country": "US",
      "screened_at": "2026-09-04T09:12:33Z"
    },
    "message": "Your KYC submission has been received and is awaiting review."
  },
  "meta": { "request_id": "req_abc123", "timestamp": "2026-09-04T09:12:33Z" }
}

data.kyb ist das Unternehmen-Screening (clear wenn die Entity clean ist, review wenn eine sankktionierte Region oder eine verweigerte Partei gepasst hat). Es wird mit dem Formular geprüft — blockiert die Einreichung nie und erfordert auch bei review dieselbe menschliche Prüfung. Das Feld fehlt, wenn das Screening nicht laufen konnte (dann wird eine manuelle Überprüfung angemeldet).

3. Marktpayloads — was Ihre Destination tatsächlich verlangt

Das obige Formular wird pro Organisation einmal eingereicht, doch welche Felder der Prüfer am stärksten gewichtet, hängt von der Destination ab. Das country verankert den Markt — geben Sie ihn als Zielmarkt ein, nicht als Rechnungsadresse; ein UK-Sender mit country: "US" erhält nur eine Rückfrage zur Korrektur. Zwei Feldgruppen erreichen stets den Prüfer: das Freitext use_case und die KYB-Identitätsfelder (registration_number, beneficial_owners). Organisationen, die mehrere blockierte Destinationen bedienen, wiederholen das Dokumentmodell pro Destination — gruppieren Sie Uploads pro Ziel in der Dokumentenbibliothek, statt ein Formular zu verwässern. Die folgenden Märkte halten Sends vor einer Vorregistrierung. Für jeden: die hervorzuhebenden Profilfelder und die geforderten Dokumentrollen. Uploads liegen unter Compliance → Dokumente und werden per ID in Registrierungen referenziert; die prüfersichtbaren Rollen sind business_doc, address_proof, id_proof, authorization. Die Sender-ID-Marktmatrix nennt den live-Wert registration pro Land; der Documents Guide deckt den Uploadfluss ab.

Deutschland — BNetzA Entity-Identität

BNetzA (Bundesnetzagentur) prüft die Identität hinter jeder alphabetyptischen Route und jeder Voice-KYC. Gewichten Sie registration_number (Handelsregistereintrag) und eine richtige Rechtsform. Geforderte Dokumente: business_doc (Handelsregisterauszug).

Spanien — CNMC Sender-ID-Registrierung

Die CNMC erlaubt Sends auf alphabetyptischen Sendern erst nach Registrierung. Gewichten Sie registration_number und ein use_case auf spanische Empfänger ausgelegt. Dokumente: business_doc (CIF/NIF der Entität).

Frankreich — ARCEP Absender-Registrierung

Die ARCEP und die Träger registreren die Identität hinter dem alphabetyptischen Sender; nicht angemeldete Marken erhalten SMS-Routen-Ablehnungen. Gewichten Sie registration_number (RCS-Immatrikulation) mit einem referenziertem use_case. Dokumente: business_doc (Kbis-Extrakt oder SIREN) plus authorization, wenn eine Agentur im Namen der Marke einreicht.

Türkei — BTK Sender-Name

Die BTK registriert den Absendernamen, nicht nur die Route — hinterlegen Sie den Namen, den Ihre Kunden sehen, und nennen Sie ihn in use_case. Dokumente: business_doc (Handelskammer-Dokumente).

Arabische Märkte — Beispiel VAE TDRA

Einige arabische Märkte (z. B. VAE, TDRA plus Träger e&/du) erwarten eine KYC-abgesicherte Markenidentität am Absender — der Overlay, der dünnen Einreichungen am ehesten abschwirrt. Gewichten Sie company_name, company_website und ein vollständiges use_case. Dokumente: business_doc plus Marken-authorization. In jedem Markt gilt dasselbe: Entscheiden Sie, was in company_name, use_case und registration_number steht, bevor ein Sende-Gate den Traffic mit einer 422 abwehrt. Send Gates erläutert, wie eine required-Destination unregistrierte Sends blockiert. Für die Lesart englischer oder historisch englischer Märkte (UK, Saudi-Arabien, VAE, Brasilien, Indien DLT, US 10DLC) siehe die englische Version des Guides.

4. Optional: eine gehostete IDV-Session hinzufügen

Einige Träger verlangen ein staatliches Ausweisdokument plus einen Liveness-Check vor der Unterzeichnung. POST /api/v1/organization/kyc/idv/session öffnet eine gehostete Session beim konfigurierten Provider; öffnen Sie die zurückgegebene URL im Browser oder geben Sie sie an den Unterzeichner.

cURL

curl -X POST https://api.orbit.devotel.io/api/v1/organization/kyc/idv/session \
  -H "X-API-Key: $ORBIT_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "redirect_url": "https://your-app.example/kyc/return" }'

Antwort (200):

{
  "data": {
    "status": "pending",
    "provider": "idv",
    "session_id": "sess_9f2b7c",
    "hosted_url": "https://hosted-idv.example/sessions/sess_9f2b7c",
    "reason": null,
    "created_at": "2026-09-04T09:13:04Z",
    "updated_at": "2026-09-04T09:13:04Z"
  },
  "meta": { "request_id": "req_def456", "timestamp": "2026-09-04T09:13:04Z" }
}

Bis ein Operator einen Vendor bereitstellt, antwortet der Endpoint mit 503:

{ "error": { "code": "IDV_NOT_CONFIGURED", "message": "Identity verification is not available for this account", "status": 503 } }

Prüfen Sie den Provider-Verdict mit GET /api/v1/organization/kyc/idv/status. Er reconciliiert sich selbst: solange die gespeicherte Session pending ist, fragt jeder GET den Provider nach dem neuesten Ergebnis und schreibt die finale Transition zurück. Ein finales verified, declined oder expired — mit einem reason falls der Provider eines liefert — ergänzt das Signal, das der Operator abwägt. Es ist niemals selbstanerkennend: verified genehmigt KYC NICHT, und declined lehnt es nicht ab.

{
  "data": {
    "status": "verified",
    "provider": "idv",
    "session_id": "sess_9f2b7c",
    "hosted_url": "https://hosted-idv.example/sessions/sess_9f2b7c",
    "reason": null,
    "created_at": "2026-09-04T09:13:04Z",
    "updated_at": "2026-09-04T09:44:12Z",
    "configured": true
  }
}

5. Erfragen Sie das Organisations-Verdict

Poll GET /api/v1/organization/kyc/status bis das Organ-Verdict anliegt. Die möglichen Stände sind not_started, pending (pre-submit transient), pending_review, approved und rejected; die Antwort spiegelt auch die eingereichten Unternehmensfelder und reviewed_at nach einer Entscheidung.

cURL

curl https://api.orbit.devotel.io/api/v1/organization/kyc/status \
  -H "X-API-Key: $ORBIT_TEST_KEY"

Antwort (200):

{
  "data": {
    "status": "pending_review",
    "company_name": "Acme Logistics Ltd.",
    "country": "US",
    "industry": "Logistik",
    "submitted_at": "2026-09-04T09:12:33Z",
    "reviewed_at": null,
    "source": null
  },
  "meta": { "request_id": "req_ghi789", "timestamp": "2026-09-04T09:15:00Z" }
}

Ältere SDK-Builds lesen manchmal den nackten GET /api/v1/organization/kyc-Pfad; er liefert das gleiche Antwortschema, also ist ein Ziel auf /kyc/status sicher und kompatibel. Der Endpoint ist sicher vom Dashboard oder einem Server abzupollern — er degradiert bei einem kurzen Datenbankblip zu einer neutralen not_started-Lesung statt einer 503, und die nächste Abfrage korrigiert sich selbst.

6. Erneute Einreichung und die «ALREADY_VERIFIED»-Grenze

Ein erneutes POST des Formulars ist bei einem rejected die richtige Wahl: der Schreibzugriff stempelt pending_review erneut, überschreibt den Formularblock und durchläuft das Screening mit den korrigierten Antworten. Auch eine noch pending_review erneute Einreichung wird akzeptiert — sie ersetzt den laufenden Profil. Eine approved Organisation erneut zu einzureichen ergibt 409:

{
  "error": {
    "code": "ALREADY_VERIFIED",
    "message": "KYC verification has already been approved",
    "status": 409
  }
}

Dieselbe Grenze gilt für eine IDV-Session, sobald die Identität verified ist — ein POST auf den Session-Endpunkt erhält dann 409 ALREADY_VERIFIED, und eine erneute Erfassung ist nur sinnvoll, wenn die Organisation abgelehnt wurde und erneut angetrieben wird.

7. Was eine Ablehnung bedeutet und was zu tun ist

Eine Ablehnung ist ein menschliches Urteil — der Operator geht das Devotel-Betriebspanel durch, liest Ihre Formularfelder plus die screening- und IDV-Signale und drückt Approve oder Reject. Die kundenorientierte Oberfläche legt nie ein Maschinenrationale frei; die Entscheidungsemail nennt die Lücke und die Korrektur. Behandeln Sie rejected als handlungsrelevante Lesart:

Lesen Sie die eingereichten Felder erneut auf Genauigkeit (eine Diskrepanz beim legalen Namen oder ein dünnes use-case ist das häufigste Flag).
Beheben Sie alle kyb-Matches und jegliche declined-IDV-Ergebnisse.
Reichen Sie mit den korrigierten Daten erneut ein — der Endpoint akzeptiert und die Warteschlange re-organisiert sich.

Wenn die Ablehnung eindeutig ein Versehen ist — etwa ein Tippfehler im Operator-Panel statt in Ihren Daten — melden Sie sich durch den Support mit der Account-ID und der req_*-ID aus der Statusabfrage; der Eigentümer der Review-Warteschlange kann den Vorgang wieder öffnen und operatorseitig freigeben.

Was dieses Gate NICHT ist: per-Rufnummer-Dokumente

Organisations-KYC steht neben den per-Rufnummer-Dokumentbündeln, die Träger pro Sender fordern — letztere (Firmentstellung, Adressnachweis, Identität) decken eine bestimmte, von Ihnen gehaltene Nummer und folgen einer separaten Prüfschleife unter Compliance → Dokumente. Die Genehmigung der Organisation klärt ein per-Rufnummer-Paket nicht, und umgekehrt. Siehe den per-Rufnummer-KYC-Dokumente-Guide für diesen separaten Register.

8. Nach Freigabe — die letzten Go-live-Gates

Freigabe kippt das Organ-Verdict, also liefert GET /organization/kyc/status approved. Schließen Sie die beiden verbleibenden Gates aus der Go-live-Checkliste ab:

Live-Key anzelms. Unter Einstellungen → API Keys einen geheim mit dem Präfix dv_live_sk_ erstellen und den Sandbox-Schlüssel dv_test_sk_ ersetzen — Requestformen sind identisch, also ist kein Code-Umbau nötig.
Guthaben aufladen. Fügen Sie Mittel unter Einstellungen → Billing hinzu; SMS, WhatsApp und Voice ziehen alle von diesem Wallet, und Live-Sends schlagen bei leerem Guthaben mit einer Billing-Fehlermeldung fehl.
US-SMS: 10DLC hinzufügen. Enthält die Destination US-Long-Codes, schließen Sie die 10DLC-Marken- + Kampagnen-Registration ab. Die KYC-Freigabe allein ersetzt die Carrier-Registrierung nie; beide Gates müssen vor einem US-SMS-Send grün sein.

Sobald die zwei Gates plus alle Channel-Registrationen bestanden sind, verhielt sich der Live-Send exakt wie der Sandbox-Send — gleiche Endpoint, gleiches Webhook-Envelope, keine weitere Freigabeschleife.

Getting Started

Channels

Channels (Voice)

AI Agents

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Brand & press

Changelog

Organisations-KYC/KYB/IDV-Integration

Organisations-KYC/KYB/IDV-Integration

1. Warum Live-Traffic blockiert ist

2. Reichen Sie das Formular ein

3. Marktpayloads — was Ihre Destination tatsächlich verlangt

Deutschland — BNetzA Entity-Identität

Spanien — CNMC Sender-ID-Registrierung

Frankreich — ARCEP Absender-Registrierung

Türkei — BTK Sender-Name

Arabische Märkte — Beispiel VAE TDRA

4. Optional: eine gehostete IDV-Session hinzufügen

5. Erfragen Sie das Organisations-Verdict

6. Erneute Einreichung und die «ALREADY_VERIFIED»-Grenze

7. Was eine Ablehnung bedeutet und was zu tun ist

Was dieses Gate NICHT ist: per-Rufnummer-Dokumente

8. Nach Freigabe — die letzten Go-live-Gates

Verwandte Referenzen

​Organisations-KYC/KYB/IDV-Integration

​1. Warum Live-Traffic blockiert ist

​2. Reichen Sie das Formular ein

​3. Marktpayloads — was Ihre Destination tatsächlich verlangt

​Deutschland — BNetzA Entity-Identität

​Spanien — CNMC Sender-ID-Registrierung

​Frankreich — ARCEP Absender-Registrierung

​Türkei — BTK Sender-Name

​Arabische Märkte — Beispiel VAE TDRA

​4. Optional: eine gehostete IDV-Session hinzufügen

​5. Erfragen Sie das Organisations-Verdict

​6. Erneute Einreichung und die «ALREADY_VERIFIED»-Grenze

​7. Was eine Ablehnung bedeutet und was zu tun ist

​Was dieses Gate NICHT ist: per-Rufnummer-Dokumente

​8. Nach Freigabe — die letzten Go-live-Gates

​Verwandte Referenzen

Organisations-KYC/KYB/IDV-Integration

1. Warum Live-Traffic blockiert ist

2. Reichen Sie das Formular ein

3. Marktpayloads — was Ihre Destination tatsächlich verlangt

Deutschland — BNetzA Entity-Identität

Spanien — CNMC Sender-ID-Registrierung

Frankreich — ARCEP Absender-Registrierung

Türkei — BTK Sender-Name

Arabische Märkte — Beispiel VAE TDRA

4. Optional: eine gehostete IDV-Session hinzufügen

5. Erfragen Sie das Organisations-Verdict

6. Erneute Einreichung und die «ALREADY_VERIFIED»-Grenze

7. Was eine Ablehnung bedeutet und was zu tun ist

Was dieses Gate NICHT ist: per-Rufnummer-Dokumente

8. Nach Freigabe — die letzten Go-live-Gates

Verwandte Referenzen