> ## 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 on Messaging Conversations > Place a litigation hold on a messaging conversation so the retention sweep preserves the thread for eDiscovery — owner/admin-only, fully audit-logged # Legal Holds on Messaging Conversations A **legal hold** (litigation hold) preserves a messaging conversation for eDiscovery. When you place a hold on a conversation, every message in that thread is exempt from the age-based retention sweep — the sweep skips both the media-null step and the hard-delete step — so the thread survives for litigation preservation, supervision review, or a regulator's request. This page covers messaging conversations (SMS, MMS, WhatsApp, RCS, email, chat); for voice and video recordings, the same hold is exposed on the **Settings → Compliance → Legal holds** screen under recordings. Preservation is your control, not ours — and this page is **not legal advice.** Whether a conversation must be preserved, for how long, and who must attest to it are your organization's calls. Confirm the specifics with qualified counsel. *** ## What a hold protects you from Retention is designed to delete. Under **Settings → Compliance → Retention**, each channel has a window; once a message ages past it, the retention sweep first clears the message's media (the `media_url` is nulled), then — when your retention policy applies hard delete — removes the message row entirely. That is the right posture for storage limitation in normal operation, and the wrong posture when counsel notifies you that a matter is anticipated or ongoing. A legal hold inverts that for one conversation: place the hold, and the retention sweep skips the thread for as long as the hold stands. Messages that arrive **after** the hold was placed are also protected — the hold belongs to the conversation, not just to the messages that existed at the moment you placed it. A held conversation is also protected against direct destruction: a hard-delete of a held conversation is refused with `409 legal_hold_active`, so no operator — admin included — can destroy a preserved thread without first releasing the hold. A hold does not change what you can read or export. Held threads remain fully visible in the dashboard and through the conversations API; the hold only stops the deletion machinery. *** ## Place or release a hold The hold surface is one endpoint pair per conversation. Placing and releasing require an **owner or admin** role; reads use the same gate. Every write is recorded in your audit log (see [Audit trail](#audit-trail)). ### Check the current hold state ```bash theme={null} curl https://api.orbit.devotel.io/api/v1/compliance/legal-hold/conversations/{conversation_id} \ -H "X-API-Key: dv_live_sk_..." ``` ```json theme={null} { "data": { "conversation_id": "conv_01J…", "legal_hold": true, "reason": "Matter 2026-0041 — anticipated litigation", "updated_by": "user_01H…", "updated_at": "2026-08-20T14:02:11.000Z", "message_count": 342, "held_message_count": 342 } } ``` * `legal_hold` — `true` while the conversation is exempt from the retention sweep. * `reason` — the free-text justification recorded with the last change (up to 512 characters). * `updated_by` / `updated_at` — who changed the hold most recently and when. * `message_count` / `held_message_count` — the protected fraction of the thread, so you can confirm the hold actually propagated. A conversation id that does not exist returns `404`. ### Place the hold Send `hold: true` with the reason your matter-management process requires: ```bash theme={null} curl -X PUT https://api.orbit.devotel.io/api/v1/compliance/legal-hold/conversations/{conversation_id} \ -H "X-API-Key: dv_live_sk_..." \ -H "Content-Type: application/json" \ -d '{ "hold": true, "reason": "Matter 2026-0041 — anticipated litigation; preserve custodian thread" }' ``` The response echoes the resulting state plus `messages_updated` — the number of existing message rows the hold was propagated to. Placing a hold is idempotent: re-sending `hold: true` on an already-held conversation simply re-stamps the reason and timestamp. ### Release the hold When the matter is closed and counsel confirms preservation may end, release with `hold: false`: ```bash theme={null} curl -X PUT https://api.orbit.devotel.io/api/v1/compliance/legal-hold/conversations/{conversation_id} \ -H "X-API-Key: dv_live_sk_..." \ -H "Content-Type: application/json" \ -d '{ "hold": false, "reason": "Matter 2026-0041 closed; hold released per counsel" }' ``` After release, the thread rejoins the normal retention sweep on the next cycle: messages already past their window become sweep-eligible again. Release is not reversible. Once the hold is off, a message that is already older than its retention window can be media-nulled and hard-deleted by the next sweep. Confirm the matter is genuinely closed — and mirror an [immutable archival export](/compliance/archival-export) first if you still need a preserved copy — before you release. *** ## Who can place a hold Legal-hold reads and writes both require an **owner or admin** API key or dashboard role. Preservation is a compliance-governance decision, so the surface is deliberately kept off the everyday messaging operator role. A caller without the role receives `403`. ### Audit trail Every place-or-release call is written to your workspace audit log with the resulting hold state, the recorded reason, and the number of messages the hold propagated to. An auditor can reconstruct the preservation chain — who held which conversation, why, when, and when it was released — from the audit log alone. The most recent reason, actor, and timestamp also stay readable on the conversation itself via the `GET` endpoint. *** ## How the hold interacts with retention and erasure * **Age-based retention sweep.** Held conversations are skipped entirely — no media-null, no hard-delete — for as long as the hold stands. This includes messages that arrive after the hold was placed. * **Admin hard-delete.** Refusing to destroy a held conversation is by design: the hard-delete path returns `409 legal_hold_active` until the hold is released. Use the reversible archive option if you merely want the thread out of the inbox. * **DSAR / erasure requests.** A legal hold is a preservation obligation, not a defensible-disposal shortcut — GDPR erasure and litigation preservation can genuinely conflict, and that conflict is resolved by your counsel, not by the platform. Erasure workflows do not silently override a held thread; reconcile holds against open erasure requests as part of your DSAR process (see [Data subject requests](/compliance/dsar)). * **Immutable archival.** A hold preserves the live thread in place; an [archival export](/compliance/archival-export) produces a tamper-evident copy you pin into your own WORM store. For matters likely to outlive your Orbit retention windows, run both: hold the thread, then archive it. *** ## Manage holds in the dashboard Go to **Settings → Compliance → Legal holds**. The screen covers both preservable entity kinds side by side: * **Messaging conversations** — paste the conversation id (visible in the conversation view and in the API), read the current hold state with its held/total message tally, and place or release the hold with a reason. * **Voice and video recordings** — the equivalent hold for recording ids, exempting them from the media-deletion retention sweep. The screen is visible to owner and admin roles only, the same gate the API enforces. *** ## Your preservation posture stays yours Legal holds are a **tenant-owned control**: Orbit provides the exemption, the audit trail, and the API surface — when preservation must start, which conversations it covers, what reason is sufficient, and when it may end are your organization's decisions. Nothing places a hold automatically; every hold exists because an owner or admin in your workspace created it, and every one of those decisions is auditable. *** ## Related Copy preserved records into a tamper-evident bundle for your own WORM store. Access and erasure workflows, and how to reconcile them with open holds. Assemble audit-ready evidence bundles from the controls you configured. The broader control environment around logging and access.