latestOpenAPI 3.1.0raw.githubusercontent.com2026-08-136188852.7 MB

9cd7291d4228

communication

Retire a phone number (soft, default) or hard-delete (force=true, internal only)

Retire (default) or hard-delete (force=true, internal only) a phone number.

Default — soft-retire (ENG-847, HV-17): flips status to RETIRED, tears down per-number SIP infra best-effort, stamps actor/timestamp, and keeps the row and every dependent evidence row (SMS/voice usage, and the ENG-846 durable chunk/attempt/outbox/operation chain) intact. This is now the day-to-day, audited, reversible path (see .../restore).

force=true is the internal-only escape hatch that performs the actual, permanent hard delete (evidence-safe: dependent SMS/voice usage rows detach via ON DELETE SET NULL rather than cascading away) — the explicit, policy-driven purge, not an accidental cascade. Non-internal callers that pass force=true are rejected with 403.

delete/v1/communication/phone-numbers/{phone_number_id}

Path parameters

phone_number_idstring uuid required

Query parameters

forceboolean

Response

Successful Response