PHI-adjacent audience designations

The PHI-adjacent audience registry is your organization’s register of contact-list and segment ids whose members carry PHI. This page is the reference for the two registry endpoints: what a designation attests, how GET lists and PUT replaces the id set, the server-side ceiling on registry size, and how the BAA lifecycle and HIPAA controls interact with the registry. For a step-by-step walkthrough, see Register PHI-adjacent audiences; for the full HIPAA control surface, see HIPAA compliance.

The registry is a tenant-owned compliance control. You decide which audiences carry PHI; Orbit enforces the designations you set and never designates an audience on your behalf. Designations take effect only once HIPAA is in scope for your organization.

Where this fits

Designation is the middle step of the HIPAA enablement sequence:

Attest and execute — attest that PHI is in scope and execute your BAA (HIPAA onboarding).
Designate — register every contact-list and segment id whose members carry PHI, on this page’s endpoints.
Verify and launch — when HIPAA is in scope and a campaign’s audience resolves to a designated list or segment id, the campaign launch precheck evaluates the reference against this registry and refuses the launch with 422 HIPAA_BAA_REQUIRED until your BAA is executed and in-term (see Interaction with the BAA gate).

If you have not designated any audience, the registry is empty and the launch precheck has no list or segment id to evaluate — nothing carries the designation forward. Audiences assembled per contact (all contacts, CSV upload, manual entry) are then evaluated recipient-by-recipient at send time instead: the per-recipient BAA gate decides, per recipient, whether the send may proceed. Designation converts that per-recipient evaluation into an audience-level yes/no at launch.

BAA ordering

Designations stay inert until the BAA is executed and in-term — the launch precheck enforces the same BAA lifecycle the per-recipient gate does.

HIPAA checklist

Designation is one control on the HIPAA control surface the checklist walks: attestation, BAA, then the registry.

First-enablement runbook

The end-to-end first-enablement sequence designation slots into.

What a designation attests

Under HIPAA mode — once your organization has attested that PHI is in scope — a designated list or segment id tells the platform: members of this audience may carry Protected Health Information (PHI). The designation follows the audience itself, not any individual campaign: an audience is PHI-adjacent because of its source data (an EHR export, a treatment-outreach opt-in list), so every campaign that picks the audience up inherits the designation for as long as it stays in the registry. The registry holds audience id strings — contact-list ids and segment ids, 1–128 characters each. Audiences assembled per contact (all contacts, CSV upload, manual entry) have no registry id to designate and are evaluated recipient-by-recipient at send time instead.

List the registry (GET)

GET /api/v1/compliance/hipaa/phi-audiences

Returns the organization’s full designated id set — there is no pagination; the whole registry is returned in one response:

{
  "data": {
    "audience_ids": ["list_9f2c1a", "seg_4b7e20"],
    "max": 500
  }
}

The max field reports the server-side registry-size ceiling: at most 500 ids per organization. Because the campaign launch precheck evaluates audiences against the registry, the ceiling is enforced write-side rather than by an ever-growing unbounded list. Both endpoints require the owner or admin role — the same gate the BAA endpoints use. A developer, viewer, or billing role receives 403. To rederive the id you want to designate:

GET /api/v1/contacts/lists      # contact lists
GET /api/v1/contacts/segments   # segments

Copy the id field of the list or segment you are designating. Both id kinds live side by side in the same registry — the examples below designate one contact-list id and one segment id: Designate a contact-list id — add list_9f2c1a alongside the entry another operator already stored:

# 1. Read the current registry
GET /api/v1/compliance/hipaa/phi-audiences
#    { "data": { "audience_ids": ["seg_4b7e20"], "max": 500 } }

# 2. PUT the union back (full replacement — never PUT only your id)
PUT /api/v1/compliance/hipaa/phi-audiences
{
  "audience_ids": ["seg_4b7e20", "list_9f2c1a"]
}

Designate a segment id — remove the list and designate a segment instead in one swap:

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

Both examples use the same read-modify-write discipline the PUT section below requires: PUT replaces the whole set, so build the body from the GET result, not from local state.

Replace the registry (PUT)

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

PUT is a full replacement of the designated id set — one write operation, no PATCH, no per-id DELETE. The write commits atomically in a single statement, so a concurrent GET never sees a partially applied update. The response echoes the stored set with a write-acknowledgement flag:

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

Because the write is a swap, every client must follow read-modify-write: GET the current registry, add or remove your id in the result, and PUT the whole set back. Building the body from local state alone silently drops designations another operator added. To lift a designation, PUT the registry without that id; to re-designate, PUT it with the id added back. An empty array clears every designation:

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

Validation failures return 422: more than 500 ids, or an id that is empty after trimming or over 128 characters. Whitespace is trimmed server-side. The audience_ids field defaults to an empty array, so a request missing that field clears the registry rather than failing. Every replacement is recorded in the organization’s audit log as a hipaa.phi_audiences.set entry carrying the acting user and the full post-write id set. The sequence of set rows is the registry’s version history — to reconstruct what was designated at a point in time, walk the rows back.

Interaction with the BAA gate

Designation feeds the campaign launch precheck: when HIPAA is in scope for your organization and a campaign’s audience resolves to a designated list or segment id, the launch is refused with 422 HIPAA_BAA_REQUIRED until your BAA is executed and in-term. The precheck evaluates the same BAA rules as the per-recipient send gate, so the two never disagree about what “BAA in-term” means. Neither gate fires until HIPAA is in scope — a designation on a workspace that has not attested PHI is inert. The BAA lifecycle — require, execute, decline, revert, and the one-year term — is documented under Business Associate Agreement (BAA). The per-recipient send gate’s verdicts and fail-closed behaviour are under Send gates. The healthcare workspace enable sequence — the checklist designation slots into — is under HIPAA compliance, and the first-enablement runbook that walks it end-to-end is HIPAA onboarding.

Troubleshooting: `422 HIPAA_BAA_REQUIRED`

When a launch is refused because a designated audience meets a BAA that is not executed and in-term, the resolution paths — execute the BAA, or lift the designation if the audience genuinely carries no PHI — are mapped on the troubleshooting page: Troubleshooting: HIPAA_BAA_REQUIRED (422). The check’s details.reason (not_signed, pending, expired) tells you which BAA state de-blocks the launch.

API reference

Method	Endpoint	Description	Required role
`GET`	`/compliance/hipaa/phi-audiences`	Read the full designated id set and the server-side ceiling (`max`)	`owner` / `admin`
`PUT`	`/compliance/hipaa/phi-audiences`	Full-replacement write of the designated id set (≤ 500 ids, each 1–128 chars)	`owner` / `admin`

Getting Started

Channels

Channels (Voice)

AI Agents

Campaigns

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Brand & press

Tutorials

Changelog

PHI-adjacent audience designations

PHI-adjacent audience designations

Where this fits

BAA ordering

HIPAA checklist

First-enablement runbook

What a designation attests

List the registry (GET)

Replace the registry (PUT)

Interaction with the BAA gate

Troubleshooting: `422 HIPAA_BAA_REQUIRED`

API reference

See also

​PHI-adjacent audience designations

​Where this fits

BAA ordering

HIPAA checklist

First-enablement runbook

​What a designation attests

​List the registry (GET)

​Replace the registry (PUT)

​Interaction with the BAA gate

​Troubleshooting: 422 HIPAA_BAA_REQUIRED

​API reference

​See also

PHI-adjacent audience designations

Where this fits

What a designation attests

List the registry (GET)

Replace the registry (PUT)

Interaction with the BAA gate

Troubleshooting: `422 HIPAA_BAA_REQUIRED`

API reference

See also