> ## 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. # PHI-nahe Audiences registrieren > Walkthrough des PHI-nahen Audience-Registers: wann eine Liste oder ein Segment zu designieren ist, wie der atomare Full-Replacement-PUT funktioniert, wie der Kampagnen-Launch-Precheck reagiert und wie der Audit-Trail gelesen wird. # PHI-nahe Audiences registrieren Das PHI-nahe Audience-Register ist die Liste Ihrer Organisation von Kontakt-Listen und Segmenten, deren Mitglieder PHI tragen — zum Beispiel Patienten, die in Behandlungs-Outreach eingewilligt haben. Die Referenz [HIPAA-Steuerungen](/compliance/hipaa#phi-adjacent-audience-registry) dokumentiert die zwei Endpunkte; diese Anleitung führt durch deren produktiven Einsatz: was zu designieren ist, wie die Schreib-Semantik funktioniert, was beim Kampagnen-Launch passiert und wie der Audit-Trail zu lesen ist. Das Register ist **mandanteneigen**. Devotel designiert nie Audiences in Ihrem Namen und scopet PHI nie für Sie — die Designierungen sind Ihre Attestation, sie sind BAA-geskartete Steuerungen, die Sie betreiben, und sie wirken erst, sobald HIPAA für Ihre Organisation im Umfang ist. Wenn Sie das BAA noch nicht ausgeführt und den HIPAA-Modus noch nicht aktiviert haben, führen Sie zuerst die Sequenz [HIPAA-Onboarding](/guides/hipaa-onboarding) aus. ## 1. Wann eine Audience PHI-nah zu markieren ist Die Designation folgt der **Provenance**: markieren Sie die Audiences, deren Quelldaten PHI enthalten, unabhängig davon, was eine einzelne Kampagne an sie sendet. Eine Audience ist PHI-nah wegen der Herkunft ihrer Mitglieder — ein Patienten-Termin-Erinnerungs-Import, eine Behandlungs-Outreach-Opt-in-Liste — nicht wegen des Texts, den Sie diese Woche zufällig schreiben. Deshalb liegt die Designation auf der Audience selbst und nicht auf einer Kampagne: welche Kampagne die Audience auch aufnimmt, die Designation reist mit. Markieren Sie eine Audience als PHI-nah, wenn: * Ihre Mitglieder aus einem System importiert wurden, das PHI hält (ein EHR-Export, eine Patientenportal-Opt-in-Synchronisation). * Die Liste oder das Segment anhand PHI-tragender Kriterien gefiltert oder zusammengestellt ist (diagnose-nahe Tags, Behandlungs-Kohorten). * Die Datenkarte Ihres Compliance-Beauftragten die Audience als PHI im Umfang erfasst. Designieren Sie eine Audience nicht „nur zur Sicherheit". Eine Designation hängt das [BAA-Launch-Gate](#4-wie-der-launch-precheck-das-register-nutzt) an jede Kampagne, die die Audience nutzt — das Designieren von Audiences, die keine PHI tragen, blockiert Launches aus keinem Compliance-Grund. **Wer attestieren darf:** beide Endpunkte verlangen die `owner`- oder `admin`-Rolle — dasselbe Gate, das die [BAA-Endpunkte](/compliance/baa) nutzen. Ein `developer` oder `viewer` erhält `403`. Halten Sie die Designations-Entscheidung bei Ihrem HIPAA-Compliance-Beauftragten; die Plattform zeichnet *wer* das Register bei jedem Schreibvorgang geändert hat, auf (siehe [Audit-Trail](#5-audit-trail)). ## 2. Listen- versus Segment-IDs wählen Das Register hält Audience-IDs — jeder Eintrag ist entweder eine **Kontakt-Listen-ID** oder eine **Segment-ID**, als reiner String übergeben. Der Kampagnen-Launch-Precheck löst nur Audiences vom Typ `list` und `segment` gegen das Register auf; pro Kontakt zusammengestellte Audiences (alle Kontakte, CSV-Upload, manuelle Eingabe) werden stattdessen zum Sende-Zeitpunkt Empfänger-für-Empfänger bewertet und haben daher keine zu designierende Register-ID. Um die ID für eine Designation abzuleiten: ```bash theme={null} # Kontakt-Listen GET /api/v1/contacts/lists # Segmente GET /api/v1/contacts/segments ``` Kopieren Sie das `id`-Feld der Liste oder des Segments, das Sie designieren. IDs sind nach dem Trimmen 1–128 Zeichen; alles Längere oder Leere wird beim Schreiben mit `422` abgelehnt. Das Register hält maximal **500** IDs pro Organisation — ein `PUT` mit mehr gibt `422` zurück. > Designieren Sie die **Quell**-ID, nicht eine nachgelagerte Kopie. Wenn eine PHI-tragende Liste ein abgeleitetes Segment speist, entscheiden Sie, ob das abgeleitete Segment ebenfalls PHI enthält, und designieren Sie es explizit — der Precheck prüft die ID, die die Kampagne tatsächlich referenziert, und nichts sonst. ## 3. Der atomare PUT-Swap Das Register hat **eine** Schreiboperation: einen Full-Replacement-`PUT`. Es gibt kein `PATCH`, kein pro-ID `DELETE` — jeder Schreibvorgang ersetzt den gesamten designierten Satz in einer einzigen atomaren Anweisung, sodass ein gleichzeitiger `GET` nie ein teilweise angewandtes Update sieht. ```bash theme={null} PUT /api/v1/compliance/hipaa/phi-audiences { "audience_ids": ["list_9f2c1a", "seg_4b7e20", "list_31dc88"] } ``` Die Antwort spiegelt den gespeicherten Satz: ```json theme={null} { "data": { "audience_ids": ["list_9f2c1a", "seg_4b7e20", "list_31dc88"], "replaced": true } } ``` Der Body ist **idempotent**: dasselbe volle Satz zweimal zu senden erzeugt dasselbe gespeicherte Register und zwei getrennte Audit-Zeilen. Ein leeres Array löscht jede Designation: ```bash theme={null} PUT /api/v1/compliance/hipaa/phi-audiences { "audience_ids": [] } ``` Da der Schreibvorgang ein Swap ist, muss jeder Client **read-modify-write** befolgen: `GET` das aktuelle Register, fügen Sie Ihre ID im Ergebnis hinzu oder entfernen Sie sie, und `PUT` den gesamten Satz zurück. Bauen Sie den Body nie nur aus lokalem Zustand — Sie würden still Designierungen fallen lassen, die ein anderer Betreiber hinzugefügt hat. Um eine Designation zu liftieren, `PUT` das Register ohne diese ID. Um erneut zu designieren, `PUT` es mit der wieder hinzugefügten ID. Einzelne IDs, die einen Swap überleben, bleiben unverändert; nur die Zugehörigkeit zum Satz zählt. ## 4. Wie der Launch-Precheck das Register nutzt Zwei Gates schützen PHI an verschiedenen Punkten, und das Register speist das erste: 1. **Launch-Precheck (Kampagnen-Ebene, hartes Gate).** Bevor eine Kampagne Entwurf/geplant verlässt, löst der Precheck ihre Audience-ID gegen das Register auf. Eine designierte ID plus ein BAA, das nicht `executed` und in-Laufzeit ist, verweigert den Launch mit `422 HIPAA_BAA_REQUIRED` — bevor ein einziger Empfänger angemeldet wird. Wenn der Compliance-Zustand nicht gelesen werden kann, versagt der Precheck geschlossen mit `500 HIPAA_BAA_GATE_DB_FAIL`, statt die Audience still zuzulassen. 2. **Pro-Empfänger-Sende-Gate (Nachrichten-Zeit, unverändert).** Das bestehende Send-Gate gilt weiterhin für jeden Einzelversand und konsultiert das Register nicht — Legacy-Einzelversende werden allein von ihm gesteuert. Ein blockierter Launch taucht mit der untenstehenden Verweigerung auf. Das `details.reason` sagt Ihnen genau, welcher BAA-Zustand ihn freigibt: ```json theme={null} { "error": { "code": "HIPAA_BAA_REQUIRED", "status": 422, "message": "The designated PHI-adjacent audience for this campaign requires an executed Business Associate Agreement (BAA) before outbound sends are permitted.", "details": { "reason": "pending", "audience": { "type": "list", "id": "list_9f2c1a" } } } } ``` | `reason` | Was es bedeutet | Wie freigegeben | | ------------ | --------------------------------------------------------------- | -------------------------------------------------------------------------- | | `not_signed` | PHI ist attestiert im Umfung, aber kein BAA wurde je ausgeführt | BAA ausführen — [BAA-Ablauf](/compliance/baa) | | `pending` | BAA-Ausführung begonnen, aber nicht abgeschlossen | Den Ausführungsschritt abschließen (`POST /api/v1/compliance/baa/execute`) | | `expired` | Das ausgeführte BAA hat seine Einjahreslaufzeit überschritten | BAA erneut ausführen | Es gibt **zwei** Wege freizugeben, und sie sind Compliance-Entscheidungen, nicht Plattform-Entscheidungen: * **Das BAA auflösen** — ausführen oder erneut ausführen, sodass das Gate passiert. Das ist der richtige Weg, wenn die Audience wirklich PHI trägt. * **Die Designation entfernen** — `PUT` das Register ohne die Audience-ID. Das ist der richtige Weg *nur*, wenn die Audience versehentlich designiert war. Eine Designation zu liften, um das Gate zu umgehen, ist in Ihrem eigenen Audit-Protokoll sichtbar. Im Kampagnen-Assistenten des Dashboards zeigt die Wahl einer designierten Audience eine beratende Warnung beim Audience-Schritt. Die Warnung blockiert die **Weiter**-Schaltfläche nicht — die Designation kann liftiert oder das BAA vor dem Launch ausgeführt werden — aber das harte Gate beim Launch gilt immer. ## 5. Audit-Trail Zwei Datensatz-Klassen landen im Audit-Protokoll Ihrer Organisation: * **`hipaa.phi_audiences.set`** — eine Zeile pro `PUT`, die den handelnden Benutzer, die Organisation und den vollen Post-Schreib-ID-Satz aufzeichnet. Das ist Ihre Versionierungsgeschichte: das Register hat keine separate Revisions-Ressource — die Sequenz von Audit-Zeilen *ist* der Versionsverlauf. Um zu rekonstruieren, was zu einem Zeitpunkt designiert war, gehen Sie die `set`-Zeilen zurück; um zurückzusetzen, `PUT` den ID-Satz einer früheren Zeile. * **`HIPAA_BAA_REQUIRED`-Launch-Verweigerungen** — jeder blockierte Launch wird mit dem verweigernden Grund und der bewerteten Audience geloggt. Diese Zeilen verdoppeln als Ihre Incident-Queue: eine Verweigerung bedeutet, dass entweder Compliance-Arbeit aussteht (BAA nicht ausgeführt) oder eine Designation und eine Kampagne uneinig sind. Überprüfen Sie beide Klassen in einem Rhythmus, der Ihrem Compliance-Programm entspricht — wöchentlich ist ein brauchbarer Standard für einen aktiven Gesundheits-Workspace. Exportieren Sie das Audit-Protokoll neben Ihrem PHI-Zugriffsprotokoll, wenn Sie Belege für ein externes Audit zusammenstellen; der HIPAA-Paket des [Evidence Binders](/compliance/evidence-binder) rollt BAA-Haltung und PHI-Zugriffsprotokollierung zu einem signierten Download. **Incident-Runbook für eine unerwartete Verweigerung:** 1. Lesen Sie das `details.reason` und `details.audience.id` der Verweigerung. 2. Prüfen Sie `GET /api/v1/compliance/baa/` — wenn das BAA `pending`/`expired`/nicht ausgeführt ist, lösen Sie es über den [BAA-Ablauf](/compliance/baa) auf. 3. Wenn das BAA gesund ist, prüfen Sie, ob die Audience überhaupt designiert sein sollte: `GET /api/v1/compliance/hipaa/phi-audiences` und vergleichen Sie mit Ihrer Datenkarte. Liftieren Sie eine fehlerhafte Designation mit einem Swap (`PUT` ohne die ID). 4. Zeichnen Sie das Ergebnis in Ihrem eigenen Incident-Register auf — die Audit-Zeilen oben sind die Belege, die Sie zitieren. ## 6. Konfliktbehebung bei gleichzeitigen Überschrieben Der Register-`PUT` selbst gibt nie `409` zurück — der atomare Einzel-Anweisungs-Swap bedeutet, dass ein Schreibvorgang immer committet, und der letzte Schreiber gewinnt. Das Konfliktrisiko ist **verlorene Updates zwischen Betreibern**, nicht abgelehnte Schreibvorgänge: * Betreiber A und Betreiber B beide `GET` das Register. * A fügt `list_aaa` hinzu und `PUT`s. B — von A's vorherigem Snapshot arbeitend — fügt `list_bbb` hinzu und `PUT`s. * B's Swap lässt still `list_aaa` fallen. Mitigationen: * **Unmittelbar vor dem Schreiben lesen.** Halten Sie das Read-Modify-Write-Fenster kurz; tragen Sie ein geholtges Register nicht über eine Bearbeitungssitzung hinweg — re-`GET`, wenn Sie bereit zum `PUT` sind. * **Nach dem Schreiben verifizieren.** `GET` erneut und bestätigen Sie, dass Ihre ID vorhanden ist und keine unverbundene Designation verloren ging. Wenn etwas verschwunden ist, zeigen die `hipaa.phi_audiences.set`-Zeilen des Audit-Protokolls, wessen Schreibvorgang es überschrieben hat und welcher Satz wiederherzustellen ist. * **Register-Bearbeitungen organisatorisch serialisieren.** Da Designation eine Compliance-Attestation ist, leiten Sie Bearbeitungen durch eine Rolle (den Compliance-Beauftragten), statt sie über Betreiber zu verteilen — ein prozeduraler Fix, der das Race ganz beseitigt. Wenn Sie `422` statt Erfolg sehen, ist die Ursache Validierung, nicht Konflikt: mehr als **500** IDs, eine leere ID nach dem Trimmen oder eine ID über 128 Zeichen. Trimmen Sie und versuchen Sie es mit dem vollen Satz erneut. ## Siehe auch * [PHI-nahe Audience-Designationen](/compliance/phi-audiences) — die Endpunkt-Referenz für den Register-Vertrag (Obergrenze, Replace-Semantik, Audit-Aktion) * [HIPAA-Compliance-Steuerungen](/compliance/hipaa) — die volle Steuerungs-Referenz, die das Register speist * [BAA — Business Associate Agreement](/compliance/baa) — der Lebenszyklus, den der Launch-Precheck durchsetzt * [HIPAA-Onboarding: vom BAA bis zur Audit-Bereitschaft](/guides/hipaa-onboarding) — die Sequenz, die einen Gesundheits-Workspace zur Audit-Bereitschaft bringt, bevor Sie Audiences designieren * [Send-Gates](/compliance/send-gates) — das Pro-Empfänger-Gate, das den Launch-Precheck ergänzt