# POST /contacts/voice/unsubscribe

**Resource:** [Contacts](./contacts.md)  
**Scopes:** `contacts:write`  
**Write operation:** yes

Voice-agent unsubscribe endpoint. Returns text/plain. Called by a Retell voice agent when a caller asks to opt out. Resolves the caller by phone number (from args.phone in the Retell call envelope, with fallback to from_number for inbound or to_number for outbound calls). Unsubscribes ALL contacts in the workspace that share the phone number (Spam Act compliance -- up to 20 matched contacts). Sets email_unsubscribed and sms_unsubscribed to true on each matched contact. Returns a plain-text confirmation string the agent reads aloud. On error the response body begins with "UNSUBSCRIBE NOT COMPLETED -- DO NOT TELL THE CALLER THEY HAVE BEEN REMOVED" so the agent script can instruct the agent to handle the failure gracefully without misleading the caller.

## Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `phone` | body | string | no | Caller phone in E.164 or local format. If omitted, resolves from the Retell call envelope (from_number for inbound, to_number for outbound). Provide explicitly when testing outside a live Retell call. |
| `reason` | body | string | no | Optional reason for the unsubscribe (e.g. "caller requested via voice agent"). Stored as a note on the contact. |

## Request example

```bash
# Retell sends the full call envelope. The args wrapper is required.
curl -X POST \
  "https://api.trustpager.com/functions/v1/api/v1/contacts/voice/unsubscribe" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "call": { "from_number": "+61412345678" },
    "name": "unsubscribe_caller",
    "args": {
      "reason": "caller requested via voice agent"
    }
  }'
```

## Response example

```json
Done! You have been removed from our contact list and will no longer receive calls, SMS, or emails from us.
```

---
Base URL: `https://api.trustpager.com/functions/v1/api/v1` — Auth: `Authorization: Bearer YOUR_API_KEY`