HIPAA tenant BAA attestation checklist — first run

Run this checklist once when your organization first handles Protected Health Information (PHI) in Orbit. It covers only the Business Associate Agreement (BAA) attestation and gate-verification steps; the broader HIPAA enablement sequence (roles, retention, PHI-adjacent audiences, evidence binder) lives in the HIPAA first-enablement runbook.

This is a tenant-owned control. You decide whether PHI is in scope and an owner executes the BAA. Orbit supplies the e-sign pipeline and the send-time gate, but the legal determination is yours.

Step 1 — Declare PHI in scope

An owner or admin attests that PHI is entering the workspace. This is the act that raises the hipaa_required flag and opens the BAA execution flow.

Dashboard: Settings → Compliance → BAA → Start handling PHI
API: POST /api/v1/compliance/baa/require

curl -X POST "https://api.orbit.devotel.io/api/v1/compliance/baa/require" \
  -H "Authorization: Bearer $ORBIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Patient appointment reminders contain PHI" }'

After this call:

baa_status is pending
hipaa_required is true
The audit log receives a compliance.baa.hipaa_required entry naming the actor and the optional reason

The optional reason field (up to 500 characters) is recorded on the audit row.

Step 2 — Execute the BAA

Execution binds the organization, so it is owner-only. The signer reviews the rendered template, then types their legal name into typed_attestation; the server rejects the call unless it matches signer_name exactly.

Dashboard: Settings → Compliance → BAA → Execute BAA
API: POST /api/v1/compliance/baa/execute

curl -X POST "https://api.orbit.devotel.io/api/v1/compliance/baa/execute" \
  -H "Authorization: Bearer $ORBIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "signer_name": "Jane Roe",
    "signer_email": "jane@example.com",
    "typed_attestation": "Jane Roe"
  }'

On success:

baa_status becomes executed
baa_executed_at, expires_at, and days_until_expiry are populated
The audit log receives a compliance.baa.executed entry carrying the signer, template version, and signature method (type_the_name)

That audit entry is the proof record. The stored executed PDF is available from GET /api/v1/compliance/baa/download for 24 hours per request.

Step 3 — Verify the gate before sign-off

Before you call the first production PHI send official, prove the gate behaves. With the BAA still pending, a PHI-enabled send must return 422 HIPAA_BAA_REQUIRED. After execution, the same send must pass.

Before execution (or on a scratch workspace left at pending), attempt a PHI-bearing send:

curl -X POST "https://api.orbit.devotel.io/api/v1/messages" \
  -H "Authorization: Bearer $ORBIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155550101",
    "channel": "sms",
    "body": "Your appointment is confirmed."
  }'

Expected:

{
  "error": {
    "code": "HIPAA_BAA_REQUIRED",
    "status": 422,
    "message": "Business Associate Agreement required before sending PHI traffic.",
    "details": { "reason": "pending" }
  }
}

After execution, repeat the same send. It should proceed past the gate and return a normal send response.

The block lands before wallet hold, quota increment, or provider dispatch, so the rejected test send costs nothing. Do not skip this verification: the gate is fail-closed, and a passing send is the only proof the workspace is ready.

Step 4 — Find the audit log entries

Every BAA lifecycle action appends a row under Settings → Audit log. Look for these actions:

Audit action	What it proves
`compliance.baa.hipaa_required`	An owner or admin declared PHI in scope.
`compliance.baa.executed`	An owner executed the BAA — this is the proof record.
`compliance.baa.declined`	An owner or admin attested that PHI is no longer in scope.
`compliance.baa.reverted`	An owner returned an executed or expired BAA to the platform default.

The audit row, not the current status field, is the legal evidence of attestation. Keep the audit log reachable for compliance reviews.

Step 5 — Know the decline and revert paths

Two paths return the workspace to the default not_required state. They are not interchangeable.

Decline (`compliance.baa.declined`)

Use this when PHI was declared in scope but the organization has not yet executed the BAA and now attests that no PHI is in scope.

Who: owner or admin
API: POST /api/v1/compliance/baa/decline
When it fires: from pending only; it refuses an executed BAA with 400
Effect: clears hipaa_required, returns baa_status to not_required, and lifts the send gate

curl -X POST "https://api.orbit.devotel.io/api/v1/compliance/baa/decline" \
  -H "Authorization: Bearer $ORBIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "No PHI in scope; rolling back the attestation." }'

Revert (`compliance.baa.reverted`)

Use this after an executed or expired BAA has run its contractual course and HIPAA mode has been disabled.

Who: owner only
API: POST /api/v1/compliance/baa/revert
When it fires: from executed or expired only; requires HIPAA mode to be off first
Effect: returns baa_status to not_required while preserving the executed PDF and audit history

curl -X POST "https://api.orbit.devotel.io/api/v1/compliance/baa/revert" \
  -H "Authorization: Bearer $ORBIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Organization no longer processes PHI." }'

If you try to revert while HIPAA mode is still enabled, the call returns 400 with a message asking you to disable HIPAA mode first.

Fail-closed rule

The BAA gate is fail-closed. There is no bypass, tenant override, or support path that opens it while the required proof is missing. An unverifiable compliance state blocks sends rather than risk a PHI transmission. Treat any 500 HIPAA_BAA_GATE_DB_FAIL response as a verification outage, not a missing BAA, and retry.

Business Associate Agreement (BAA) flow — full lifecycle, states, and endpoints
HIPAA BAA gate evaluation guide — how the gate evaluates a send
HIPAA first-enablement runbook — roles, retention, PHI audiences, and evidence binder
HIPAA readiness checklist runbook — from the free checklist tool to go/no-go

Getting Started

Channels

Channels (Voice)

AI Agents

Campaigns

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Brand & press

Changelog

HIPAA tenant BAA attestation checklist — first run

HIPAA tenant BAA attestation checklist — first run

Step 1 — Declare PHI in scope

Step 2 — Execute the BAA

Step 3 — Verify the gate before sign-off

Step 4 — Find the audit log entries

Step 5 — Know the decline and revert paths

Decline (`compliance.baa.declined`)

Revert (`compliance.baa.reverted`)

Fail-closed rule

​HIPAA tenant BAA attestation checklist — first run

​Step 1 — Declare PHI in scope

​Step 2 — Execute the BAA

​Step 3 — Verify the gate before sign-off

​Step 4 — Find the audit log entries

​Step 5 — Know the decline and revert paths

​Decline (compliance.baa.declined)

​Revert (compliance.baa.reverted)

​Fail-closed rule

​Related pages

HIPAA tenant BAA attestation checklist — first run

Step 1 — Declare PHI in scope

Step 2 — Execute the BAA

Step 3 — Verify the gate before sign-off

Step 4 — Find the audit log entries

Step 5 — Know the decline and revert paths

Decline (`compliance.baa.declined`)

Revert (`compliance.baa.reverted`)

Fail-closed rule

Related pages