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"
}'
{
"id": "6ac5d11b2d7ce50e5408be61",
"applied": true,
"active": true,
"revision": 1
}
Voice Calls (v1)
Record a Voice Opt-Out
Stop calling a recipient after they withdraw permission.
POST
/
v1
/
voice
/
opt-outs
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"
}'
{
"id": "6ac5d11b2d7ce50e5408be61",
"applied": true,
"active": true,
"revision": 1
}
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
For an email withdrawal with a known time and source ID, include both optional fields:
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.
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 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
string
required
Recipient phone number in E.164 format, including
+ and country code.string
required
verbal, email, or other. Use other for a withdrawal received by another method.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.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
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
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"
}'
{
"recipient": "+14155551234",
"channel": "email",
"occurredAt": "2026-10-06T14:22:10-07:00",
"evidenceReference": "salesforce:case-123:revocation"
}
{
"id": "6ac5d11b2d7ce50e5408be61",
"applied": true,
"active": true,
"revision": 1
}
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. |