> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Legal holds: preserve recordings and message threads from retention sweeps

> Place and release litigation holds on voice/video recordings and messaging conversations from Settings → Compliance → Legal Holds — every held record stays exempt from the age-based retention sweep, and every change lands in the audit log as evidence.

# Legal holds: preserve recordings and message threads from retention sweeps

Your retention sweep deletes on age. That is the right default until a thread or a recording becomes material to an active legal matter — then age-based deletion destroys evidence you were ordered to keep. The legal-hold console (**Settings → Compliance → Legal Holds**) is the control you operate when litigation, a regulator, or counsel tells you to preserve: mark a messaging conversation or a voice/video recording as held, give the hold a reason, and the sweep skips it until you release it.

Every place and release is written to your [audit log](/guides/audit-log) with actor, reason, and timestamp, so the evidence trail for the hold itself exists the moment counsel asks for it.

<Note>
  Legal holds are a tenant-owned control: Orbit gives you the switch and the
  audit evidence; it does not decide what you must preserve, and this page is
  not legal advice. Confirm your preservation duties with counsel. Holds also
  interact with GDPR erasure — a record under an active hold is exempt from
  the retention sweep, and an erasure request routed through your [DSAR
  queue](/compliance/dsar) should account for anything your counsel has told
  you to keep.
</Note>

## What a hold does

Retention in Orbit runs as two age-based sweeps: one for messaging threads, one for voice and video recordings. Either sweep walks its records, and anything older than the retention window you configured is deleted — media files nulled, and rows hard-deleted when your retention policy says so.

A legal hold flips a `legal_hold` flag on the record:

* **Conversations (messaging threads)** — placing the hold stamps the flag on the conversation and on every message in it, across every channel the thread spans (SMS, WhatsApp, MMS, RCS, email, web chat). The sweep skips the whole thread while the flag is set.
* **Recordings (voice and video)** — the flag covers both the stored media file and the recording's catalog row, so neither the blob nor the metadata can be reaped while held.

Nothing else changes: held content stays readable and playable in the inbox and recording viewers, and new messages keep flowing into a held conversation. The hold only says "the sweep must not delete this."

## Place a hold

Open **Settings → Compliance → Legal Holds**. Placing and releasing holds requires the **owner** or **admin** role — the backend enforces the same gate on the endpoints, and other roles get the read-only view of the page.

The page is two editors side by side, behind the same lookup → hold → verify flow:

1. **Identify the record.** You need the conversation id (`cnv_…`, visible on the thread in the [inbox](/guides/inbox-setup) or returned by `GET /conversations`) or the recording id (`rec_…`, the recording catalog id). Lookups you have run before stay in the **Recent holds** list on this device, so a repeat check is one click.
2. **Look up.** Paste the id and select **Look up**. The editor shows the current hold state, and—for a conversation—how many of its messages are already preserved (for example, `148 of 152` if a hold was placed on the thread earlier).
3. **Set the reason.** Optional but do it: a reason like `SEC 17a-4 litigation — ticket C-1042` or `FINRA 4511 — order-date 2026-08-01` is what makes the audit entry legible to counsel six months later. Keep it short; the field caps at a few hundred characters.
4. **Place hold.** The state pill flips to **On hold**. The API equivalent:

```bash theme={null}
# Messaging conversation
curl -X PUT "https://api.orbit.devotel.io/api/v1/compliance/legal-hold/conversations/cnv_9f2a1e" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hold": true, "reason": "SEC 17a-4 litigation — ticket C-1042"}'

# Voice / video recording
curl -X PUT "https://api.orbit.devotel.io/api/v1/recordings/rec_4b8d2c/legal-hold" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hold": true, "reason": "FINRA 4511 — order-date 2026-08-01"}'
```

Both writes are `hold: boolean` plus the optional `reason`, hold the same owner/admin role gate, and take an API key (`X-API-Key`, live keys prefixed `dv_live_sk_`) or a dashboard token. Set `hold: false` to release.

## Verify the exemption against your retention policy

Before you tell counsel a record is preserved, verify two things:

1. **The flag is set.** Re-run the lookup — the state pill reads **On hold**. Over the API, `GET /api/v1/compliance/legal-hold/conversations/<id>` returns `legal_hold: true` with the reason, the actor, and the last-changed timestamp; for a conversation it also reports `message_count` and `held_message_count` so you can confirm the whole thread, not a slice, is covered. Recordings answer the same fields on `GET /api/v1/recordings/<id>/legal-hold`. When a conversation spans several call legs or video sessions, `GET /api/v1/recordings/conversation/<conversationId>/legal-hold` returns an aggregate `held_recordings` of `total_recordings` tally — a `3 of 4` there is the warning that one leg is unprotected.
2. **The sweep would have deleted it.** The exemption only matters if the record's age exceeds (or is approaching) your configured retention window. A thread your policy keeps for 90 days is safe for a month without a hold; a hold is what stops the deletion once that window elapses. Verify the window you actually configured before relying on the exemption.

Re-check periodically for long-running matters: a missed step above is the difference between "preserved" and "preserved except the newest messages, which nobody re-checked."

## Release the hold and export the evidence

When counsel closes the matter, release the hold — the record returns to normal lifecycle handling and the sweep processes it from its original age, so a five-year-old thread deleted at release is expected behaviour, not data loss.

**Release.** In the console, open the same editor, **Look up**, and select **Release hold** (optionally set a closing reason first). Over the API, send `hold: false`. The ledger records the release with the same actor/reason/timestamp shape as the placement.

**Evidence.** Releasing wipes nothing — the audit entries persist, and the ledger cannot be edited or deleted. To assemble the evidence pack for counsel or an auditor:

1. Filter the [audit log](/guides/audit-log) to the legal-hold entries: from the holds page, the **Access history** panel shows the latest changes and its **View full history** link opens the audit log pre-scoped to them; you can build the same slice yourself with the audit log's search and action filters.
2. Export that filtered view as CSV or JSON from the quick-export buttons (up to 10,000 rows), or queue the uncapped **Full export** for a complete pull.
3. The same evidence ships continuously if you subscribe an endpoint to the audit webhook event — hook it into the binder you maintain for your framework; the [evidence binder guide](/guides/compliance-evidence-binder) covers that assembly.

## Fit the hold into your retention posture

Holds are one control in a posture you own end to end:

* **Retention wins by default.** Your configured sweeps keep destroying on age until a hold says otherwise — that keeps storage and minimization obligations the norm, with preservation the explicit exception.
* **Erasure requests.** A held record still surfaces in a data-subject request — counsel decides whether a litigation duty overrides erasure, and you keep or release per that call. The conversation and recording exports in the [conversation archive](/guides/conversation-archive) and the recording catalog give you the DSAR data to review, and the [evidence binder](/guides/compliance-evidence-binder) packages the resulting attestation.
* **Chain of custody.** Because every change is audit-logged, the answer to "who touched this hold, and when" is an export away — review the hold history the way you review the rest of the ledger in the [audit log guide](/guides/audit-log).

Run the posture review on a schedule: open the holds page, walk the **Recent holds** list, and release whatever closed. A hold nobody revisits is a retention posture nobody designed.

## Console ⇄ guide cross-links

The console page this guide walks — **Settings → Compliance → Legal Holds** — keeps three companion surfaces one click away: the audit ledger it writes to ([audit log](/guides/audit-log)), the archive exports used for DSAR review ([conversation archive](/guides/conversation-archive)), and the evidence binder the finished attestation joins ([evidence binder](/guides/compliance-evidence-binder)). For the full retention-window configuration the exemption defends against, see the recording and messaging retention settings in **Settings → Compliance**.