Einwilligungsmanagement und Nachweise

Bevor Sie einem Kontakt auf einem regulierten Kanal eine Nachricht senden, benötigen Sie in der Regel eine Rechtsgrundlage — meist eine Einwilligung. Die Einwilligungs-API von Orbit ist das führende System dafür, wer auf welchem Kanal wann und auf welcher Rechtsgrundlage ein- oder ausgestiegen ist. Jeder Schreibvorgang wird auf die Speicher verteilt, gegen die Ihre Sendevorgänge geprüft werden — das Erfassen einer Einwilligung hier gibt also die Nachricht tatsächlich frei (oder blockiert sie). Sie können zudem den gesamten Verlauf exportieren als auditfähige CSV- oder JSON-Datei. Alle folgenden Endpunkte sind unter https://api.orbit.devotel.io/api/v1/compliance beheimatet.

Das Erfassen einer Einwilligung in Orbit schafft einen auditfähigen Verlauf, macht einen Versand jedoch nicht allein dadurch rechtmäßig. Sie bleiben für das Einholen einer wirksamen Einwilligung und für die von Ihnen versendeten Inhalte verantwortlich. Diese Seite ist keine Rechtsberatung.

Kanäle und Zustände

Die Einwilligung wird pro Kanal erfasst. Das unterstützte Kanalset umfasst: email, fax, instagram, line, messenger, push, rcs, sms, viber, voice, whatsapp. Ein Paar (contact, channel) nimmt einen von drei Zuständen an:

Zustand	Bedeutung
`opted_in`	Einwilligung erteilt und nicht widerrufen.
`opted_out`	Einwilligung widerrufen oder ein expliziter Opt-out erfasst.
`unknown`	Für das Paar liegt kein Einwilligungsdatensatz vor — Ihr Sende-Gate entscheidet über den Standard.

Einwilligungen erfassen

POST /compliance/consent erfasst einen Opt-in oder Opt-out über einen oder mehrere Kanäle in einem einzigen Aufruf. Identifizieren Sie den Kontakt über contact_id oder über identifier (eine E-Mail, eine E.164-Telefonnummer oder eine WhatsApp-ID — Orbit erkennt den Typ automatisch).

curl -X POST https://api.orbit.devotel.io/api/v1/compliance/consent \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "jordan@example.com",
    "channels": ["email", "sms"],
    "opt_in": true,
    "source": "web_form",
    "consent_type": "marketing",
    "lawful_basis": "consent",
    "purpose": "Weekly product newsletter and order updates",
    "consent_text_version": "tos-2026-04",
    "consent_proof_url": "https://example.com/proofs/abc123.png"
  }'

Rückgabe 201 Created:

{
  "contact_id": "cnt_9f…",
  "consent_record_ids": ["cr_a1…", "cr_b2…"],
  "channels": ["email", "sms"],
  "state": "opted_in",
  "valid_until": null
}

Feld	Typ	Hinweise
`contact_id` / `identifier`	string	Geben Sie eines der beiden an.
`channels`	string[]	Einer oder mehrere aus dem Kanalset; dedupliziert und sortiert.
`opt_in`	boolean	Erforderlich. `true` = Opt-in, `false` = Opt-out.
`source`	string	Wie die Einwilligung erfasst wurde (z. B. `web_form`, `import`, `double_opt_in`). Standard `consent_api`.
`consent_type`	string	Zweckkategorie, z. B. `marketing`, `transactional`. Standard `messaging`.
`lawful_basis`	enum	Rechtsgrundlage nach Art. 6 DSGVO: `consent`, `contract`, `legal_obligation`, `vital_interests`, `public_task`, `legitimate_interests`.
`purpose`	string	Freitext zur Beschreibung der Verwendung (≤ 500).
`consent_text_version`	string	Version des Hinweistextes, dem die betroffene Person zugestimmt hat.
`consent_proof_url`	string (url)	Link zu einem Screenshot oder signierten Dokument.
`valid_until`	string (ISO-8601 UTC)	Absoluter Zeitpunkt, zu dem die Einwilligung abläuft. Nur bei Opt-in — wird bei Opt-out ignoriert. Schließt `expires_in_days` aus.
`expires_in_days`	integer	Relatives Gültigkeitsfenster (1–3650 Tage ab jetzt). Nur bei Opt-in. Schließt `valid_until` aus.
`metadata`	object	Beliebige benutzerdefinierte Schlüssel/Werte.

Die Angabe beider Werte valid_until und expires_in_days ist mehrdeutig und wird mit 422 VALIDATION_ERROR abgelehnt. Wenn Sie ein Zeitfenster setzen, gibt die 201-Antwort das aufgelöste valid_until (den absoluten Ablaufzeitpunkt) zurück; bei einer nicht ablaufenden Einwilligung oder einem Opt-out ist es null. Das erneute Erfassen eines Opt-ins mit einem neuen Zeitfenster verlängert die Gültigkeit — der ursprüngliche granted_at-Wert bleibt erhalten, der Ablaufzeitpunkt wird jedoch aktualisiert. Was ein Schreibvorgang bewirkt. Jeder erfasste Kanal aktualisiert vier synchronisierte Speicher: die Audit-Tabelle consent_records, den Spiegel channel_preferences des Kontakts (den schnellen Lese-Pfad, den Ihre Sendevorgänge prüfen), die suppression_list (bei Opt-out) sowie einen kurzlebigen Redis-STOP-Blocker, damit laufende Kampagnen-Batches die Änderung innerhalb von ca. 10 Minuten berücksichtigen.

Schreibvorgänge sind teilsicher: Schlägt ein Kanal fehl, gelten die anderen weiterhin. Vergleichen Sie consent_record_ids.length mit der Anzahl der angeforderten Kanäle, um einen Teilschreibvorgang zu erkennen. Das erneute Erfassen eines Opt-ins für einen bereits aktiven Kanal aktualisiert die Metadaten/den Nachweis, behält aber den ursprünglichen granted_at bei.

Einwilligungen abrufen

GET /compliance/consent/lookup gibt den aktuellen Zustand für ein (contact, channel)-Paar zurück — verwenden Sie ihn als Prüfung vor dem Versand.

curl "https://api.orbit.devotel.io/api/v1/compliance/consent/lookup?identifier=jordan@example.com&channel=sms" \
  -H "Authorization: Bearer $ORBIT_API_KEY"

{
  "contact_id": "cnt_9f…",
  "channel": "sms",
  "state": "opted_in",
  "source": "web_form",
  "granted_at": "2026-04-02T10:11:00.000Z",
  "revoked_at": null,
  "lawful_basis": "consent",
  "purpose": "Weekly product newsletter and order updates",
  "consent_text_version": "tos-2026-04",
  "consent_proof_url": "https://example.com/proofs/abc123.png",
  "valid_until": null,
  "expired": false,
  "requires_reconfirmation": false
}

Ein state von unknown bedeutet, dass für das Paar kein Datensatz existiert — Ihre Anwendung entscheidet, ob dies eine Einwilligung impliziert (einige Transaktionsabläufe) oder den Versand blockiert (die meisten Marketingabläufe). Die letzten drei Felder melden zeitlich begrenzte Einwilligungen und sind immer vorhanden:

Feld	Typ	Hinweise
`valid_until`	string \| null	Der Ablaufzeitpunkt der Einwilligung oder `null`, wenn die Einwilligung nie abläuft (oder das Paar abgemeldet ist).
`expired`	boolean	`true`, wenn die Einwilligung aktiv ist, ihr `valid_until` jedoch in der Vergangenheit liegt. Behandeln Sie eine abgelaufene Einwilligung an Ihrem Sende-Gate als nicht mehr eingewilligt.
`requires_reconfirmation`	boolean	Spiegelt `expired` — ein Hinweis, einen Re-Permission-Prozess auszulösen. Setzen Sie den Wert zurück, indem Sie einen neuen Opt-in erfassen (optional mit einem neuen Zeitfenster).

Ablaufende Einwilligungen finden

GET /compliance/consent/expiring durchsucht den Mandanten nach Opt-ins, deren Gültigkeitsfenster abgelaufen ist oder bald abläuft — die Grundlage für eine Re-Permission-Kampagne (erneute Bestätigung). Es werden nur Einwilligungen mit einem valid_until zurückgegeben; nicht ablaufende Einwilligungen erscheinen nie.

curl "https://api.orbit.devotel.io/api/v1/compliance/consent/expiring?within_days=30&status=all" \
  -H "Authorization: Bearer $ORBIT_API_KEY"

Abfrageparameter:

Parameter	Typ	Hinweise
`within_days`	integer	Vorausschau-Horizont (0–3650, Standard 30). Gibt Einwilligungen zurück, deren `valid_until` bei oder vor jetzt + `within_days` liegt; bereits abgelaufene Einwilligungen sind immer enthalten.
`channel`	enum	Optional — auf einen einzelnen Kanal einschränken.
`status`	enum	`all` (Standard), `expired` (bereits nach `valid_until`) oder `expiring` (noch gültig, aber innerhalb des Horizonts).
`limit`	integer	Seitengröße (1–100, Standard 50).
`cursor`	string	Opaker Paginierungs-Cursor — unverändert zurücksenden.

{
  "within_days": 30,
  "channel": null,
  "status": "all",
  "as_of": "2026-05-01T09:00:00.000Z",
  "items": [
    {
      "id": "cr_b2…",
      "contact_id": "cnt_9f…",
      "channel": "sms",
      "consent_type": "marketing",
      "source": "web_form",
      "lawful_basis": "consent",
      "granted_at": "2025-05-02T10:11:00.000Z",
      "valid_until": "2026-04-20T00:00:00.000Z",
      "expired": true,
      "status": "expired",
      "requires_reconfirmation": true
    }
  ],
  "next_cursor": null
}

Die Einträge sind so sortiert, dass die am frühesten ablaufenden zuerst kommen. Jeder trägt einen status (expired oder expiring), sodass Sie zwischen „jetzt erneut bestätigen” und „vor Ablauf des Fensters warnen” unterscheiden können. Die erneute Bestätigung ist ein gewöhnlicher Opt-in per POST /compliance/consent — optional mit einem neuen valid_until oder expires_in_days.

Behandeln Sie next_cursor als opak und senden Sie ihn unverändert zurück; ein null-Wert bedeutet die letzte Seite. Ein ungültiger oder veralteter Cursor wird als neue erste Seite behandelt und löst keinen Fehler aus.

Bestätigte Einwilligungen (Double-Opt-in-Handshakes)

Ein einfaches POST /compliance/consent dokumentiert die Einwilligung — es ist das führende System, sobald Ihre eigene Oberfläche die Einwilligung eingeholt hat. Wenn die Beweisstufe eine erfasste Antwort des Empfängers erfordert (ausdrückliche schriftliche Einwilligung nach TCPA, bestätigter Opt-in in der EU, 10DLC-Kampagnenprüfung), verwenden Sie stattdessen den verwalteten Double-Opt-in-Handshake:

POST /compliance/consent/double-opt-in — Start: erfasst eine Zeile im Status pending (noch keine Einwilligung) und gibt den Bestätigungstext für das Paar zurück.
Der Empfänger antwortet; leiten Sie den Text an POST /compliance/consent/double-opt-in/confirm weiter — Bestätigung: Ein zustimmendes Schlüsselwort zur ausstehenden Aufforderung wandelt das Paar in eine bestätigte opted_in- Einwilligung um.
GET /compliance/consent/double-opt-in/status — Lesen: der aktuelle Zustand (opted_in | opted_out | pending | none) sowie die Flags confirmed / awaiting_reply, ohne Nebenwirkungen.

Bestätigte Handshakes landen im selben Einwilligungsregister, das diese Seite dokumentiert — /lookup, /history und der Export lesen sie identisch. Bis zur Bestätigung ist ein ausstehender Handshake keine Einwilligung. Mandanteneigen: Nichts startet einen Handshake im Namen der Plattform. Die vollständigen Mechanismen finden Sie unter Bestätigte Einwilligungen (Double-Opt-in-Handshakes).

Einwilligungsverlauf

GET /compliance/consent/history gibt den vollständigen, paginierten Prüfpfad für einen Kontakt zurück — jede Erteilung und jeder Widerruf, die neuesten zuerst. Abfrageparameter: contact_id oder identifier (eines erforderlich), ein optionaler channel-Filter, limit (≤ 100, Standard 50) und ein opaker cursor.

{
  "contact_id": "cnt_9f…",
  "channel": null,
  "items": [
    {
      "id": "cr_b2…",
      "channel": "sms",
      "consent_state": "opted_in",
      "granted": true,
      "source": "web_form",
      "granted_at": "2026-04-02T10:11:00.000Z",
      "revoked_at": null,
      "lawful_basis": "consent",
      "created_at": "2026-04-02T10:11:00.000Z"
    }
  ],
  "next_cursor": "eyJ0…"
}

Behandeln Sie next_cursor als opak — senden Sie ihn unverändert zurück, um die nächste Seite abzurufen. Ein ungültiger oder veralteter Cursor wird als neue erste Seite behandelt und löst keinen Fehler aus.

Den Einwilligungsnachweis exportieren

GET /compliance/consent/export lädt den mandantenweiten Einwilligungsverlauf als einzelne Datei herunter — die Antwort auf ein TCPA-Audit, die Beweislast nach Art. 7 Abs. 1 DSGVO oder eine Offenlegungsanfrage („zeigen Sie, wer wann auf welchem Kanal und aus welcher Quelle ein- oder ausgestiegen ist”). Er ist das Massen-Gegenstück zu /lookup und /history.

curl "https://api.orbit.devotel.io/api/v1/compliance/consent/export?format=csv&state=opted_out" \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -o consent-proof-of-record.csv

Abfrageparameter:

Parameter	Typ	Hinweise
`format`	enum	`csv` (Standard — RFC-4180, kann in einer Tabellenkalkulation geöffnet werden) oder `json`.
`channel`	enum	Auf einen Kanal einschränken.
`state`	enum	`all` (Standard), `opted_in`, `opted_out` oder `unknown`.
`contact_id`	string	Schränkt den Export auf einen einzelnen Kontakt ein — die Form einer Offenlegungsanfrage.
`from` / `to`	string	Datumsbereich über `created_at` des Datensatzes. Akzeptiert ein reines Datum im Format `YYYY-MM-DD` oder einen RFC-3339-Zeitstempel.
`limit`	integer	Anzahl der Zeilen (1–50.000, Standard 50.000).

Jede Zeile enthält ein Einwilligungsereignis, verknüpft mit den Identifikatoren des Kontakts — record_id, contact_id, email, phone, whatsapp_id, channel, consent_state, granted, consent_type, source — sowie die Spalten zur Beweislast nach DSGVO lawful_basis, purpose, policy_template, consent_text_version, consent_proof_url, ip_address, valid_until und die Zeitstempel für Erteilung/Widerruf/Aktualisierung. CSV-Downloads erhalten einen datierten Dateinamen (consent-proof-of-record-YYYY-MM-DD.csv) und werden nie über einen Lesecache ausgeliefert (Cache-Control: no-store). Bei format=json liefert die Antwort stattdessen eine Hülle mit columns / items / count — dieselben Daten für programmatische Verbraucher. Der Zugriff ist auf Owner- und Admin-Schlüssel beschränkt — die Nutzdaten legen mandantenweit rohe Empfänger-Identifikatoren offen, dieselbe Vertrauensstufe wie beim Suppression-Import. Jeder Exportlauf wird selbst mit seinen Filtern und der Zeilenzahl in das Audit-Log geschrieben.

Überschreitet Ihr Register 50.000 Zeilen, wird der Export an der Obergrenze abgeschnitten: CSV-Antworten tragen den Header X-Export-Truncated: true, und die JSON-Hülle setzt truncated: true. Grenzen Sie nach Kanal oder Status ein oder paginieren Sie, indem Sie aufeinanderfolgende Datumsfenster mit from/to exportieren.

Indiens Digital Personal Data Protection Act (DPDP) führt das Konzept eines Consent Managers ein — eines rechenschaftspflichtigen, registrierten Vermittlers, der im Namen einer betroffenen Person kryptografisch signierte Einwilligungsnachweise ausstellt. Orbit kann die Manager registrieren, die Ihre Nutzer verwenden, und die von ihnen ausgestellten Nachweise prüfen. POST /compliance/consent/managers (Admin/Owner) registriert einen Manager und speichert dessen öffentlichen Schlüssel (einen ECDSA-P-256-SPKI-PEM), mit dem jeder von ihm signierte Nachweis geprüft wird.

curl -X POST https://api.orbit.devotel.io/api/v1/compliance/consent/managers \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Consent Manager",
    "manager_id": "acme-cm-001",
    "manager_url": "https://cm.acme.example",
    "public_key": "-----BEGIN PUBLIC KEY-----\n…\n-----END PUBLIC KEY-----",
    "country_code": "IN"
  }'

GET /compliance/consent/managers listet registrierte Manager (aktive zuerst).
PUT /compliance/consent/managers/{id} aktualisiert oder deaktiviert einen (Teilaktualisierung; alle Felder optional).

Einen signierten Nachweis speichern

POST /compliance/consent/receipts prüft einen von einem Manager signierten Nachweis und speichert ihn als Einwilligung. Die Signatur (ECDSA P-256 / SHA-256, IEEE-P1363, base64url) wird anhand des öffentlichen Schlüssels des registrierten Managers über eine an JCS angelehnte JSON-Kanonisierung der Nutzdaten mit sortierten Schlüsseln geprüft, bevor etwas gespeichert wird. Diese Kanonisierung sortiert Objektschlüssel aufsteigend nach UTF-16-Codeeinheit und entfernt unwesentlichen Leerraum, ist jedoch keine vollständige RFC-8785-Implementierung — insbesondere wendet sie die von JCS vorgeschriebenen Regeln zur Zahlenserialisierung nicht an. Signieren Sie Nachweise mit derselben Form sortierter Schlüssel, die Orbit verwendet, statt davon auszugehen, dass ein spezifikationsvollständiger RFC-8785-Prüfer einen übereinstimmenden Hash erzeugt.

curl -X POST https://api.orbit.devotel.io/api/v1/compliance/consent/receipts \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "cnt_9f…",
    "consent_manager_id": "acme-cm-001",
    "channel": "sms",
    "consent_type": "marketing",
    "receipt": {
      "receipt_id": "rcpt_77…",
      "issued_at": "2026-05-01T09:00:00.000Z",
      "purpose": "Promotional SMS",
      "fiduciary_id": "fid_acme",
      "signature": "MEUCIQ…",
      "payload": { "…": "…" }
    }
  }'

Rückgabe 201 mit { "id": …, "receipt_id": …, "verified": true }. Eine ungültige Signatur oder ein nicht registrierter/inaktiver Manager liefert 422 CONSENT_RECEIPT_INVALID — das Detail weist darauf hin, dass die Nutzdaten manipuliert worden sein können oder der Manager die Schlüssel rotiert hat.

Einen gespeicherten Nachweis erneut prüfen

POST /compliance/consent/receipts/{id}/verify prüft einen zuvor gespeicherten Nachweis erneut anhand des aktuellen Schlüssels des Managers — verwenden Sie dies während eines Audits, um zu bestätigen, dass ein Nachweis weiterhin gültig ist und ob sein Manager aktiv bleibt. {id} akzeptiert entweder die ID des Einwilligungsdatensatzes oder die receipt_id.

Einwilligungsnachweise setzen die Mandantenmigration consent_managers voraus. Bei Mandanten ohne diese Migration degradieren die Lesepfade kontrolliert: Die Managerliste gibt eine leere Liste zurück, und der Re-Verify-Endpunkt liefert 404. Das Ausstellen eines Nachweises ist fail-closed, daher liefert POST /compliance/consent/receipts bei Mandanten ohne Migration 422 CONSENT_RECEIPT_INVALID, statt zu degradieren — führen Sie die Migration aus, bevor Sie Nachweise ausstellen.

Weiterführende Referenzen

Ein DSGVO-Posture von Anfang bis Ende aufbauen — die Abfolge, die diese Einwilligungsebene speist.
Bestätigte Einwilligungen (Double-Opt-In-Handshakes) — der Beginn/Bestätigen/Status-Ablauf oberhalb eines einfachen Einwilligungsdatensatzes.
Einwilligungs-Posture: Die Richtlinien für unbekannte Einwilligung — die organisationsweiten Regler, die bestimmen, was Kontakte ohne Register-Eintrag empfangen dürfen (Marketing-Versand vs. CDP-Fanout).
Opt-Out & Suppressionslisten — Massenimport von Opt-outs und wie die Suppressionsliste Sendevorgänge steuert.
DSAR — Bearbeitung von Auskunfts-/Löschanträgen über den Einwilligungsdatensatz.
DLT-India-Onboarding — die Registrierungsebene, die DPDP-Einwilligungen bei indischen SMS ergänzt.
API-Referenz → Compliance — vollständige Anfrage-/Antwortschemas (aus der Live-API neu generiert).

Getting Started

Channels

Channels (Voice)

AI Agents

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Changelog

Einwilligungsmanagement und Nachweise

Einwilligungsmanagement und Nachweise

Kanäle und Zustände

Einwilligungen erfassen

Einwilligungen abrufen

Ablaufende Einwilligungen finden

Bestätigte Einwilligungen (Double-Opt-in-Handshakes)

Einwilligungsverlauf

Den Einwilligungsnachweis exportieren

Einen signierten Nachweis speichern

Einen gespeicherten Nachweis erneut prüfen

Weiterführende Referenzen

​Einwilligungsmanagement und Nachweise

​Kanäle und Zustände

​Einwilligungen erfassen

​Einwilligungen abrufen

​Ablaufende Einwilligungen finden

​Bestätigte Einwilligungen (Double-Opt-in-Handshakes)

​Einwilligungsverlauf

​Den Einwilligungsnachweis exportieren

​Einen Consent Manager registrieren

​Einen signierten Nachweis speichern

​Einen gespeicherten Nachweis erneut prüfen

​Weiterführende Referenzen

Einwilligungsmanagement und Nachweise

Kanäle und Zustände

Einwilligungen erfassen

Einwilligungen abrufen

Ablaufende Einwilligungen finden

Bestätigte Einwilligungen (Double-Opt-in-Handshakes)

Einwilligungsverlauf

Den Einwilligungsnachweis exportieren

Einen Consent Manager registrieren

Einen signierten Nachweis speichern

Einen gespeicherten Nachweis erneut prüfen

Weiterführende Referenzen