Opt-Outs API

Per-contact, per-channel opt-out records. When a contact opts out of a channel, future outbound sends on that channel for that contact are blocked at the compliance gate — across every campaign, flow, and direct-send path in the tenant. This API powers the dashboard’s bulk-CSV import wizard (one batched request replaces what used to be 50 000 sequential round-trips) and the export flow for compliance evidence. Base path: /api/v1/contacts/optouts Authentication: Clerk session (Authorization: Bearer <token>) or API key (X-API-Key). Scopes: contacts:read for GET, contacts:write for everything else (with role gate owner / admin / developer).

Worked sequence: opt a contact out, then read the list back

The run-through every integration does first: create an opt-out with POST /contacts/optouts, then confirm it shows up in the cursor-paginated GET /contacts/optouts list. The create call returns the full {data, meta} envelope — data.already_opted_out tells you whether this was a genuine create (false) or an idempotent re-apply of an opt-out the contact already had (true).

1. Create the opt-out

POST /api/v1/contacts/optouts

Request

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/contacts/optouts" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "contact": "+14155552671",
    "channel": "sms",
    "reason": "Customer reply STOP"
  }'

Node.js

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

const created = await orbit.request("POST", "/contacts/optouts", {
  contact: "+14155552671",
  channel: "sms",
  reason: "Customer reply STOP",
});
console.log((created as any).data.already_opted_out); // false on a genuine create

Python

import requests

resp = requests.post(
    "https://api.orbit.devotel.io/api/v1/contacts/optouts",
    headers={
        "X-API-Key": "dv_live_sk_your_key_here",
        "Content-Type": "application/json",
    },
    json={
        "contact": "+14155552671",
        "channel": "sms",
        "reason": "Customer reply STOP",
    },
)
created = resp.json()
print(created["data"]["already_opted_out"])  # False on a genuine create

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{
		"contact": "+14155552671",
		"channel": "sms",
		"reason": "Customer reply STOP"
	}`)
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/contacts/optouts", bytes.NewReader(body))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/contacts/optouts')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  contact: '+14155552671',
  channel: 'sms',
  reason: 'Customer reply STOP',
}.to_json

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
created = JSON.parse(res.body)
puts created.dig('data', 'already_opted_out') # false on a genuine create

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/contacts/optouts');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  'contact' => '+14155552671',
  'channel' => 'sms',
  'reason' => 'Customer reply STOP',
]));
$created = json_decode(curl_exec($ch), true);
var_dump($created['data']['already_opted_out']); // false on a genuine create

Response

{
  "data": {
    "id": "con_abc",
    "phone": "+14155552671",
    "email": null,
    "channel_preferences": {
      "sms": { "opted_out": true }
    },
    "already_opted_out": false,
    "updated_at": "2026-05-24T12:00:00Z"
  },
  "meta": { "request_id": "req_abc123", "timestamp": "2026-05-24T12:00:00Z" }
}

Re-send the identical body and the call stays safe to retry: the contact is already opted out, so you get 200 OK with already_opted_out: true in data — no duplicate audit entry, no second webhook fire:

{
  "data": {
    "id": "con_abc",
    "phone": "+14155552671",
    "email": null,
    "channel_preferences": {
      "sms": { "opted_out": true }
    },
    "already_opted_out": true,
    "updated_at": "2026-05-24T12:00:00Z"
  },
  "meta": { "request_id": "req_def456", "timestamp": "2026-05-24T12:01:00Z" }
}

2. Read the opt-outs list back

GET /api/v1/contacts/optouts

Request

cURL

curl "https://api.orbit.devotel.io/api/v1/contacts/optouts?channel=sms&limit=50" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

const page = await orbit.request<unknown>("GET", "/contacts/optouts?channel=sms&limit=50");
console.log(page);

Python

import requests

resp = requests.get(
    "https://api.orbit.devotel.io/api/v1/contacts/optouts",
    params={"channel": "sms", "limit": 50},
    headers={"X-API-Key": "dv_live_sk_your_key_here"},
)
page = resp.json()
print(page["pagination"].get("cursor"))

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/contacts/optouts?channel=sms&limit=50", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/contacts/optouts?channel=sms&limit=50')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/contacts/optouts?channel=sms&limit=50');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
]);
echo curl_exec($ch);

Response

{
  "data": [
    {
      "id": "con_abc",
      "phone": "+14155552671",
      "email": null,
      "display_name": "Ada Lovelace",
      "channel_preferences": {
        "sms": { "opted_out": true }
      },
      "updated_at": "2026-05-22T10:30:00Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "total": 1,
    "cursor": "MjAyNi0wNS0yMlQxMDozMDowMC4wMDBafGNvbl9hYmM="
  },
  "meta": { "request_id": "req_abc123", "timestamp": "2026-05-24T12:00:00Z" }
}

When pagination.cursor is present, pass it back as ?cursor=<value> on the next call to page forward. The opted-out contact you created in step 1 appears here on its opted-out channels. Privacy note: opt-out records are tenant-owned consent data. Write the most specific reason you have (the inbound STOP keyword, the unsubscribe link, the support ticket) — that string is what your compliance export and audit trail carry.

Using the SDKs

Prefer the generic orbit.request() escape hatch here (the typed orbit.contacts.* helpers cover contact CRUD and segments; the opt-out surface uses the same envelope anyway). Create an opt-out with a real body and read the idempotent re-apply flag back — then list the tenant’s opt-outs through the same envelope: The create-and-list round trip above is already sampled inside the CodeGroup blocks of steps 1–2 in all six languages — through the SDK escape hatch in Node.js, plain requests in Python, and standard-library HTTP in Go, Ruby, and PHP, so the samples run without installing an SDK for the opt-out surface. The Python SDK is core-scope — it wraps the 8 core resources (messaging, voice, contacts, campaigns, verify, numbers) and reaches the opt-out endpoints through the generic client.request() escape hatch. See the Python SDK. Raw curl in the body of this page works identically. Full SDK index at SDK quickstart.

Canonical channels

Opt-outs are scoped to one of the 9 canonical contact channels. These are the channels surfaced in the contact-facing UI (preferences, opt-outs, consent records). The full platform supports more channels (push, web_chat, agent, video, fax) which are NOT consumer-facing in the same way. Consent state is stored per-channel on the contact’s channel_preferences object as a boolean — channel_preferences[<channel>].opted_out. There is no separate timestamp or channel-array column on the contact row; a channel is opted out when its opted_out flag is true, and opted in (or never set) when the flag is absent or false.

"channel_preferences": {
  "sms": { "opted_out": true },
  "email": { "opted_out": false }
}

The per-opt-out reason and the time each opt-out happened are recorded on the contact.opted_out / contact.opted_in audit-log entries (see Audit + observability), not on the contact row. Pull the audit log when you need a timestamped, reasoned trail for compliance evidence.

Channel	Notes
`sms`	SMS messages (10DLC, short codes, international long-code).
`whatsapp`	WhatsApp Business messages.
`email`	Transactional + marketing email.
`rcs`	RCS Business Messaging.
`viber`	Viber Business Messages.
`voice`	Outbound voice (calls + voicemail drops).
`messenger`	Facebook Messenger.
`instagram`	Instagram DMs.
`telegram`	Telegram bot messages.

The channels above are validated via Zod enum — any value not in the list is rejected at the request boundary with 422 VALIDATION_ERROR. Bulk-CSV imports normalize channel values case-insensitively and trim surrounding whitespace before enum validation.

List opt-outs

GET /api/v1/contacts/optouts

Scope: contacts:read. Cursor-paginated list of all opt-outs in the tenant. Query parameters

Name	Type	Notes
`limit`	integer (1–200)	Default 25. Values above 200 are clamped to 200.
`cursor`	string	Opaque base64url cursor from the previous response. Plaintext `<ts>	<id>` cursors are still accepted during the rollout window.
`channel`	enum	Optional filter — one of the 9 canonical channels.
`search`	string	Free-text match against the contact’s phone / email.

cURL

curl "https://api.orbit.devotel.io/api/v1/contacts/optouts?channel=sms&limit=50" \
  -H "X-API-Key: dv_live_sk_your_key_here"

200 OK

{
  "data": [
    {
      "id": "con_abc",
      "phone": "+14155552671",
      "email": null,
      "display_name": "Ada Lovelace",
      "channel_preferences": {
        "sms": { "opted_out": true }
      },
      "updated_at": "2026-05-22T10:30:00Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "total": 1,
    "cursor": "MjAyNi0wNS0yMlQxMDozMDowMC4wMDBafGNvbl9hYmM="
  },
  "meta": { "request_id": "req_abc123", "timestamp": "2026-05-24T12:00:00Z" }
}

Create opt-out

POST /api/v1/contacts/optouts

Scope: contacts:write. Role: owner / admin / developer. Opts a single contact out of a single channel by setting channel_preferences[<channel>].opted_out to true. Idempotent — re-applying an opt-out the contact already has returns 200 OK (instead of 201 Created) with already_opted_out: true, and does not write a duplicate audit entry or re-fire the webhook.

string

required

Contact identifier — either an E.164 phone (+14155552671) or a normalized email address. The platform resolves it to an existing contacts row or creates a stub row scoped to the tenant.

enum

required

One of the 9 canonical channels listed above.

string

required

Why the contact opted out — surfaced in audit logs and compliance exports. 1–500 chars.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/contacts/optouts" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "contact": "+14155552671",
    "channel": "sms",
    "reason": "Customer reply STOP"
  }'

201 Created Returns the updated contact row, including the merged channel_preferences, plus an already_opted_out flag (false on a genuine create, true on an idempotent re-apply).

{
  "data": {
    "id": "con_abc",
    "phone": "+14155552671",
    "email": null,
    "channel_preferences": {
      "sms": { "opted_out": true }
    },
    "already_opted_out": false,
    "updated_at": "2026-05-24T12:00:00Z"
  },
  "meta": { "request_id": "req_abc123", "timestamp": "2026-05-24T12:00:00Z" }
}

Also writes a contact.opted_out audit log with the channel + reason — that entry is where the reason and timestamp for this specific opt-out are recorded.

Bulk-CSV opt-out

POST /api/v1/contacts/optouts/bulk

Scope: contacts:write. Role: owner / admin / developer. Batched opt-out for the dashboard’s CSV-import wizard. The pre-fix path issued one HTTP request per row — a 1 000-row file = 1 000 round-trips. This endpoint accepts up to 500 rows per call; the dashboard chunks larger files client-side so a 50 000-row CSV uploads in ~100 batches instead of 50 000. Per-row isolation: A malformed row does NOT roll back the batch — each row is attempted independently, and the response carries {succeeded, skipped, failed, results[]} so the dashboard can surface actionable per-row errors. Partial success is preferable to silent total-loss. Counts: total always equals succeeded + skipped + failed. A row is counted as skipped (not succeeded) when the contact was already opted out of that channel — the import is idempotent, so re-uploading the same CSV reports those rows as skipped and does not write a duplicate audit entry or re-fire the webhook. Reconcile against total rather than assuming succeeded + failed === total.

array

required

Array of { contact, channel, reason } objects. 1–500 entries per request. Each channel is normalized (lowercased + trimmed) before enum validation.

curl -X POST "https://api.orbit.devotel.io/api/v1/contacts/optouts/bulk" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "rows": [
      { "contact": "+14155552671", "channel": "sms",      "reason": "CSV import" },
      { "contact": "+14155552672", "channel": "WhatsApp", "reason": "CSV import" },
      { "contact": "user@example.com", "channel": "email", "reason": "CSV import" }
    ]
  }'

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

const batch = await orbit.request("POST", "/contacts/optouts/bulk", {
  rows: [
    { contact: "+14155552671", channel: "sms",      reason: "CSV import" },
    { contact: "+14155552672", channel: "WhatsApp", reason: "CSV import" },
    { contact: "user@example.com", channel: "email", reason: "CSV import" },
  ],
});
const result = (batch as any).data;
console.log(`${result.succeeded} succeeded, ${result.skipped} skipped, ${result.failed} failed of ${result.total}`);

import requests

resp = requests.post(
    "https://api.orbit.devotel.io/api/v1/contacts/optouts/bulk",
    headers={
        "X-API-Key": "dv_live_sk_your_key_here",
        "Content-Type": "application/json",
    },
    json={
        "rows": [
            {"contact": "+14155552671", "channel": "sms", "reason": "CSV import"},
            {"contact": "+14155552672", "channel": "WhatsApp", "reason": "CSV import"},
            {"contact": "user@example.com", "channel": "email", "reason": "CSV import"},
        ],
    },
)
result = resp.json()["data"]
for row in result["results"]:
    if not row["ok"]:
        print(row["contact"], "->", row.get("error"))

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{
		"rows": [
			{ "contact": "+14155552671", "channel": "sms",      "reason": "CSV import" },
			{ "contact": "+14155552672", "channel": "WhatsApp", "reason": "CSV import" },
			{ "contact": "user@example.com", "channel": "email", "reason": "CSV import" }
		]
	}`)
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/contacts/optouts/bulk", bytes.NewReader(body))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
}

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/contacts/optouts/bulk')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  rows: [
    { contact: '+14155552671', channel: 'sms',      reason: 'CSV import' },
    { contact: '+14155552672', channel: 'WhatsApp', reason: 'CSV import' },
    { contact: 'user@example.com', channel: 'email', reason: 'CSV import' },
  ],
}.to_json

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
result = JSON.parse(res.body)['data']
puts "#{result['succeeded']} succeeded, #{result['skipped']} skipped, #{result['failed']} failed of #{result['total']}"

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/contacts/optouts/bulk');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  'rows' => [
    ['contact' => '+14155552671', 'channel' => 'sms', 'reason' => 'CSV import'],
    ['contact' => '+14155552672', 'channel' => 'WhatsApp', 'reason' => 'CSV import'],
    ['contact' => 'user@example.com', 'channel' => 'email', 'reason' => 'CSV import'],
  ],
]));
$batch = json_decode(curl_exec($ch), true);
foreach ($batch['data']['results'] as $row) {
  if (!$row['ok']) {
    echo $row['contact'] . ' -> ' . $row['error'] . "\n";
  }
}

207 Multi-Status

{
  "data": {
    "total": 3,
    "succeeded": 2,
    "skipped": 1,
    "failed": 0,
    "results": [
      { "contact": "+14155552671",    "channel": "sms",      "ok": true,  "status": "succeeded" },
      { "contact": "+14155552672",    "channel": "whatsapp", "ok": true,  "status": "skipped" },
      { "contact": "user@example.com","channel": "email",    "ok": true,  "status": "succeeded" }
    ]
  },
  "meta": { "request_id": "req_abc123", "timestamp": "2026-05-24T12:00:00Z" }
}

The endpoint takes a JSON rows array (each { contact, channel, reason } — one row of your CSV), so the samples above send a JSON body rather than a multipart upload; the dashboard handles the file-to-rows parsing before it calls this endpoint. Each result row carries a status — one of succeeded (newly opted out), skipped (already opted out; deduplicated), or failed. The ok boolean is retained for backwards compatibility: it is true for both succeeded and skipped, and false for failed. A failed row also carries an error message string.

Channel normalization. "SMS", "sms ", and "Sms" all map to the canonical sms. A value that isn’t one of the 9 canonical channels (even after normalization) fails request validation — the whole request returns 422 VALIDATION_ERROR rather than failing that row alone. Per-row isolation applies to processing failures (such as a contact that doesn’t yet exist), not to channel validation, so clean the channel column before upload. The dashboard previously substituted sms as a fallback for unknown channel strings — that silent fallback is now reserved for explicit operator confirmation in the wizard’s “review” step rather than the API.

Re-opt-in (delete opt-out)

DELETE /api/v1/contacts/optouts/{id}/{channel}

Scope: contacts:write. Role: owner / admin / developer. Removes the opt-out record for one channel on one contact. The contact becomes eligible for outbound sends on that channel again, subject to consent records — re-opt-in does not by itself create the affirmative consent some channels require (e.g. WhatsApp 24h window, RCS marketing). Path parameters:

id — the contact id (con_*)
channel — one of the 9 canonical channels

curl -X DELETE "https://api.orbit.devotel.io/api/v1/contacts/optouts/con_abc/sms" \
  -H "X-API-Key: dv_live_sk_your_key_here"

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

const updated = await orbit.request("DELETE", "/contacts/optouts/con_abc/sms");
console.log(updated);

import requests

resp = requests.delete(
    "https://api.orbit.devotel.io/api/v1/contacts/optouts/con_abc/sms",
    headers={"X-API-Key": "dv_live_sk_your_key_here"},
)
print(resp.json()["data"]["channel_preferences"])

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("DELETE", "https://api.orbit.devotel.io/api/v1/contacts/optouts/con_abc/sms", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/contacts/optouts/con_abc/sms')
req = Net::HTTP::Delete.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/contacts/optouts/con_abc/sms');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
]);
echo curl_exec($ch);

200 OK — returns the updated contact row. Also writes a contact.opted_in audit log with the channel.

Platform-scope only. This endpoint updates consent within Orbit — the contact’s channel_preferences, the suppression list, and (if you’ve connected one) the CRM/marketing tools consent is propagated to. It does not reach into the upstream SMS carrier network. For a US/CA toll-free number, a carrier can apply its own opt-out block independently of Orbit’s records; re-opting in here does not clear that carrier-level block. If a contact re-consents outside a messaging channel (a web form, email, or preference center) and still can’t be reached on SMS after this call, the block may be held at the carrier and needs to be resolved through your toll-free verification / carrier support channel, not through this API.

Export opt-outs

POST /api/v1/contacts/optouts/export

Scope: contacts:write (export is treated as a write because it produces an artifact and is rate-limited as such). Returns up to 10 000 opted-out contacts as JSON. Use for compliance evidence (e.g. carrier registration review, FCC complaint response).

enum

Optional filter — one of the 9 canonical channels. Omit to export all opt-outs.

curl -X POST "https://api.orbit.devotel.io/api/v1/contacts/optouts/export" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "sms" }'

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

const exported = await orbit.request("POST", "/contacts/optouts/export", {
  channel: "sms",
});
console.log((exported as any).data.total);

import requests

resp = requests.post(
    "https://api.orbit.devotel.io/api/v1/contacts/optouts/export",
    headers={
        "X-API-Key": "dv_live_sk_your_key_here",
        "Content-Type": "application/json",
    },
    json={"channel": "sms"},
)
print(resp.json()["data"]["total"])

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{ "channel": "sms" }`)
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/contacts/optouts/export", bytes.NewReader(body))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
}

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/contacts/optouts/export')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = { channel: 'sms' }.to_json

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/contacts/optouts/export');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['channel' => 'sms']));
echo curl_exec($ch);

200 OK

{
  "data": {
    "contacts": [
      {
        "id": "con_abc",
        "phone": "+14155552671",
        "email": null,
        "display_name": "Ada Lovelace",
        "channel_preferences": {
          "sms": { "opted_out": true }
        },
        "updated_at": "2026-05-22T10:30:00Z"
      }
    ],
    "total": 1
  },
  "meta": { "request_id": "req_abc123", "timestamp": "2026-05-24T12:00:00Z" }
}

For tenants with >10 000 opt-outs, use the paginated GET /optouts endpoint and iterate cursor.

The export returns current opt-out state per contact. For a timestamped, reasoned history of when each opt-out or opt-in occurred — the trail most compliance reviews ask for — read the audit log (contact.opted_out / contact.opted_in entries).

Errors

Status	`error.code`	Cause
`422`	`VALIDATION_ERROR`	`channel` not in canonical list, `contact` empty, `reason` missing/too long, or `rows` count exceeds 500.
`404`	`NOT_FOUND`	Contact id not found in the tenant (`DELETE` path).
`403`	`FORBIDDEN`	API key lacks `contacts:write` or caller role is `viewer`.
`429`	`RATE_LIMITED`	Per-API-key rate limit exceeded: bulk endpoints allow 10/minute, export endpoints allow 5/minute.

A validation failure returns the standard error envelope — a bad channel value is the most common trigger:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "channel must be one of: sms, whatsapp, email, rcs, viber, voice, messenger, instagram, telegram"
  },
  "meta": { "request_id": "req_abc123", "timestamp": "2026-05-24T12:00:00Z" }
}

Two properties matter for how you handle these errors:

Privacy. Validation errors on opt-out writes never echo the contact value back in the response — the identifier (a phone number or email) is consent data, and it is not smuggled into an error string your logs might ship elsewhere. Fix the field the message names.
Idempotency. A 422 means nothing was written — no partial opt-out, no audit entry. Retrying the corrected body is always safe, and retrying an already-opted-out contact is also safe (that path returns 200 OK with already_opted_out: true, never an error).

Audit + observability

Every state change writes an audit log:

contact.opted_out on POST /optouts and per row on POST /optouts/bulk.
contact.opted_in on DELETE /optouts/:id/:channel.

Each entry carries { channel, reason } (and bulk: true on bulk-imports). Per-row audit writes during a bulk import are best-effort — a single audit-write failure does NOT roll the batch back, but the warning is logged structurally.

Cross-channel STOP/START

A STOP reply received on one channel automatically fans out to a configured set of related channels via the inbound webhook handler (handleOptOut). See Compliance overview for the cross-channel fan-out matrix.

API Reference

All Endpoints

Opt-Outs API: per-contact channel consent and CSV sync

Opt-Outs API

Worked sequence: opt a contact out, then read the list back

1. Create the opt-out

2. Read the opt-outs list back

Using the SDKs

Canonical channels

List opt-outs

Create opt-out

Bulk-CSV opt-out

Re-opt-in (delete opt-out)

Export opt-outs

Errors

Audit + observability

Cross-channel STOP/START

See also

​Opt-Outs API

​Worked sequence: opt a contact out, then read the list back

​1. Create the opt-out

​2. Read the opt-outs list back

​Using the SDKs

​Canonical channels

​List opt-outs

​Create opt-out

​Bulk-CSV opt-out

​Re-opt-in (delete opt-out)

​Export opt-outs

​Errors

​Audit + observability

​Cross-channel STOP/START

​See also

Opt-Outs API

Worked sequence: opt a contact out, then read the list back

1. Create the opt-out

2. Read the opt-outs list back

Using the SDKs

Canonical channels

List opt-outs

Create opt-out

Bulk-CSV opt-out

Re-opt-in (delete opt-out)

Export opt-outs

Errors

Audit + observability

Cross-channel STOP/START

See also