> ## 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.
# 10DLC-Registrierung für US-A2P-Messaging-Compliance
> Registrieren Sie Ihre Marke und Kampagnen für die US-amerikanische 10-Digit Long Code (10DLC) Messaging-Compliance über Orbit, um A2P-Durchsatz und Zustellbarkeit bei Carrier zu erschließen.
# 10DLC-Registrierung
10DLC (10-Digit Long Code) ist das von den US-Carriern vorgeschriebene System für den Versand von Application-to-Person (A2P) SMS-Nachrichten über normale 10-stellige Rufnummern. Alle Unternehmen, die SMS an US-Nummern versenden, müssen sich über 10DLC registrieren, um Zustellbarkeit und Compliance sicherzustellen.
## Überblick
US-Carrier (T-Mobile, AT\&T, Verizon) verlangen die 10DLC-Registrierung für A2P-Messaging. Nicht registrierter Verkehr erfährt:
* **Aggressive Filterung** — Nachrichten werden still blockiert
* **Höhere Gebühren** — Aufschläge pro Nachricht für nicht registrierte Absender
* **Geringer Durchsatz** — begrenzt auf \~1 Nachricht/Sekunde gegenüber 75+ bei registrierten Absendern
Orbit übernimmt den Registrierungsprozess über The Campaign Registry (TCR).
**Empfohlener Ablauf:** Verwenden Sie den [10DLC-Registrierungs-Wizard](/guides/10dlc-wizard) — er speichert einen fortsetzbaren Entwurf, ermöglicht das Ausfüllen der Marken- und Kampagnenabschnitte in beliebiger Reihenfolge, verifiziert die Rufnummer eines Sole-Proprietor per OTP und reicht beide atomar ein. Die linearen Endpunkte unten bleiben für Skript-Pipelines verfügbar.
***
## Registrierungsschritte
### Schritt 1: Registrieren Sie Ihre Marke
Erstellen Sie eine Markenidentität, die Ihre Organisation repräsentiert.
```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/compliance/10dlc/brand \
-H "X-API-Key: dv_live_sk_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"entity_type": "PRIVATE_PROFIT",
"display_name": "Acme Corp",
"company_name": "Acme Corporation Inc.",
"ein": "12-3456789",
"phone": "+14155551234",
"street": "1 Market St",
"city": "San Francisco",
"state": "CA",
"postal_code": "94105",
"country": "US",
"email": "compliance@acme.com",
"website": "https://acme.com",
"vertical": "TECHNOLOGY"
}'
```
`entity_type` muss einer der folgenden Werte sein: `PRIVATE_PROFIT`, `PUBLIC_PROFIT`, `NON_PROFIT`, `GOVERNMENT` oder `SOLE_PROPRIETOR`. `display_name`, `company_name`, `phone`, `street`, `city`, `state`, `postal_code` und `email` sind erforderlich; `ein` und `website` sind optional.
**Antwort (`201 Created`):**
```json theme={null}
{
"data": {
"brandId": "BXXXXXX",
"status": "PENDING"
},
"meta": {
"request_id": "req_abc123",
"timestamp": "2026-03-08T12:00:00Z"
}
}
```
Die Markenprüfung (Vetting) dauert in der Regel 24–48 Stunden.
### Schritt 2: Erstellen Sie eine Kampagne
Registrieren Sie den konkreten Anwendungsfall Ihres Messagings.
Bevor Sie einreichen — prüfen Sie Ihre Marken- und Kampagnen-Payload mit dem [Preflight-Linter](#preflight-prüfung-ihrer-einreichung). Er erkennt die deterministischen TCR-Ablehnungen (fehlende Opt-out-Formulierung, Shortener-Links, Use-Case-Echo), solange die Korrektur noch kostenlos ist. Jede abgelehnte Einreichung kostet eine neue Vetting-Gebühr und startet die Prüfungsfrist von 1–5 Werktagen neu.
```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/compliance/10dlc/campaign \
-H "X-API-Key: dv_live_sk_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"brand_id": "BXXXXXX",
"usecase": "CUSTOMER_CARE",
"description": "Sending order updates and support responses to customers who opted in on our website checkout form.",
"sample_message": [
"Your order #12345 has shipped! Track at https://acme.com/track/12345",
"Hi! Your support ticket #567 has been resolved. Reply STOP to unsubscribe."
],
"message_flow": "Customers opt in via a web form at checkout and confirm consent. They can reply STOP at any time to opt out.",
"help_message": "Reply HELP for assistance or contact support@acme.com.",
"optout_message": "You have been unsubscribed and will receive no further messages."
}'
```
`description` muss mindestens 40 Zeichen lang sein, `message_flow` mindestens 40, und sowohl `help_message` als auch `optout_message` mindestens 20. `sample_message` ist ein Array von 1–10 repräsentativen Nachrichten. Kampagnen im politischen Bereich (`usecase` von `POLITICAL_ADVOCACY` oder `POLLING_AND_VOTING`, oder `is_political: true`) erfordern zusätzlich einen Campaign-Verify-`cv_token`.
**Antwort (`201 Created`):**
```json theme={null}
{
"data": {
"campaignId": "CXXXXXX",
"status": "PENDING"
},
"meta": {
"request_id": "req_def456",
"timestamp": "2026-03-08T12:05:00Z"
}
}
```
### Schritt 3: Genehmigung abwarten
Die Kampagnenprüfung dauert 1–5 Werktage. Sie können den Status abfragen:
```bash theme={null}
curl https://api.orbit.devotel.io/api/v1/compliance/10dlc/campaigns/CXXXXXX/status \
-H "X-API-Key: dv_live_sk_your_key_here"
```
**Antwort:**
```json theme={null}
{
"data": {
"campaignId": "CXXXXXX",
"status": "APPROVED",
"brandId": "BXXXXXX",
"mnoStatuses": {
"10017": "APPROVED",
"10035": "APPROVED",
"10095": "REVIEW"
},
"provider": "telnyx"
},
"meta": {
"request_id": "req_ghi789",
"timestamp": "2026-03-09T09:00:00Z"
}
}
```
Der Top-Level-`status` ist die CSP-Ebene-Entscheidung. `mnoStatuses` ist die genehmigende Zuordnung pro Carrier (Schlüssel sind MNO-Carrier-IDs — z. B. `10017` T-Mobile, `10035` AT\&T, `10095` Verizon); eine Kampagne kann auf CSP-Ebene `APPROVED` sein, während sie bei einem einzelnen Carrier noch in `REVIEW` ist.
**Statuswerte:**
| Status | Beschreibung |
| ---------- | ----------------------------------------------- |
| `PENDING` | Eingereicht, wartet auf Carrier-Prüfung |
| `APPROVED` | Genehmigt — Sie können versenden |
| `FAILED` | Abgelehnt — siehe `rejectionReason` für Details |
### Schritt 4: Mit dem Versand beginnen
Nach der Genehmigung erhalten Nachrichten von registrierten Nummern vollen 10DLC-Durchsatz und Zustellbarkeit.
Wenn eine Einreichung mit `FAILED` zurückkommt, ein Vetting-Score Ihre Stufe deckelt oder Sie den Headroom benötigen, den eine genehmigte Kampagne tatsächlich hat — der Leitfaden [10DLC-Ablehnungen und Re-Vet](/guides/10dlc-rejections-and-revet) behandelt Decoder-, Re-Vet- und Durchsatz-Endpunkte.
***
## Preflight-Prüfung Ihrer Einreichung
Die meisten TCR-Ablehnungen sind deterministisch — dieselben wenigen Muster zu Inhalten und Vollständigkeit stolpern Ersteinreichungen immer wieder. Jede Ablehnung verbrennt eine neue Vetting-Gebühr (4–15 USD pro Neuesreichung) und startet die Prüfungsfrist von 1–5 Werktagen neu. Orbit liefert einen Preflight-Linter, der Ihre Marken- und Kampagnen-Payload gegen den Katalog bekannter Ablehnungsmuster bewertet, **bevor** Sie einreichen — und liefert feldspezifische Befunde, jeweils mit Schweregrad, dem exakten beanstandeten Textfragment und einem konkreten Umschreibungsvorschlag.
`POST /api/v1/compliance/10dlc/preflight`
Der Linter ist eine reine Regel-Engine: Es wird nichts an TCR gesendet, nichts gespeichert und kein Antrag erstellt. Jede Rolle in der Organisation kann ihn aufrufen — kein `numbers:write`-Scope erforderlich.
Senden Sie die Marken- und Kampagnenobjekte exakt so, wie Sie sie einreichen möchten, plus optional ein `brand_vetting_score` (0–100), wenn Sie bereits einen haben:
```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/compliance/10dlc/preflight \
-H "X-API-Key: dv_live_sk_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"brand": {
"display_name": "Acme Corp",
"entity_type": "PRIVATE_PROFIT",
"ein": "12-3456789",
"email": "compliance@acme.com",
"website": "https://acme.com"
},
"campaign": {
"usecase": "MARKETING",
"description": "Acme sends weekend promotional offers to customers who opt in on our checkout page.",
"sample_message": [
"Acme: 20% off today. Shop at https://bit.ly/acme-sale"
],
"message_flow": "Customers opt in at checkout. They can reply STOP at any time to opt out.",
"help_message": "Reply HELP for assistance or email support@acme.com.",
"optout_message": "You are unsubscribed. Reply STOP to opt out.",
"expected_msg_per_day_per_number": 5000
},
"brand_vetting_score": 45
}'
```
**Antwort (`200 OK`):**
```json theme={null}
{
"data": {
"score": 61,
"verdict": "block",
"findings": [
{
"ruleId": "R-CAMP-SAMPLE-SHORTENER",
"severity": "error",
"field": "campaign.sample_message[0]",
"message": "Public URL shortener detected. Carriers auto-reject shortener domains in sample messages.",
"match": "bit.ly",
"suggestion": "Replace the shortener with a link on your own domain (e.g. acme.com/sale)."
},
{
"ruleId": "R-CAMP-SAMPLES-COUNT",
"severity": "warn",
"field": "campaign.sample_message",
"message": "Only one sample message provided. TCR vets 2-10 distinct samples covering your real traffic.",
"suggestion": "Add distinct samples (welcome, reminder, confirmation) so TCR sees the full campaign."
},
{
"ruleId": "R-CAMP-SAMPLE-CTA-STOP",
"severity": "warn",
"field": "campaign.sample_message[0]",
"message": "Sample message does not reference STOP. Carriers expect opt-out wording in at least one sample.",
"match": "Acme: 20% off today.",
"suggestion": "Append \"Reply STOP to unsubscribe.\" to the sample."
},
{
"ruleId": "R-CAMP-THROUGHPUT-TIER",
"severity": "warn",
"field": "campaign.expected_msg_per_day_per_number",
"message": "Declared throughput exceeds the daily cap your vetting tier qualifies for.",
"suggestion": "Lower the declared volume or raise your vetting score to qualify for a higher tier."
}
],
"engine": "tcr-preflight/v1"
},
"meta": {
"request_id": "req_pf001",
"timestamp": "2026-08-28T09:00:00Z"
}
}
```
**Antwortform.** `score` liegt zwischen `0`–`100` (`100` = keine bekannten Muster gefunden; jeder Befund reduziert je nach Schweregrad). `verdict` ist das Gesamturteil — `block` bei Vorhandensein eines `error`-Befunds, `warn` unter einem Score von 75, sonst `pass`. Jeder `findings[]`-Eintrag trägt eine stabile `ruleId`, einen `severity` (`error` | `warn` | `info`), den Dot-Pfad-`field`, auf den er sich bezieht, eine menschenlesbare Zusammenfassung, ein optionales `match` mit dem exakten beanstandeten Text (für Hervorhebung in Ihrer UI) und einen `suggestion` — eine Umschreibung, die den Befund auflöst. `engine` ist die Regel-Engine-Version (`tcr-preflight/v1`), sodass Sie Scores über die Zeit korrelieren können.
Ein `pass`-Urteil bedeutet „keine bekannten Ablehnungsmuster gefunden" — nicht „TCR wird zustimmen". Der Linter erfasst die deterministische Mehrheit der Ablehnungen; Ihre Einreichung durchläuft weiterhin die normale Carrier-Prüfung. Er ist Berater, niemals ein Gate: Sie entscheiden, wann Sie einreichen.
### Was der 10DLC-Linter prüft
Der Katalog kodiert die Muster, die TCR und Carrier ablehnen. Zentrale Regeln:
| Regel-ID | Schweregrad | Was er erfasst |
| ----------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `R-BRAND-EIN` | error | EIN-Format entspricht keinem gültigen US-Steuer-ID-Schema |
| `R-BRAND-EMAIL-DOMAIN` | warn | E-Mail auf einer Freemail-Domain, die Carrier abwerten (gmail.com usw.) |
| `R-BRAND-WEBSITE` | warn | Website fehlt oder ist keine öffentliche, markenbezogene URL |
| `R-CAMP-DESC-LEN` / `R-CAMP-DESC-GENERIC` | error | Beschreibung zu kurz oder gibt nur den Use-Case-Namen wörtlich wieder |
| `R-CAMP-SAMPLES-COUNT` | warn | Zu wenige Beispielnachrichten — der Linter markiert zudem Platzhaltertext wie `Hi {{firstName}}` (`R-CAMP-SAMPLE-PLACEHOLDER`) |
| `R-CAMP-SAMPLE-SHAFT` | error | SHAFT-C-Inhalte in Samples (sex, hate, alcohol, firearms, tobacco, cannabis) — Automatische-Ablehnungs-Kategorien |
| `R-CAMP-SAMPLE-BLOCKLIST` | error | Carrier-Inhalts-Blocklist-Phrasen (MEF / UCC §3.4) — gemeinsamer Katalog mit dem Short-Code-Linter |
| `R-CAMP-SAMPLE-SHORTENER` | error | Öffentliche URL-Shortener (bit.ly, t.co, tinyurl.com …) — Carrier lehnen automatisch ab |
| `R-CAMP-SAMPLE-CLICK-HERE` | warn | Vages „click here" ohne Zielname |
| `R-CAMP-SAMPLE-CTA-STOP` | warn | Kein Sample erwähnt die STOP-Opt-out |
| `R-CAMP-HELP` / `R-CAMP-OPTOUT` | error | `help_message` / `optout_message` ohne den kanonischen Schlüsselwortsatz |
| `R-CAMP-FLOW` | error | `message_flow` fehlt oder ist generisch (der Opt-in-Flow, den TCR am härtesten prüft) |
| `R-CAMP-AI-USECASE` | warn | KI-gesteuerte Kampagne, deren Beschreibung die KI-Use-Case-Offenlegung auslässt |
| `R-CAMP-THROUGHPUT-TIER` | warn | Deklariertes Tagesvolumen übersteigt die Obergrenze, für die Ihr `brand_vetting_score` qualifiziert |
Beheben Sie jeden Befund in Schweregrad-Reihenfolge, wiederholen Sie den Linter bis zur sauberen Antwort (`verdict: "pass"`), und reichen Sie dann dieselbe Payload über [Schritt 2](#schritt-2-erstellen-sie-eine-kampagne) ein.
***
## Anwendungsfall-Typen
Geben Sie einen dieser Werte im `usecase`-Feld beim Erstellen einer Kampagne (Schritt 2) weiter. TCR-Codes sind **GROSSGESCHRIEBEN** — senden Sie sie exakt wie abgebildet; ein Kleinbuchstabe wird bei der Registrierung abgelehnt.
| Anwendungsfall | Beschreibung | Durchsatz |
| ----------------------------- | ------------------------------------------------------------------------------------------ | ---------------------------- |
| `CUSTOMER_CARE` | Kundensupport, Service-Antworten und Warnungen | Durch Vetting-Score bestimmt |
| `MARKETING` | Werbeaktionen, Angebote und Vertriebsansprache | Durch Vetting-Score bestimmt |
| `ACCOUNT_NOTIFICATION` | Kontoänderungen, Abrechnung und Sicherheitshinweise | Durch Vetting-Score bestimmt |
| `DELIVERY_NOTIFICATION` | Bestell-, Versand- und Zustell-Updates | Durch Vetting-Score bestimmt |
| `TWO_FACTOR_AUTH` | Einmalpasswörter und 2FA-Challenges | Durch Vetting-Score bestimmt |
| `POLLING_AND_VOTING` | Umfragen und Abstimmungen (politische Kampagnen benötigen zudem ein Campaign-Verify-Token) | Durch Vetting-Score bestimmt |
| `PUBLIC_SERVICE_ANNOUNCEMENT` | Öffentlich interessierende Ankündigungen | Durch Vetting-Score bestimmt |
| `CHARITY` | Messaging registrierter 501(c)(3)-Nonprofits | Reduziert (501(c)(3)-Lane) |
| `EMERGENCY` | Sicherheits- und öffentliche Warnmeldungen | Carrier-Priorität |
| `MIXED` | Mehrere Anwendungsfälle in einer Kampagne (der Standard) | Reduzierte Tagesobergrenze |
***
## Durchsatzstufen
Der 10DLC-Durchsatz wird als **pro Tag, pro Nummer** Message-Segment-Obergrenze gewährt, nicht als Rate pro Sekunde. Ihre Stufe wird durch Ihren Marken-Vetting-Score (0–100) und Ihren registrierten Entity-Typ bestimmt. Die Tagesobergrenze jeder Stufe gilt für jede Nummer, die der Kampagne zugewiesen ist, sodass der Gesamtkampagnendurchsatz mit der Anzahl zugewiesener Nummern skaliert.
| Stufe | Berechtigung | Tagesobergrenze pro Nummer |
| ------------------- | ---------------------------------------- | -------------------------- |
| Sole Proprietor | Entity-Typ `SOLE_PROPRIETOR` | \~1.000 Nachr./Tag |
| Low Volume Standard | Basislinie (jede Marke, auch ohne Score) | \~30.000 Nachr./Tag |
| Standard | Vetting-Score 50 oder höher | \~200.000 Nachr./Tag |
| Top Tier | Vetting-Score 75 oder höher | \~2.000.000 Nachr./Tag |
Die Obergrenzen spiegeln T-Mobile-Defaults; AT\&T und Verizon liegen innerhalb von etwa 10 %. Sie erhalten die höchste Stufe, für die Ihr Vetting-Score qualifiziert. Eine Marke ohne Score fällt auf die Low-Volume-Standard-Basislinie zurück.
Verbessern Sie Ihren Vetting-Score durch vollständige, korrekte Markeninformationen einschließlich EIN, Website und Börsensymbol (falls öffentlich). Ein Score von 75 oder höher erschließt die Top-Tier-Tagesobergrenze.
***
## Compliance-Anforderungen
1. **Opt-in-Einwilligung.** Sie benötigen die ausdrückliche Einwilligung jedes Empfängers vor dem Versand.
2. **Opt-out-Behandlung.** STOP-Anfragen sofort beachten. Orbit verarbeitet automatisch STOP, CANCEL und UNSUBSCRIBE.
3. **Nachrichteninhalt.** Beispielnachrichten müssen repräsentativ für den tatsächlichen Verkehr sein.
4. **Konsistente Verwendung.** Senden Sie nur Nachrichten, die dem registrierten Anwendungsfall Ihrer Kampagne entsprechen.
***
## Dashboard-Registrierung
Sie können die gesamte 10DLC-Registrierung auch über das Orbit-Dashboard abschließen:
1. Navigieren Sie zu **Einstellungen > Compliance > 10DLC**
2. Klicken Sie **Marke registrieren** und füllen Sie Ihre Firmendaten aus
3. Sobald die Marke genehmigt ist, klicken Sie **Kampagne erstellen**
4. Wählen Sie Ihren Anwendungsfall, fügen Sie Beispielnachrichten hinzu und weisen Sie Nummern zu
5. Reichen Sie zur Carrier-Prüfung ein
***
## Konfiguration des Country-Rule-Feeds
Dieser Abschnitt richtet sich an **Plattformbetreiber / Self-Hosted-Deployments**. SaaS-Kunden auf `api.orbit.devotel.io` müssen diese nicht setzen — Orbit hält die 10DLC-Länderregeln für Sie aktuell.
Orbit hält seinen kanonischen US-10DLC-Länderregelsatz (Absendertypen, Durchsatzhaltung, Registrierungsanforderung) aktuell, indem es aus dem **iconectiv TCR Partner-Feed** bezieht. Der Connector liegt in `@devotel/compliance/country-rule-feeds` und läuft an zwei Stellen:
* **On-Demand** — die Admin-Aktion „Von Upstream aktualisieren"
(`POST /api/v1/compliance/country-rules/sync?provider=iconectiv`).
* **Wöchentlich** — der Auto-Refresh-Tick im Compliance-Sync-Scheduler des Webhook-Workers.
Der Connector ist **optional und fail-open**: Bei fehlenden Zugangsdaten protokolliert er einen Fehler und überspringt, wobei vorhandene Länderregeln bestehen bleiben. Es ist ein reiner Metadaten-Feed — niemals ein Nachrichtentransportpfad, ausgehende SMS verlassen weiterhin das Devotel Softswitch.
| Variable | Erforderlich | Beschreibung |
| ------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DEVOTEL_TCR_API_KEY` | für den Feed | iconectiv TCR Partner-API-Schlüssel. Der Connector überspringt, wenn nicht gesetzt. |
| `DEVOTEL_TCR_PARTNER_ID` | für den Feed | iconectiv TCR Partner-ID (Pfadsegment auf der Partner-API). Der Connector überspringt, wenn nicht gesetzt. |
| `DEVOTEL_TCR_FEED_URL` | optional | Basis-URL-Override für die Partner-API. Standard ist `https://csp-api.campaignregistry.com`. |
| `DEVOTEL_TCR_OPTOUT_URL` | optional | Vollständige URL des TCR Universal Opt-Out Registry-Endpunkts, der den DNC-Opt-out-Pull steuert, überschreiben. Standard ist `/v1/partner//universalOptOuts`. Nur lesend — niemals ein Versandpfad. |
Sowohl `DEVOTEL_TCR_API_KEY` als auch `DEVOTEL_TCR_PARTNER_ID` müssen gesetzt sein, damit der Feed läuft; fehlt einer, tut der Connector nichts. Registrieren Sie Devotel als TCR-Partner bei [iconectiv.com](https://iconectiv.com/), um diese Zugangsdaten zu erhalten.
***
## Fehlerbehebung
| Problem | Lösung |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Marke abgelehnt | Stellen Sie sicher, dass Ihre EIN exakt mit IRS-Aufzeichnungen übereinstimmt |
| Kampagne abgelehnt | Stellen Sie sicher, dass Beispielnachrichten zum gewählten Anwendungsfall passen und Opt-out-Sprache enthalten |
| Niedriger Vetting-Score | Liefern Sie vollständige Markeninformationen (Website, Börsensymbol, voller rechtlicher Name) |
| Nachrichten werden weiterhin gefiltert | Bestätigen Sie, dass der Kampagnenstatus `approved` ist und Nummern zugewiesen sind |
Das Versenden hochvolumiger SMS ohne 10DLC-Registrierung kann zu Carrier-Filterung, Nachrichtenblockierung und möglicher Nummernsperrung führen.