​

PHI-nahe Audiences registrieren

​

1. Wann eine Audience PHI-nah zu markieren ist

• 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.

​

2. Listen- versus Segment-IDs wählen

# Kontakt-Listen
GET /api/v1/contacts/lists

# Segmente
GET /api/v1/contacts/segments

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

PUT /api/v1/compliance/hipaa/phi-audiences
{
  "audience_ids": ["list_9f2c1a", "seg_4b7e20", "list_31dc88"]
}

{
  "data": {
    "audience_ids": ["list_9f2c1a", "seg_4b7e20", "list_31dc88"],
    "replaced": true
  }
}

PUT /api/v1/compliance/hipaa/phi-audiences
{
  "audience_ids": []
}

​

4. Wie der Launch-Precheck das Register nutzt

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.

{
  "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" }
    }
  }
}

• 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.

​

5. Audit-Trail

• 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.

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 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

• Betreiber A und Betreiber B beide GET das Register.
• A fügt list_aaa hinzu und PUTs. B — von A’s vorherigem Snapshot arbeitend — fügt list_bbb hinzu und PUTs.
• B’s Swap lässt still list_aaa fallen.

• 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.

​

Siehe auch

• PHI-nahe Audience-Designationen — die Endpunkt-Referenz für den Register-Vertrag (Obergrenze, Replace-Semantik, Audit-Aktion)
• HIPAA-Compliance-Steuerungen — die volle Steuerungs-Referenz, die das Register speist
• BAA — Business Associate Agreement — der Lebenszyklus, den der Launch-Precheck durchsetzt
• HIPAA-Onboarding: vom BAA bis zur Audit-Bereitschaft — die Sequenz, die einen Gesundheits-Workspace zur Audit-Bereitschaft bringt, bevor Sie Audiences designieren
• Send-Gates — das Pro-Empfänger-Gate, das den Launch-Precheck ergänzt