Skip to main content

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

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

Returns the organization’s full designated id set — there is no pagination; the whole registry is returned in one response:
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:
Copy the id field of the list or segment you are designating.

​
Replace the registry (PUT)

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:
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:
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 is under HIPAA compliance and 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

​
See also

Last updated: September 2026 For questions about PHI-adjacent designations, contact: compliance@devotel.io