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

# Record a Voice Opt-Out

> Stop calling a recipient after they withdraw permission.

When someone tells your agent to stop calling, or sends a withdrawal by email or another channel, report it to Trackly from your backend. A successful response blocks new outbound calls to that number from **this client's calling business**, regardless of which of its caller IDs or calling backends you use. You can record the withdrawal immediately without a CRM record ID or a known occurrence time. Keep any underlying call note, email, or other evidence in your own system; send its stable reference if you have one. Do not put the Trackly API key in Salesforce browser code.

Use an API key for the client account with the `voice_calls.write` scope and an active Voice Calls entitlement. The account must have a calling business in Trackly. Trackly derives that business from the key; you cannot choose another account or business in the request. This endpoint records withdrawals only. Contact Trackly for a documented reconsent or correction; do not resume calling based on a local CRM change alone.

An optional [recipient screening](/api-reference/voice/recipient-screening.md) result never clears a recorded opt-out, even when it reports no reassignment. Screening may also independently stop outbound calls while Trackly confirms a reassignment restriction.

## Body Parameters

**recipient** `string` *required*

Recipient phone number in E.164 format, including `+` and country code.

**channel** `string` *required*

`verbal`, `email`, or `other`. Use `other` for a withdrawal received by another method.

**occurredAt** `string`

When the recipient withdrew permission, as an ISO 8601 timestamp with a UTC offset, if known. Omit this field when unknown; Trackly retains the time it received the request without claiming that was the withdrawal time. Do not substitute the time your sync job ran. Times more than five minutes in the future are rejected. An explicit `null` or blank value is invalid.

**evidenceReference** `string`

Stable ID for the source record in your system, up to 256 characters, if one exists. For example, use a Salesforce call or case ID. Omit this field when no source ID exists; Trackly does not invent a CRM reference. Do not send the transcript or message body. Trackly trims surrounding spaces when recording new source IDs. An explicit `null` or blank value is invalid.

## Header

**Idempotency-Key** `string` *required*

Unique request ID, 1–128 printable characters. If the result is uncertain, retry with the same API key, key value, and exact body, including the same omitted fields. Changed input returns `409 idempotency_conflict`.

## Example

```bash cURL theme={null}
curl -X POST https://api.tracklysms.com/api/v1/voice/opt-outs \
  -H "X-Api-Key: trk_your_client_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: withdrawal-123" \
  -d '{
    "recipient": "+14155551234",
    "channel": "verbal"
  }'
```

For an email withdrawal with a known time and source ID, include both optional fields:

```json theme={null}
{
  "recipient": "+14155551234",
  "channel": "email",
  "occurredAt": "2026-10-06T14:22:10-07:00",
  "evidenceReference": "salesforce:case-123:revocation"
}
```

```json 200 OK theme={null}
{
  "id": "6ac5d11b2d7ce50e5408be61",
  "applied": true,
  "active": true,
  "revision": 1
}
```

Trackly retains the API-key actor, receipt time, and event ID even when the optional fields are omitted; occurrence time and external source remain unknown in that case. `applied: false` means a supplied source reference had already been recorded with another request ID; the response retains the earlier decision ID. `active` reports the restriction state immediately after the recorded event. A later Trackly-authorized correction or reconsent can change the current state. The same key and body return the same result without adding another withdrawal. When you omit `evidenceReference`, use the original key for retries because Trackly has no external source ID for duplicate-source matching.

## Errors

| Status | Code | Meaning |
| - | - | - |
| 401 | `missing_api_key`, `invalid_api_key` | No usable client API key was supplied. |
| 403 | `insufficient_scope`, `account_suspended`, `voice_not_entitled` | The key lacks permission, its account is suspended, or Voice Calls is disabled. |
| 409 | `calling_business_required` | Set up the client account's calling business first. |
| 409 | `idempotency_conflict`, `evidence_reference_conflict`, `opt_out_conflict` | The same request or source reference was used for different evidence, or a conflicting update remains unresolved. |
| 422 | `invalid_number`, `invalid_channel`, `invalid_field`, `invalid_fields`, `invalid_opt_out`, `idempotency_key_required` | Correct the request fields or header. |
| 429 | `rate_limit_exceeded` | API-key request limit was reached. |
| 503 | `opt_out_unavailable` | Outcome could not be confirmed. Retry the same request and key. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.