Skip to main content

​
Troubleshooting: HIPAA_BAA_REQUIRED (422)

Your campaign launch was refused with a 422 and code HIPAA_BAA_REQUIRED, or the campaign wizard shows the PHI-adjacent audience warning on the audience picker:
This means the campaign’s audience is designated PHI-adjacent, and your organization’s BAA is not executed and in-term. This page maps the two symptom shapes to the fix you can run yourself. For the full concept — the BAA lifecycle, the registry, and the launch precheck — see HIPAA compliance.
The BAA and PHI-adjacent designations are tenant-owned compliance controls: you attest that PHI is in scope, you execute the agreement, and you decide which of your audiences carry PHI. Orbit enforces the designation you set — it never designates an audience on its own.

​
What a PHI-adjacent designation means

The PHI-adjacent audience registry is a register of contact-list and segment ids whose members carry PHI — for example, patients opted into treatment outreach. The designation belongs to the audience, not to any individual campaign: an audience is PHI-adjacent because of its source data, so the designation follows it into every campaign that picks it up, for as long as the designation holds.

​
Warning on the picker vs gate at launch

Campaigns have two surfaces that talk about PHI-adjacent audiences, and they mean different things:
  • The wizard warning is advisory. Choosing a designated list or segment in the campaign wizard’s audience step shows the PHI-adjacent warning, but it does not block the Next button — the designation may be lifted, or the BAA executed, before you actually launch.
  • The launch precheck is the hard gate. At launch, the precheck refuses with 422 HIPAA_BAA_REQUIRED if the audience resolves to a designated list or segment id and your BAA is not executed and in-term. The refusal charges nothing and creates no draft — fix the gate and relaunch.

​
Resolution path

Work through these in order:
  1. Check BAA status under Settings → Compliance → BAA, or read GET /api/v1/compliance/baa/ — both show the current baa_status and, once executed, the days remaining in term.
  2. Execute the BAA if the status is pending or expired. From the Compliance → BAA page, type your name exactly as shown in the signer field and confirm; the same flow is available over the API as POST /api/v1/compliance/baa/execute (owner only). Once the status reads executed, the precheck passes and the campaign launches normally. The full flow is documented under Business Associate Agreement (BAA).
  3. Or lift the designation if the audience genuinely carries no PHI. Remove its id from the registry with PUT /api/v1/compliance/hipaa/phi-audiences (owner/admin) — the endpoint replaces the whole registry in one write, so pass the current list minus the id you are clearing. Confirm the current contents first with GET /api/v1/compliance/hipaa/phi-audiences. Lift a designation only after you have verified the audience’s source data holds no PHI — the registry governs every future campaign that picks this audience up.

​
Edge notes

  • Only list- and segment-type audiences resolve against the registry at launch. Audiences assembled per contact (all contacts, CSV upload, manual entry) are evaluated recipient-by-recipient at send time by the per-recipient send gate instead — see Send gates → BAA — the HIPAA send gate.
  • The registry governs campaign launches only. Legacy one-off per-recipient sends are covered by the same send gate, which does not consult the registry.
  • An expired BAA blocks again even if it was executed before — executed BAAs carry a one-year term and must be re-executed after it passes.

​
Still blocked? Pass to support

Include in the ticket:
  • The request_id from meta.request_id on the 422 response
  • The campaign id and the audience (list/segment) id you tried to launch against
  • Your current baa_status from GET /api/v1/compliance/baa/
Cross-references: HIPAA compliance · Business Associate Agreement (BAA) · Error code reference · API reference