Erase a contact's message content

Server URLloading...

POST

/v1/contacts/{contact_number}/erase

Send

Authorization

Path

Body

Permanently removes every message body and media URL associated with a single contact across your organization, for privacy requests such as GDPR or CCPA erasure. The erasure is all-or-nothing: every redaction and the audit record are committed together, or none of them are.

Outbound message bodies and media for messages sent to the contact, and inbound message bodies and media for messages received from the contact, are cleared and stamped with a redaction timestamp. Consent and consent history records are deliberately left intact, since they are your regulator-facing record of opt-in.

The request takes no body. There is no not-found error: erasing a contact you have no messages for, or erasing the same contact twice, returns 200 OK with inbound_redacted and outbound_redacted of 0, and an audit record is still written.

Requires the messages:erase scope. Issue this scope on a separate key from your sending and read keys so a compromised data-plane key cannot trigger an erasure storm. The route is rate-limited per organization (100/hour by default); exhausted callers receive 429 RATE_LIMITED with a Retry-After header.

Path Parameters

Response Body

curl -X POST "https://example.com/v1/contacts/%2B15551234567/erase" \  -H "Content-Type: application/json" \  -d '{}'

{
  "success": true,
  "data": {
    "contact_number": "+15551234567",
    "inbound_redacted": 138,
    "outbound_redacted": 412,
    "erased_at": "2026-04-28T14:01:53Z",
    "audit_log_id": "01HXJZ4Q3A0PZ4QH7JZK6S0R3M"
  }
}

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "authentication failed",
    "request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
  }
}

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "missing required scope",
    "request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "validation failed",
    "request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM",
    "details": {
      "to": "must be E.164",
      "body": "must be 1..1600 chars"
    }
  }
}

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "rate limited",
    "request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
  }
}