> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.
# KYC-Dokumente und der Lebenszyklus des Compliance-Profils
> Laden Sie KYC-Dokumente einmal hoch, referenzieren Sie sie per doc_…-ID über Compliance-Profile und Absender-ID-Registrierungen hinweg und erneuern Sie sie, bevor sie veralten und Ihre Nummern blockieren.
# KYC-Dokumente und der Lebenszyklus des Compliance-Profils
Regulierte Märkte akzeptieren kein „Vertrauen Sie mir" – ein Carrier oder
eine Regulierungsbehörde verlangt einen Nachweis darüber, wer Sie sind,
bevor eine Telefonnummer aktiviert wird oder eine Absender-ID Verkehr
tragen darf. Orbit modelliert diesen Nachweis als zwei Dinge, die Ihnen
gehören: eine **Dokumentbibliothek** (die Dateien selbst) und
**Compliance-Profile** (die strukturierte Identität, die die Dokumente
untermauern). Diese Seite erklärt, was ein Profil erfasst, wie Dokumente
vom Upload über die Wiederverwendung bis zur Erneuerung wandern, wo dasselbe
Dokument referenziert wird und wie Sie ein Ablaufdatum kommen sehen, bevor
es Sie eine Nummer kostet.
Alle nachstehenden Endpunkte sind unter
`https://api.orbit.devotel.io/api/v1/compliance` verwurzelt.
Orbit speichert Ihre Dokumente, trägt sie zum Carrier und stellt deren
Prüfstatus dar – **die endgültige Genehmigung wird stets vom Carrier oder
der Regulierungsbehörde des jeweiligen Landes erteilt**, nicht von der
Plattform. Das Bereitstellen und Erneuern der Dokumente selbst bleibt bei
Ihnen.
***
## Was ein Compliance-Profil ist
Ein **Compliance-Profil** (`cprof_…`) ist ein gebündeltes regulatorisches
Identitätspaket: wer der Endnutzer ist, für welchen Anwendungsfall, in
welchem Land. Carrier prüfen das Profil als Einheit – wird es einmal
genehmigt, kann jede Nummer oder jeder Absender, die bzw. der unter dieses
Profil fällt, es nutzen.
| Feld | Was es erfasst |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | Ihre Bezeichnung für das Profil, z. B. „DE local numbers — Acme GmbH". |
| `use_case` | Wofür die Identität bestimmt ist: `phone_number_purchase`, `sms_sender_id_alphanumeric`, `sms_10dlc_brand_us`, `sms_10dlc_campaign_us`, `sms_tfv_us`, `whatsapp_business_verification`, `rcs_brand_verification`, `email_domain_verification`, `voice_carrier_kyc`, `other`. |
| `country_code` / `countries` | Der bzw. die Märkte, auf die das Profil abzielt. Erforderlich für Telefonnummern- und Absender-ID-Anwendungsfälle; optional für länderunabhängige Fälle (WhatsApp, RCS, E-Mail). |
| `end_user_type` | `business` oder `individual` – Regulierer wenden auf jede dieser Kategorien unterschiedliche Dokumentregeln an. |
| strukturierte Daten | Die typisierten Felder, die das Land verlangt (eingetragener Firmenname, Adresse, Steuer-ID, …), gesetzt über `PUT /compliance-profiles/:id/data`. Prüfen Sie mit dem [Regulatory-Preview-Endpunkt](/numbers/regulatory-preview) genau, welche Felder ein Land benötigt, bevor Sie mit dem Ausfüllen beginnen. |
Der eigene Status eines Profils bewegt sich von `draft` über
`pending_review` zu `approved` (oder `rejected` / `partially_rejected`) und
zu `expired`, wenn sein Gültigkeitsfenster abläuft. Nur ein `approved`-
Profil erfüllt die Prüfungen eines Landes.
***
## Der Lebenszyklus eines Dokuments
Dokumente leben in einer mandantenweiten **Bibliothek**, getrennt von
jedem einzelnen Profil. Laden Sie einen Reisepass einmal hoch, und Sie
können ihn heute an ein deutsches Telefonnummern-Profil anhängen und
dieselbe Datei morgen für eine Absender-ID-Registrierung wiederverwenden –
kein zweiter Upload.
### 1. Upload
`POST /compliance/documents` nimmt einen `multipart/form-data`-Upload
entgegen und gibt die Bibliotheks-ID des Dokuments zurück, die stets mit
`doc_` beginnt:
```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/compliance/documents \
-H "Authorization: Bearer $ORBIT_API_KEY" \
-F "type=business_registration" \
-F "country_code=DE" \
-F "file=@/path/to/registration.pdf"
```
| Akzeptiert | Werte |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Dokumenttypen | `id_card`, `passport`, `drivers_license`, `utility_bill`, `bank_statement`, `business_registration`, `vat_certificate`, `lease_agreement`, `proof_of_address`, `power_of_attorney`, `other` |
| Dateiformate | JPEG, PNG, WebP, PDF |
| Maximale Größe | 10 MB |
Dateien werden verschlüsselt, bevor sie die API verlassen, und in einem
privaten Speicher vorgehalten; nichts an einer `doc_…`-ID ist erratbar
oder außerhalb Ihrer Organisation teilbar. Listen Sie die Bibliothek
jederzeit mit `GET /compliance/documents`.
### 2. Referenzierung per `doc_…`-ID
Ein Dokument für sich allein ist inert – es leistet nur dann regulatorische
Arbeit, wenn es mit einer Rolle **an ein Profil angehängt** ist:
```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/compliance/compliance-profiles/cprof_abc123/documents \
-H "Authorization: Bearer $ORBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "document_id": "doc_k7f2m9x1ab", "role": "business_doc" }'
```
Rollen (`id_proof`, `address_proof`, `business_doc`, `authorization`,
`other`) teilen dem Carrier mit, welche Anforderung das Dokument erfüllt.
Dieselbe `doc_…`-ID kann in einem anderen Profil eine andere Rolle
übernehmen.
### 3. Ablauf
Viele Regulierer betrachten Dokumente nach einem festen Alter als veraltet
– das britische Ofcom, die deutsche BNetzA und die französische ARCEP etwa
verlangen in der Regel, dass Identitäts- oder Adressnachweise nicht älter
als 3–12 Monate sind. Orbit hält je angehängtem Dokument ein `expires_at`
fest; sobald ein Dokument abgelaufen ist, zählt es nicht mehr für die
Anforderungen des Landes, auch wenn die Datei selbst weiterhin in Ihrer
Bibliothek liegt.
### 4. Erneuerung
Die Erneuerung ist ein neuer Upload, keine Bearbeitung: Laden Sie das
Ersatzdokument hoch, hängen Sie es in derselben Rolle an das Profil und
trennen Sie dann das abgelaufene (und löschen Sie es optional mit
`DELETE /compliance/documents/:id`). Bereits `approved`-Profile bleiben
genehmigt, während Sie das Dokument austauschen – die Einreichung wird bei
der nächsten Nutzung erneut überprüft.
Das Löschen eines Dokuments wird verweigert, solange es noch an ein
Profil angehängt ist. Trennen Sie es zuerst von jedem Profil und löschen
Sie es danach.
***
## Wo Dokumente wiederverwendet werden
Die `doc_…`-ID ist der einzige Zeiger, den drei Produktoberflächen teilen:
1. **Absender-ID-Registrierung.** Jeder Landeseintrag in der
[Absender-ID-Registrierung](/compliance/sender-id-registration) trägt
`document_refs`: eine Liste von `doc_…`-IDs, die die Einreichung dieses
Landes untermauern. Die Registrierungsroute akzeptiert niemals Dateien –
referenzieren Sie die Bibliotheks-IDs, die Sie bereits hochgeladen
haben; dasselbe Dokument untermauert beliebig viele Länder, die es
akzeptieren.
2. **Regulatory Preview für Nummern.** Der
[Regulatory-Preview](/numbers/regulatory-preview)-Check gibt
`compliance_profile_satisfies: true` nur dann zurück, wenn ein Profil
jedes erforderliche Feld abdeckt **und** seine angehängten Dokumente
nicht abgelaufen sind – ein abgelaufenes Dokument dreht das Flag selbst
bei einem ansonsten vollständigen Profil auf `false`.
3. **Nummernerwerb-Gating.** Der Kauf einer Nummer in einem regulierten
Land ohne ein erfüllendes Profil versetzt die Nummer in
`pending_compliance`: Sie wird belastet, aktiviert aber erst, wenn ein
genehmigtes Profil angehängt ist. Überschreitet die Wartezeit die
Verify-by-Frist des Carriers, kann die Nummer automatisch freigegeben
werden – siehe [Number Lifecycle](/numbers/lifecycle) für Freigabe und
Wiederherstellung.
***
## Ablaufdaten überwachen, bevor sie Sie eine Nummer kosten
Orbit leitet pro Nummer Ablaufwarnungen aus den bereits gespeicherten
Zeitstempeln ab: dem `expires_at` jedes Dokuments und der
Carrier-Verify-by-Frist bei Nummern, die in `pending_compliance` warten.
Lesen Sie sie mit:
```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/numbers/document-expiry-alerts" \
-H "Authorization: Bearer $ORBIT_API_KEY"
```
Jede Warnung nennt die Nummer, den frühesten verbindlichen Ablauf
(`earliest_expiry_at`), ob er von einem Dokument oder der Carrier-Frist
stammt (`earliest_expiry_source`), die ganzen Tage bis zum Ablauf (negativ,
sobald er bereits eingetreten ist) und eine `suggested_action`:
* `renew` – noch gültig, aber innerhalb Ihres Warnfensters; laden Sie den
Ersatz jetzt hoch.
* `renew_or_release` – bereits abgelaufen; erneuern Sie sofort oder
entscheiden Sie, die Nummer gehen zu lassen.
Das Vorschau-Fenster beträgt standardmäßig 30 Tage. Stimmen Sie es pro
Organisation mit der Einstellung `numbers.document_expiry_alert_days`
(1–365 Tage) ab oder sehen Sie ein anderes Fenster ad hoc mit dem
Query-Parameter `?days=` vor. Antwortzeilen sind nach Dringlichkeit
absteigend sortiert; ein sehr großer gefährdeter Bestand wird gekappt und
meldet `truncated: true` – verkleinern Sie in diesem Fall das Fenster.
***
## Mandanteneigen von Design
Die Verantwortungsteilung ist bewusst gewählt:
| Orbit (die Plattform) | Sie (der Mandant) |
| ------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
| Verschlüsselt und speichert jedes Dokument einmal, auf Ihre Organisation begrenzt. | Stellen Sie zuallererst wahrheitsgemäße, aktuelle Dokumente bereit. |
| Trägt das Profil und seine Dokumente zu jedem Carrier und meldet den Prüfstatus je Anbieter. | Wählen Sie, welche Profile ein Dokument untermauert und in welcher Rolle. |
| Meldet Dokumente, die sich dem Ablauf nähern oder ihn überschritten haben, je Nummer. | Hängen Sie Ersatzdokumente hoch und wieder an, bevor ein Dokument abläuft. |
| Vollstreckt die Gates – nicht registrierte Absender und nicht erfüllte Profile aktivieren keine Nummern und bestehen keine Sendeprüfungen. | Halten Sie die strukturierten Felder des Profils aktuell, wenn sich Ihre Geschäftsdaten ändern. |
Orbit erfindet niemals Identitätsdokumente in Ihrem Namen und erneuert
sie nicht automatisch – die Regulierungsbehörde prüft *Ihre* Identität,
also beginnt jede Erneuerung mit einem neuen Upload von Ihnen. Was die
Plattform garantiert, ist, dass ein einmal geliefertes Dokument überall
wiederverwendbar ist, wo es akzeptiert wird, und dass Sie dessen Ablauf mit
genug Vorlauf sehen, um zu handeln.
***
## Weiterführende Referenzen
* [Absender-ID-Registrierung](/compliance/sender-id-registration) –
länderspezifische Registrierung, untermauert durch `document_refs`.
* [Regulatory Preview](/numbers/regulatory-preview) – prüfen Sie vor dem
Kauf, welche Felder und Dokumente ein Land verlangt.
* [Number Lifecycle](/numbers/lifecycle) – was mit einer Nummer geschieht,
die in `pending_compliance` festhängt, sowie Freigabe und
Wiederherstellung.
* [Länderbezogene Compliance-Anforderungen](/compliance/country-requirements)
– welche Absendertypen und Dokumente jedes Land akzeptiert.
* [API-Referenz → Compliance](/api-reference/endpoints/compliance) –
vollständige Anfrage-/Antwort-Schemata.