API recipes: contact lifecycle

The contact-lifecycle cookbook. The canonical pages — Opt-outs API, Segments API, Frequency Caps API, Analytics API, Contacts API — document each endpoint; these recipes chain them into runnable loops: create, refresh, enrich, consent, read, decide. Every request sample ships as a six-language group — cURL, Node.js (TypeScript), Python, Go, Ruby, PHP, in that order, each dependency-free so it runs without an SDK installed — followed by the complete response envelope. All five loops stay on tenant-owned controls — the contact record, opt-outs, segments, and caps are your rules, set and enforced by your key. Base URL is https://api.orbit.devotel.io/api/v1 throughout; authenticate with X-API-Key and a test key (dv_test_sk_…) for the sandbox. The base lifecycle chain, run against the contact record itself: pin your source-of-truth id on create, refresh idempotently by that pin, write attributes and consent as recorded state, read back to verify, and scan for duplicates the pin could not prevent. This is the recipe form of Import, dedupe, and upsert contacts; the counters and endpoints agree with that page. Create with external_id — the pin that keeps one live row per customer:

curl -X POST https://api.orbit.devotel.io/api/v1/contacts \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "crm-8841",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "phone": "+14155552671",
    "email": "ada@example.com",
    "attributes": { "plan": "growth", "region": "emea" }
  }'

const res = await fetch('https://api.orbit.devotel.io/api/v1/contacts', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    external_id: 'crm-8841', // the pin: at most one live row per external_id
    first_name: 'Ada',
    last_name: 'Lovelace',
    phone: '+14155552671',
    email: 'ada@example.com',
    attributes: { plan: 'growth', region: 'emea' },
  }),
});
const { data: contact } = await res.json();
console.log(contact.id); // con_9f8a7b6c

import json, os
import requests

res = requests.post(
    "https://api.orbit.devotel.io/api/v1/contacts",
    headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
    json={
        "external_id": "crm-8841",  # the pin: one live row per external_id
        "first_name": "Ada",
        "last_name": "Lovelace",
        "phone": "+14155552671",
        "email": "ada@example.com",
        "attributes": {"plan": "growth", "region": "emea"},
    },
    timeout=30,
)
res.raise_for_status()
print(res.json()["data"]["id"])  # con_9f8a7b6c

package main

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

func main() {
	body := []byte(`{
	  "external_id": "crm-8841",
	  "first_name": "Ada",
	  "last_name": "Lovelace",
	  "phone": "+14155552671",
	  "email": "ada@example.com",
	  "attributes": { "plan": "growth", "region": "emea" }
	}`)
	req, err := http.NewRequest(http.MethodPost,
		"https://api.orbit.devotel.io/api/v1/contacts", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	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()
	fmt.Println(res.StatusCode) // 201
}

require "net/http"
require "json"
require "uri"

uri = URI("https://api.orbit.devotel.io/api/v1/contacts")
req = Net::HTTP::Post.new(uri)
req["X-API-Key"] = ENV.fetch("ORBIT_API_KEY")
req["Content-Type"] = "application/json"
req.body = JSON.generate(
  external_id: "crm-8841", # the pin: one live row per external_id
  first_name: "Ada",
  last_name: "Lovelace",
  phone: "+14155552671",
  email: "ada@example.com",
  attributes: { plan: "growth", region: "emea" }
)
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts JSON.parse(res.body).dig("data", "id") # con_9f8a7b6c

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/contacts');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . getenv('ORBIT_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'external_id' => 'crm-8841', // the pin: one live row per external_id
        'first_name' => 'Ada',
        'last_name' => 'Lovelace',
        'phone' => '+14155552671',
        'email' => 'ada@example.com',
        'attributes' => ['plan' => 'growth', 'region' => 'emea'],
    ]),
]);
$body = curl_exec($ch);
curl_close($ch);
echo json_decode($body, true)['data']['id']; // con_9f8a7b6c

201

{
  "data": {
    "id": "con_9f8a7b6c",
    "external_id": "crm-8841",
    "phone": "+14155552671",
    "email": "ada@example.com",
    "display_name": "Ada Lovelace",
    "attributes": { "plan": "growth", "region": "emea" },
    "created_at": "2026-05-22T10:30:00Z",
    "updated_at": "2026-05-22T10:30:00Z"
  },
  "meta": { "request_id": "req_life01", "timestamp": "2026-05-24T12:00:00Z" }
}

A resend of the same external_id resolves to this row and refreshes it — it never mints a second. Phone numbers normalize to E.164 server-side, and a contact needs at least one of phone or email at creation. Upsert refresh — the refresh path is the same write at scale: POST /contacts/bulk keys every row on external_id, so an existing pin updates the row instead of inserting a new one. Up to 10 000 rows per call; the response carries the same inserted / updated / skipped counters as the bulk import loop:

curl -X POST https://api.orbit.devotel.io/api/v1/contacts/bulk \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: run-2026-05-24-chunk-0" \
  -d '{
    "contacts": [
      { "external_id": "crm-8841", "attributes": { "plan": "scale" } },
      { "external_id": "crm-9902", "first_name": "Grace", "email": "grace@example.com" }
    ]
  }'

const res = await fetch('https://api.orbit.devotel.io/api/v1/contacts/bulk', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'run-2026-05-24-chunk-0', // crash-safe resume
  },
  body: JSON.stringify({
    contacts: [
      { external_id: 'crm-8841', attributes: { plan: 'scale' } },
      { external_id: 'crm-9902', first_name: 'Grace', email: 'grace@example.com' },
    ],
  }),
});
const { data } = await res.json();
console.log(data.inserted, data.updated, data.skipped); // 1 1 0

import os
import requests

res = requests.post(
    "https://api.orbit.devotel.io/api/v1/contacts/bulk",
    headers={
        "X-API-Key": os.environ["ORBIT_API_KEY"],
        "Idempotency-Key": "run-2026-05-24-chunk-0",
    },
    json={
        "contacts": [
            {"external_id": "crm-8841", "attributes": {"plan": "scale"}},
            {"external_id": "crm-9902", "first_name": "Grace", "email": "grace@example.com"},
        ]
    },
    timeout=60,
)
res.raise_for_status()
d = res.json()["data"]
print(d["inserted"], d["updated"], d["skipped"])  # 1 1 0

package main

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

func main() {
	body := []byte(`{
	  "contacts": [
	    { "external_id": "crm-8841", "attributes": { "plan": "scale" } },
	    { "external_id": "crm-9902", "first_name": "Grace", "email": "grace@example.com" }
	  ]
	}`)
	req, err := http.NewRequest(http.MethodPost,
		"https://api.orbit.devotel.io/api/v1/contacts/bulk", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Idempotency-Key", "run-2026-05-24-chunk-0")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	fmt.Println(res.StatusCode) // 200
}

require "net/http"
require "json"
require "uri"

uri = URI("https://api.orbit.devotel.io/api/v1/contacts/bulk")
req = Net::HTTP::Post.new(uri)
req["X-API-Key"] = ENV.fetch("ORBIT_API_KEY")
req["Content-Type"] = "application/json"
req["Idempotency-Key"] = "run-2026-05-24-chunk-0"
req.body = JSON.generate(contacts: [
  { external_id: "crm-8841", attributes: { plan: "scale" } },
  { external_id: "crm-9902", first_name: "Grace", email: "grace@example.com" },
])
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
d = JSON.parse(res.body).fetch("data")
puts [d["inserted"], d["updated"], d["skipped"]].join(" ") # 1 1 0

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/contacts/bulk');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . getenv('ORBIT_API_KEY'),
        'Content-Type: application/json',
        'Idempotency-Key: run-2026-05-24-chunk-0',
    ],
    CURLOPT_POSTFIELDS => json_encode(['contacts' => [
        ['external_id' => 'crm-8841', 'attributes' => ['plan' => 'scale']],
        ['external_id' => 'crm-9902', 'first_name' => 'Grace', 'email' => 'grace@example.com'],
    ]]),
]);
$body = curl_exec($ch);
curl_close($ch);
$d = json_decode($body, true)['data'];
echo $d['inserted'], ' ', $d['updated'], ' ', $d['skipped']; // 1 1 0

200

{
  "data": {
    "inserted": 1,
    "updated": 1,
    "skipped": 0,
    "import_job_id": "job_7f3a2c"
  },
  "meta": { "request_id": "req_life02", "timestamp": "2026-05-24T12:01:00Z" }
}

Sum inserted + updated + skipped per chunk and reconcile against your source row count; skipped rows download per job from GET /contacts/import-jobs/{id}/skipped.csv. A rerun of an identical batch moves rows into updated or skipped — never into a second live contact. Custom-field write — attribute and custom-field writes ride the contact update; import the scalar facts you personalize with, never derived values (segments, scores), which the CDP recomputes from events:

curl -X PATCH https://api.orbit.devotel.io/api/v1/contacts/con_9f8a7b6c \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "attributes": { "loyalty_tier": "gold" }, "tags": ["vip"] }'

const res = await fetch('https://api.orbit.devotel.io/api/v1/contacts/con_9f8a7b6c', {
  method: 'PATCH',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ attributes: { loyalty_tier: 'gold' }, tags: ['vip'] }),
});
const { data: contact } = await res.json();
console.log(contact.attributes.loyalty_tier); // gold

import os
import requests

res = requests.patch(
    "https://api.orbit.devotel.io/api/v1/contacts/con_9f8a7b6c",
    headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
    json={"attributes": {"loyalty_tier": "gold"}, "tags": ["vip"]},
    timeout=30,
)
res.raise_for_status()
print(res.json()["data"]["attributes"]["loyalty_tier"])  # gold

package main

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

func main() {
	body := []byte(`{ "attributes": { "loyalty_tier": "gold" }, "tags": ["vip"] }`)
	req, err := http.NewRequest(http.MethodPatch,
		"https://api.orbit.devotel.io/api/v1/contacts/con_9f8a7b6c", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	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()
	fmt.Println(res.StatusCode) // 200
}

require "net/http"
require "json"
require "uri"

uri = URI("https://api.orbit.devotel.io/api/v1/contacts/con_9f8a7b6c")
req = Net::HTTP::Patch.new(uri)
req["X-API-Key"] = ENV.fetch("ORBIT_API_KEY")
req["Content-Type"] = "application/json"
req.body = JSON.generate(attributes: { loyalty_tier: "gold" }, tags: ["vip"])
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts JSON.parse(res.body).dig("data", "attributes", "loyalty_tier") # gold

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/contacts/con_9f8a7b6c');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'PATCH',
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . getenv('ORBIT_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'attributes' => ['loyalty_tier' => 'gold'],
        'tags' => ['vip'],
    ]),
]);
$body = curl_exec($ch);
curl_close($ch);
echo json_decode($body, true)['data']['attributes']['loyalty_tier']; // gold

200

{
  "data": {
    "id": "con_9f8a7b6c",
    "external_id": "crm-8841",
    "attributes": { "plan": "scale", "region": "emea", "loyalty_tier": "gold" },
    "tags": ["vip"],
    "updated_at": "2026-05-24T12:02:00Z"
  },
  "meta": { "request_id": "req_life03", "timestamp": "2026-05-24T12:02:00Z" }
}

Attribute writes merge per key; keys you omit keep their stored value. Field definitions (types, display names) live in custom fields. Consent write — consent rides the contact as recorded state, written exactly as your source holds it (grant as grant, suppression as suppression; consent management):

curl -X POST https://api.orbit.devotel.io/api/v1/contacts/con_9f8a7b6c/consent/sms \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "granted": true, "basis": "explicit", "source": "checkout", "recorded_at": "2026-05-20T09:12:00Z" }'

const res = await fetch('https://api.orbit.devotel.io/api/v1/contacts/con_9f8a7b6c/consent/sms', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    granted: true,
    basis: 'explicit',
    source: 'checkout',
    recorded_at: '2026-05-20T09:12:00Z',
  }),
});
console.log(res.status); // 200

import os
import requests

res = requests.post(
    "https://api.orbit.devotel.io/api/v1/contacts/con_9f8a7b6c/consent/sms",
    headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
    json={
        "granted": True,
        "basis": "explicit",
        "source": "checkout",
        "recorded_at": "2026-05-20T09:12:00Z",
    },
    timeout=30,
)
res.raise_for_status()
print(res.json()["data"]["granted"])  # True

package main

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

func main() {
	body := []byte(`{
	  "granted": true,
	  "basis": "explicit",
	  "source": "checkout",
	  "recorded_at": "2026-05-20T09:12:00Z"
	}`)
	req, err := http.NewRequest(http.MethodPost,
		"https://api.orbit.devotel.io/api/v1/contacts/con_9f8a7b6c/consent/sms", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	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()
	fmt.Println(res.StatusCode) // 200
}

require "net/http"
require "json"
require "uri"

uri = URI("https://api.orbit.devotel.io/api/v1/contacts/con_9f8a7b6c/consent/sms")
req = Net::HTTP::Post.new(uri)
req["X-API-Key"] = ENV.fetch("ORBIT_API_KEY")
req["Content-Type"] = "application/json"
req.body = JSON.generate(
  granted: true,
  basis: "explicit",
  source: "checkout",
  recorded_at: "2026-05-20T09:12:00Z"
)
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts JSON.parse(res.body).dig("data", "granted") # true

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/contacts/con_9f8a7b6c/consent/sms');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . getenv('ORBIT_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'granted' => true,
        'basis' => 'explicit',
        'source' => 'checkout',
        'recorded_at' => '2026-05-20T09:12:00Z',
    ]),
]);
$body = curl_exec($ch);
curl_close($ch);
var_export(json_decode($body, true)['data']['granted']); // true

200

{
  "data": {
    "contact_id": "con_9f8a7b6c",
    "channel": "sms",
    "granted": true,
    "basis": "explicit",
    "source": "checkout",
    "recorded_at": "2026-05-20T09:12:00Z",
    "updated_at": "2026-05-24T12:03:00Z"
  },
  "meta": { "request_id": "req_life04", "timestamp": "2026-05-24T12:03:00Z" }
}

Writing consent never re-triggers a welcome or double opt-in for an already-consented contact; rows whose source cannot state a basis land unconsented and go through your capture flow once. Read-back — verify the row as stored before you cut over:

curl https://api.orbit.devotel.io/api/v1/contacts/con_9f8a7b6c \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

const res = await fetch('https://api.orbit.devotel.io/api/v1/contacts/con_9f8a7b6c', {
  headers: { 'X-API-Key': process.env.ORBIT_API_KEY! },
});
const { data: contact } = await res.json();
console.log(contact.external_id, contact.attributes.loyalty_tier); // crm-8841 gold

import os
import requests

res = requests.get(
    "https://api.orbit.devotel.io/api/v1/contacts/con_9f8a7b6c",
    headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
    timeout=30,
)
res.raise_for_status()
d = res.json()["data"]
print(d["external_id"], d["attributes"]["loyalty_tier"])  # crm-8841 gold

package main

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

func main() {
	req, err := http.NewRequest(http.MethodGet,
		"https://api.orbit.devotel.io/api/v1/contacts/con_9f8a7b6c", nil)
	if err != nil {
		panic(err)
	}
	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()
	fmt.Println(res.StatusCode) // 200
}

require "net/http"
require "json"
require "uri"

uri = URI("https://api.orbit.devotel.io/api/v1/contacts/con_9f8a7b6c")
req = Net::HTTP::Get.new(uri)
req["X-API-Key"] = ENV.fetch("ORBIT_API_KEY")
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
d = JSON.parse(res.body).fetch("data")
puts [d["external_id"], d.dig("attributes", "loyalty_tier")].join(" ") # crm-8841 gold

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/contacts/con_9f8a7b6c');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('ORBIT_API_KEY')],
]);
$body = curl_exec($ch);
curl_close($ch);
$d = json_decode($body, true)['data'];
echo $d['external_id'], ' ', $d['attributes']['loyalty_tier']; // crm-8841 gold

200

{
  "data": {
    "id": "con_9f8a7b6c",
    "external_id": "crm-8841",
    "phone": "+14155552671",
    "email": "ada@example.com",
    "display_name": "Ada Lovelace",
    "channel_preferences": { "sms": { "opted_out": false } },
    "attributes": { "plan": "scale", "region": "emea", "loyalty_tier": "gold" },
    "tags": ["vip"],
    "created_at": "2026-05-22T10:30:00Z",
    "updated_at": "2026-05-24T12:03:00Z"
  },
  "meta": { "request_id": "req_life05", "timestamp": "2026-05-24T12:04:00Z" }
}

Phone came back as E.164, the pin matches your source, attributes and consent carried over — the row is cut-over ready. Duplicate scan — the pin prevents new duplicates; scan for the estate you already have:

curl -X POST https://api.orbit.devotel.io/api/v1/contacts/duplicates/scan \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

const res = await fetch('https://api.orbit.devotel.io/api/v1/contacts/duplicates/scan', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.ORBIT_API_KEY! },
});
const { data } = await res.json();
console.log(data.clusters_found); // 1

import os
import requests

res = requests.post(
    "https://api.orbit.devotel.io/api/v1/contacts/duplicates/scan",
    headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
    timeout=60,
)
res.raise_for_status()
print(res.json()["data"]["clusters_found"])  # 1

package main

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

func main() {
	req, err := http.NewRequest(http.MethodPost,
		"https://api.orbit.devotel.io/api/v1/contacts/duplicates/scan", nil)
	if err != nil {
		panic(err)
	}
	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()
	fmt.Println(res.StatusCode) // 200
}

require "net/http"
require "json"
require "uri"

uri = URI("https://api.orbit.devotel.io/api/v1/contacts/duplicates/scan")
req = Net::HTTP::Post.new(uri)
req["X-API-Key"] = ENV.fetch("ORBIT_API_KEY")
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts JSON.parse(res.body).dig("data", "clusters_found") # 1

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/contacts/duplicates/scan');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('ORBIT_API_KEY')],
]);
$body = curl_exec($ch);
curl_close($ch);
echo json_decode($body, true)['data']['clusters_found']; // 1

200

{
  "data": {
    "clusters_found": 1,
    "clusters": [
      {
        "cluster_id": "dup_4d2e",
        "match_basis": "email",
        "contact_ids": ["con_9f8a7b6c", "con_2b7e1a"],
        "suggested_survivor": "con_9f8a7b6c"
      }
    ]
  },
  "meta": { "request_id": "req_life06", "timestamp": "2026-05-24T12:05:00Z" }
}

Page GET /contacts/duplicates for the full cluster list; identity resolution walkthrough covers reading them, and POST /contacts/merge combines a cluster into one survivor. Merge after import, never to hide a missing pin.

1. Opt-outs: bulk suppress → export → re-opt-in one channel

A suppression file arrives from support and you need the round trip: opt the contacts out in one batch, export the suppression list as compliance evidence, then restore the one contact who re-consents by phone or email. contact identifies the address-book row by phone (E.164) or email — pick the id off GET /contacts first if your file lists raw addresses. Bulk opt-out — up to 500 rows per call, per-row outcomes isolated:

curl -X POST https://api.orbit.devotel.io/api/v1/contacts/optouts/bulk \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rows": [
      { "contact": "+14155552671", "channel": "sms", "reason": "Support ticket #4481 — no more marketing SMS" },
      { "contact": "user@example.com", "channel": "email", "reason": "Replied stop-all to a nurture sequence" }
    ]
  }'

const res = await fetch('https://api.orbit.devotel.io/api/v1/contacts/optouts/bulk', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    rows: [
      { contact: '+14155552671', channel: 'sms', reason: 'Support ticket #4481 — no more marketing SMS' },
      { contact: 'user@example.com', channel: 'email', reason: 'Replied stop-all to a nurture sequence' },
    ],
  }),
});
const { data } = await res.json();
console.log(data.succeeded, data.skipped, data.failed); // 2 0 0

import os
import requests

res = requests.post(
    "https://api.orbit.devotel.io/api/v1/contacts/optouts/bulk",
    headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
    json={
        "rows": [
            {
                "contact": "+14155552671",
                "channel": "sms",
                "reason": "Support ticket #4481 — no more marketing SMS",
            },
            {
                "contact": "user@example.com",
                "channel": "email",
                "reason": "Replied stop-all to a nurture sequence",
            },
        ]
    },
    timeout=60,
)
res.raise_for_status()
d = res.json()["data"]
print(d["succeeded"], d["skipped"], d["failed"])  # 2 0 0

package main

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

func main() {
	body := []byte(`{
	  "rows": [
	    { "contact": "+14155552671", "channel": "sms" },
	    { "contact": "user@example.com", "channel": "email" }
	  ]
	}`)
	req, err := http.NewRequest(http.MethodPost,
		"https://api.orbit.devotel.io/api/v1/contacts/optouts/bulk", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	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()
	fmt.Println(res.StatusCode) // 207
}

require "net/http"
require "json"
require "uri"

uri = URI("https://api.orbit.devotel.io/api/v1/contacts/optouts/bulk")
req = Net::HTTP::Post.new(uri)
req["X-API-Key"] = ENV.fetch("ORBIT_API_KEY")
req["Content-Type"] = "application/json"
req.body = JSON.generate(rows: [
  { contact: "+14155552671", channel: "sms" },
  { contact: "user@example.com", channel: "email" },
])
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
d = JSON.parse(res.body).fetch("data")
puts [d["succeeded"], d["skipped"], d["failed"]].join(" ") # 2 0 0

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/contacts/optouts/bulk');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . getenv('ORBIT_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['rows' => [
        ['contact' => '+14155552671', 'channel' => 'sms'],
        ['contact' => 'user@example.com', 'channel' => 'email'],
    ]]),
]);
$body = curl_exec($ch);
curl_close($ch);
$d = json_decode($body, true)['data'];
echo $d['succeeded'], ' ', $d['skipped'], ' ', $d['failed']; // 2 0 0

207 Multi-Status — the full-envelope batch result. succeeded / skipped / failed count independently, so one unknown phone number never rolls the rest back:

207

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

A failed fifth row would show ok: false, status: "failed", and an actionable error string — clean the named rows and resend only them; skipped rows (already opted out) never double-stamp the consent trail. Export the suppression list — compliance evidence, up to 10 000 contacts:

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/contacts/optouts/export', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ channel: 'sms' }), // omit to export every channel
});
const { data } = await res.json();
console.log(data.total); // 1

import os
import requests

res = requests.post(
    "https://api.orbit.devotel.io/api/v1/contacts/optouts/export",
    headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
    json={"channel": "sms"},  # omit to export every channel
    timeout=60,
)
res.raise_for_status()
print(res.json()["data"]["total"])  # 1

package main

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

func main() {
	req, err := http.NewRequest(http.MethodPost,
		"https://api.orbit.devotel.io/api/v1/contacts/optouts/export",
		bytes.NewReader([]byte(`{ "channel": "sms" }`)))
	if err != nil {
		panic(err)
	}
	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()
	fmt.Println(res.StatusCode) // 200
}

require "net/http"
require "json"
require "uri"

uri = URI("https://api.orbit.devotel.io/api/v1/contacts/optouts/export")
req = Net::HTTP::Post.new(uri)
req["X-API-Key"] = ENV.fetch("ORBIT_API_KEY")
req["Content-Type"] = "application/json"
req.body = JSON.generate(channel: "sms") # omit to export every channel
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts JSON.parse(res.body).dig("data", "total") # 1

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

200

{
  "data": {
    "contacts": [
      {
        "id": "con_9f8a7b6c",
        "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_abc124", "timestamp": "2026-05-24T12:01:00Z" }
}

Omit channel to export every opt-out across channels. Past 10 000, page GET /contacts/optouts on its cursor instead — same rows, no cap. Re-opt-in the one contact who re-consents — delete the channel’s opt-out:

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/contacts/optouts/con_9f8a7b6c/sms', {
  method: 'DELETE',
  headers: { 'X-API-Key': process.env.ORBIT_API_KEY! },
});
console.log(res.status); // 200 — the updated contact row in the envelope

import os
import requests

res = requests.delete(
    "https://api.orbit.devotel.io/api/v1/contacts/optouts/con_9f8a7b6c/sms",
    headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
    timeout=30,
)
res.raise_for_status()
print(res.json()["data"]["channel_preferences"]["sms"]["opted_out"])  # False

package main

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

func main() {
	req, err := http.NewRequest(http.MethodDelete,
		"https://api.orbit.devotel.io/api/v1/contacts/optouts/con_9f8a7b6c/sms", nil)
	if err != nil {
		panic(err)
	}
	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()
	fmt.Println(res.StatusCode) // 200
}

require "net/http"
require "json"
require "uri"

uri = URI("https://api.orbit.devotel.io/api/v1/contacts/optouts/con_9f8a7b6c/sms")
req = Net::HTTP::Delete.new(uri)
req["X-API-Key"] = ENV.fetch("ORBIT_API_KEY")
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts JSON.parse(res.body).dig("data", "channel_preferences", "sms", "opted_out") # false

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/contacts/optouts/con_9f8a7b6c/sms');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'DELETE',
    CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('ORBIT_API_KEY')],
]);
$body = curl_exec($ch);
curl_close($ch);
var_export(json_decode($body, true)['data']['channel_preferences']['sms']['opted_out']); // false

200 returns the updated contact row. The contact is eligible again on that channel subject to consent records — the delete clears the suppression, and any affirmative-consent requirement (a WhatsApp 24-hour window, RCS marketing consent) still has to be satisfied by your own capture. The round trip closes: every enlisted row, plus one restored. Labelled error envelope — a channel outside the canonical nine (case-insensitive, whitespace-trimmed) fails the whole request before any row is processed:

422

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

Nothing was written on a validation failure, so retrying the corrected body is always safe; an already-opted-out single-row write resolves as 200 with already_opted_out: true, not an error. Canonical page: Opt-outs API. Envelope reference: API error handling by example.

2. Segments: autopilot → evaluate → materialize-lookalike → members

The AI-assisted audience loop: describe the audience, persist the suggestion as a real segment, force a re-evaluation when data moves, then grow it — preview a lookalike expansion and materialize it as a static segment you can page members out of. Autopilot from a description — suggest rules + live preview in one round-trip, nothing persisted:

curl -X POST https://api.orbit.devotel.io/api/v1/contacts/segments/autopilot \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "description": "customers who bought in the last 90 days but have not replied" }'

const res = await fetch('https://api.orbit.devotel.io/api/v1/contacts/segments/autopilot', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    description: 'customers who bought in the last 90 days but have not replied',
  }),
});
const { data } = await res.json();
console.log(data.preview.match_count); // 1842

import os
import requests

res = requests.post(
    "https://api.orbit.devotel.io/api/v1/contacts/segments/autopilot",
    headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
    json={"description": "customers who bought in the last 90 days but have not replied"},
    timeout=60,
)
res.raise_for_status()
print(res.json()["data"]["preview"]["match_count"])  # 1842

package main

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

func main() {
	body := []byte(`{ "description": "customers who bought in the last 90 days but have not replied" }`)
	req, err := http.NewRequest(http.MethodPost,
		"https://api.orbit.devotel.io/api/v1/contacts/segments/autopilot", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	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()
	fmt.Println(res.StatusCode) // 200
}

require "net/http"
require "json"
require "uri"

uri = URI("https://api.orbit.devotel.io/api/v1/contacts/segments/autopilot")
req = Net::HTTP::Post.new(uri)
req["X-API-Key"] = ENV.fetch("ORBIT_API_KEY")
req["Content-Type"] = "application/json"
req.body = JSON.generate(
  description: "customers who bought in the last 90 days but have not replied"
)
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts JSON.parse(res.body).dig("data", "preview", "match_count") # 1842

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/contacts/segments/autopilot');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . getenv('ORBIT_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'description' => 'customers who bought in the last 90 days but have not replied',
    ]),
]);
$body = curl_exec($ch);
curl_close($ch);
echo json_decode($body, true)['data']['preview']['match_count']; // 1842

200

{
  "data": {
    "operator": "and",
    "rules": [
      { "field": "last_purchase_at", "op": "in_last", "value": "90d" },
      { "field": "last_reply_at", "op": "is_unset" }
    ],
    "filters": {
      "op": "AND",
      "conditions": [
        { "field": "last_purchase_at", "op": "in_last", "value": "90d" },
        { "field": "last_reply_at", "op": "is_unset" }
      ]
    },
    "preview": { "match_count": 1842, "sample_contacts": [] },
    "llm_output_preview": "{\"operator\":\"and\",\"rules\":[...]"
  },
  "meta": { "request_id": "req_seg001", "timestamp": "2026-08-25T09:41:12Z" }
}

Persist the winner with POST /contacts/segments (the main cookbook’s task 15); membership materializes on create. Labelled error envelope — the model emits a rule the segmentation engine cannot validate, and the error names the field:

422

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "rules[0].field: 'account_balance_usd' is not a segmentable field",
    "status": 422,
    "details": { "field": "account_balance_usd" }
  },
  "meta": { "request_id": "req_seg002", "timestamp": "2026-08-25T09:41:13Z" }
}

Retry with a tighter description; a 503 means no AI provider is configured on the deployment — fall back to the manual builder. Evaluate on demand — after data (not rules) changed, rebuild membership now instead of waiting for the periodic refresh:

curl -X POST https://api.orbit.devotel.io/api/v1/contacts/segments/seg_9c2b1q/evaluate \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

const res = await fetch('https://api.orbit.devotel.io/api/v1/contacts/segments/seg_9c2b1q/evaluate', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.ORBIT_API_KEY! },
});
console.log(res.status); // 200 — evaluation result in the standard envelope

import os
import requests

res = requests.post(
    "https://api.orbit.devotel.io/api/v1/contacts/segments/seg_9c2b1q/evaluate",
    headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
    timeout=120,
)
res.raise_for_status()
print(res.json()["data"]["match_count"])

package main

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

func main() {
	req, err := http.NewRequest(http.MethodPost,
		"https://api.orbit.devotel.io/api/v1/contacts/segments/seg_9c2b1q/evaluate", nil)
	if err != nil {
		panic(err)
	}
	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()
	fmt.Println(res.StatusCode) // 200
}

require "net/http"
require "json"
require "uri"

uri = URI("https://api.orbit.devotel.io/api/v1/contacts/segments/seg_9c2b1q/evaluate")
req = Net::HTTP::Post.new(uri)
req["X-API-Key"] = ENV.fetch("ORBIT_API_KEY")
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts JSON.parse(res.body).dig("data", "match_count")

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/contacts/segments/seg_9c2b1q/evaluate');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('ORBIT_API_KEY')],
]);
$body = curl_exec($ch);
curl_close($ch);
echo json_decode($body, true)['data']['match_count'];

200 returns the evaluation result — the matched count, duration, and the membership diff — in the standard envelope. Materialize a lookalike audience — promote a preview into a new static segment (no rules, auto_refresh off — the k-NN snapshot is a point-in-time cohort the refresh scheduler never wipes):

curl -X POST https://api.orbit.devotel.io/api/v1/contacts/segments/seg_9c2b1q/materialize-lookalike \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "limit": 100, "sample_size": 50 }'

const res = await fetch('https://api.orbit.devotel.io/api/v1/contacts/segments/seg_9c2b1q/materialize-lookalike', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ limit: 100, sample_size: 50 }),
});
const { data } = await res.json();
console.log(data.materialized); // true

import os
import requests

res = requests.post(
    "https://api.orbit.devotel.io/api/v1/contacts/segments/seg_9c2b1q/materialize-lookalike",
    headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
    json={"limit": 100, "sample_size": 50},
    timeout=120,
)
res.raise_for_status()
print(res.json()["data"]["materialized"])  # True

package main

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

func main() {
	req, err := http.NewRequest(http.MethodPost,
		"https://api.orbit.devotel.io/api/v1/contacts/segments/seg_9c2b1q/materialize-lookalike",
		bytes.NewReader([]byte(`{ "limit": 100, "sample_size": 50 }`)))
	if err != nil {
		panic(err)
	}
	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()
	fmt.Println(res.StatusCode) // 201
}

require "net/http"
require "json"
require "uri"

uri = URI("https://api.orbit.devotel.io/api/v1/contacts/segments/seg_9c2b1q/materialize-lookalike")
req = Net::HTTP::Post.new(uri)
req["X-API-Key"] = ENV.fetch("ORBIT_API_KEY")
req["Content-Type"] = "application/json"
req.body = JSON.generate(limit: 100, sample_size: 50)
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts JSON.parse(res.body)["data"]["materialized"] # true

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/contacts/segments/seg_9c2b1q/materialize-lookalike');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . getenv('ORBIT_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['limit' => 100, 'sample_size' => 50]),
]);
$body = curl_exec($ch);
curl_close($ch);
var_export(json_decode($body, true)['data']['materialized']); // true

201 returns materialized: true plus the new segment — its id is a first-class segment you activate like any other. A preview with no candidates returns 200 with materialized: false and a reason, persisting nothing. Read members — page the materialized snapshot with the same cursor contract as any list:

curl "https://api.orbit.devotel.io/api/v1/contacts/segments/seg_9c2b1q/members?limit=100" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

let cursor: string | undefined;
do {
  const url = new URL('https://api.orbit.devotel.io/api/v1/contacts/segments/seg_9c2b1q/members');
  url.searchParams.set('limit', '100');
  if (cursor) url.searchParams.set('cursor', cursor);
  const res = await fetch(url, { headers: { 'X-API-Key': process.env.ORBIT_API_KEY! } });
  const { data, meta } = await res.json();
  console.log(data.contacts.length); // page size
  cursor = meta.pagination.has_more ? meta.pagination.cursor : undefined;
} while (cursor);

import os
import requests

cursor = None
while True:
    params = {"limit": 100}
    if cursor:
        params["cursor"] = cursor
    res = requests.get(
        "https://api.orbit.devotel.io/api/v1/contacts/segments/seg_9c2b1q/members",
        headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
        params=params,
        timeout=30,
    )
    res.raise_for_status()
    page = res.json()
    print(len(page["data"]["contacts"]))  # page size
    cursor = page["meta"]["pagination"]["cursor"] if page["meta"]["pagination"]["has_more"] else None
    if not cursor:
        break

package main

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

func main() {
	u, err := url.Parse("https://api.orbit.devotel.io/api/v1/contacts/segments/seg_9c2b1q/members")
	if err != nil {
		panic(err)
	}
	q := u.Query()
	q.Set("limit", "100")
	u.RawQuery = q.Encode()
	req, err := http.NewRequest(http.MethodGet, u.String(), nil)
	if err != nil {
		panic(err)
	}
	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()
	fmt.Println(res.StatusCode) // 200
}

require "net/http"
require "json"
require "uri"

uri = URI("https://api.orbit.devotel.io/api/v1/contacts/segments/seg_9c2b1q/members?limit=100")
loop do
  req = Net::HTTP::Get.new(uri)
  req["X-API-Key"] = ENV.fetch("ORBIT_API_KEY")
  res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
  page = JSON.parse(res.body)
  puts page["data"]["contacts"].length # page size
  break unless page.dig("meta", "pagination", "has_more")
  uri = URI("https://api.orbit.devotel.io/api/v1/contacts/segments/seg_9c2b1q/members?limit=100&cursor=#{page.dig('meta', 'pagination', 'cursor')}")
end

<?php
$cursor = null;
do {
    $url = 'https://api.orbit.devotel.io/api/v1/contacts/segments/seg_9c2b1q/members?limit=100';
    if ($cursor) {
        $url .= '&cursor=' . rawurlencode($cursor);
    }
    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('ORBIT_API_KEY')],
    ]);
    $body = curl_exec($ch);
    curl_close($ch);
    $page = json_decode($body, true);
    echo count($page['data']['contacts']), "\n"; // page size
    $cursor = $page['meta']['pagination']['has_more'] ? $page['meta']['pagination']['cursor'] : null;
} while ($cursor);

Pass meta.pagination.cursor while has_more is true. The members list reads the last-materialized snapshot — call evaluate (above) first if you need the very latest audience. Canonical pages: Segments API (AI surfaces), Contacts API (saved-segment CRUD + membership).

3. Frequency caps: read the rules behind a send decision

Caps are the tenant’s rolling-window limits on how often one contact can be messaged. Two reads serve the “what applies to this contact?” question: the per-contact rules read, then the live per-recipient usage you branch a send decision on. Rule writes ride PATCH /frequency-caps/:id; reads ride GET /contacts/:id/frequency-caps (rules) and GET /contacts/:id/cap-status (live usage) — the decision loop below uses the rule IDs from the first read to target back-off per category. Read the rules that apply to the contact — flat plus grouped by channel, globals separated:

curl https://api.orbit.devotel.io/api/v1/contacts/con_9f8a7b6c/frequency-caps \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

const res = await fetch('https://api.orbit.devotel.io/api/v1/contacts/con_9f8a7b6c/frequency-caps', {
  headers: { 'X-API-Key': process.env.ORBIT_API_KEY! },
});
const { data } = await res.json();
console.log(data.caps.map((c) => c.id)); // ['cap_01JYMK']

import os
import requests

res = requests.get(
    "https://api.orbit.devotel.io/api/v1/contacts/con_9f8a7b6c/frequency-caps",
    headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
    timeout=30,
)
res.raise_for_status()
print([c["id"] for c in res.json()["data"]["caps"]])  # ['cap_01JYMK']

package main

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

func main() {
	req, err := http.NewRequest(http.MethodGet,
		"https://api.orbit.devotel.io/api/v1/contacts/con_9f8a7b6c/frequency-caps", nil)
	if err != nil {
		panic(err)
	}
	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()
	fmt.Println(res.StatusCode) // 200
}

require "net/http"
require "json"
require "uri"

uri = URI("https://api.orbit.devotel.io/api/v1/contacts/con_9f8a7b6c/frequency-caps")
req = Net::HTTP::Get.new(uri)
req["X-API-Key"] = ENV.fetch("ORBIT_API_KEY")
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts JSON.parse(res.body).dig("data", "caps").map { |c| c["id"] }.join(", ") # cap_01JYMK

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/contacts/con_9f8a7b6c/frequency-caps');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('ORBIT_API_KEY')],
]);
$body = curl_exec($ch);
curl_close($ch);
echo implode(', ', array_column(json_decode($body, true)['data']['caps'], 'id')); // cap_01JYMK

200

{
  "data": {
    "contact_id": "con_9f8a7b6c",
    "caps": [
      {
        "id": "cap_01JYMK",
        "organization_id": "org_01HX",
        "channel": "sms",
        "scope": "channel",
        "window_seconds": 86400,
        "max_count": 3,
        "applies_to_categories": ["marketing"],
        "enabled": true,
        "created_at": "2026-05-01T00:00:00Z",
        "updated_at": "2026-05-01T00:00:00Z"
      }
    ],
    "grouped_by_channel": {
      "sms": [
        {
          "id": "cap_01JYMK",
          "organization_id": "org_01HX",
          "channel": "sms",
          "scope": "channel",
          "window_seconds": 86400,
          "max_count": 3,
          "applies_to_categories": ["marketing"],
          "enabled": true,
          "created_at": "2026-05-01T00:00:00Z",
          "updated_at": "2026-05-01T00:00:00Z"
        }
      ]
    },
    "global_caps": []
  },
  "meta": { "request_id": "req_cap001", "timestamp": "2026-08-25T10:00:00Z" }
}

Read live usage for the “can I send?” decision — snapshot across every channel, with the consent state folded in:

curl https://api.orbit.devotel.io/api/v1/contacts/con_9f8a7b6c/cap-status \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

const res = await fetch('https://api.orbit.devotel.io/api/v1/contacts/con_9f8a7b6c/cap-status', {
  headers: { 'X-API-Key': process.env.ORBIT_API_KEY! },
});
const { data: status } = await res.json();
console.log(status.channels.sms.sends_remaining); // slots left today

import os
import requests

res = requests.get(
    "https://api.orbit.devotel.io/api/v1/contacts/con_9f8a7b6c/cap-status",
    headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
    timeout=30,
)
res.raise_for_status()
print(res.json()["data"]["channels"]["sms"]["sends_remaining"])  # slots left today

package main

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

func main() {
	req, err := http.NewRequest(http.MethodGet,
		"https://api.orbit.devotel.io/api/v1/contacts/con_9f8a7b6c/cap-status", nil)
	if err != nil {
		panic(err)
	}
	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()
	fmt.Println(res.StatusCode) // 200
}

require "net/http"
require "json"
require "uri"

uri = URI("https://api.orbit.devotel.io/api/v1/contacts/con_9f8a7b6c/cap-status")
req = Net::HTTP::Get.new(uri)
req["X-API-Key"] = ENV.fetch("ORBIT_API_KEY")
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts JSON.parse(res.body).dig("data", "channels", "sms", "sends_remaining") # slots left today

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/contacts/con_9f8a7b6c/cap-status');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('ORBIT_API_KEY')],
]);
$body = curl_exec($ch);
curl_close($ch);
echo json_decode($body, true)['data']['channels']['sms']['sends_remaining']; // slots left today

Per cap that applies, the response carries max_count / current_count / sends_remaining and (once slots are exhausted) the next_slot_at ISO timestamp, plus the channel’s consent state — one read answers both “how many left” and “may we send at all”. Update a rule — widen the marketing SMS cap; rule writes are owner/admin/developer with frequency-caps:write:

curl -X PATCH https://api.orbit.devotel.io/api/v1/frequency-caps/cap_01JYMK \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "max_count": 5, "window_seconds": 86400 }'

const res = await fetch('https://api.orbit.devotel.io/api/v1/frequency-caps/cap_01JYMK', {
  method: 'PATCH',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ max_count: 5, window_seconds: 86400 }),
});
console.log(res.status); // 200 — updated rule in the envelope

import os
import requests

res = requests.patch(
    "https://api.orbit.devotel.io/api/v1/frequency-caps/cap_01JYMK",
    headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
    json={"max_count": 5, "window_seconds": 86400},
    timeout=30,
)
res.raise_for_status()
print(res.json()["data"]["max_count"])  # 5

package main

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

func main() {
	req, err := http.NewRequest(http.MethodPatch,
		"https://api.orbit.devotel.io/api/v1/frequency-caps/cap_01JYMK",
		bytes.NewReader([]byte(`{ "max_count": 5, "window_seconds": 86400 }`)))
	if err != nil {
		panic(err)
	}
	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()
	fmt.Println(res.StatusCode) // 200
}

require "net/http"
require "json"
require "uri"

uri = URI("https://api.orbit.devotel.io/api/v1/frequency-caps/cap_01JYMK")
req = Net::HTTP::Patch.new(uri)
req["X-API-Key"] = ENV.fetch("ORBIT_API_KEY")
req["Content-Type"] = "application/json"
req.body = JSON.generate(max_count: 5, window_seconds: 86400)
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts JSON.parse(res.body).dig("data", "max_count") # 5

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/frequency-caps/cap_01JYMK');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'PATCH',
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . getenv('ORBIT_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['max_count' => 5, 'window_seconds' => 86400]),
]);
$body = curl_exec($ch);
curl_close($ch);
echo json_decode($body, true)['data']['max_count']; // 5

Decide in your send gate:

curl https://api.orbit.devotel.io/api/v1/contacts/con_9f8a7b6c/cap-status \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

const { data: status } = await orbit.request(
  'GET',
  '/api/v1/contacts/con_9f8a7b6c/cap-status',
);
// Walk status channels: zero sends_remaining (or opted_out) → hold or
// skip the recipient; positive → the cap admits the send. The 429 loop
// below is the fallback when the snapshot went stale before dispatch.

import os
import requests

status = requests.get(
    "https://api.orbit.devotel.io/api/v1/contacts/con_9f8a7b6c/cap-status",
    headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
    timeout=30,
).json()["data"]
# Walk status channels: zero sends_remaining (or opted_out) → hold or
# skip the recipient; positive → the cap admits the send. The 429 loop
# below is the fallback when the snapshot went stale before dispatch.

package main

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

func main() {
	req, err := http.NewRequest(http.MethodGet,
		"https://api.orbit.devotel.io/api/v1/contacts/con_9f8a7b6c/cap-status", nil)
	if err != nil {
		panic(err)
	}
	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()
	// Decode the envelope and walk the status channels: zero
	// sends_remaining (or opted_out) → hold or skip the recipient;
	// positive → the cap admits the send. The 429 loop below is the
	// fallback when the snapshot went stale before dispatch.
	fmt.Println(res.StatusCode)
}

require "net/http"
require "json"
require "uri"

uri = URI("https://api.orbit.devotel.io/api/v1/contacts/con_9f8a7b6c/cap-status")
req = Net::HTTP::Get.new(uri)
req["X-API-Key"] = ENV.fetch("ORBIT_API_KEY")
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
status = JSON.parse(res.body).fetch("data")
# Walk status channels: zero sends_remaining (or opted_out) → hold or
# skip the recipient; positive → the cap admits the send. The 429 loop
# below is the fallback when the snapshot went stale before dispatch.
puts status.keys.join(", ")

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/contacts/con_9f8a7b6c/cap-status');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('ORBIT_API_KEY')],
]);
$status = json_decode(curl_exec($ch), true)['data'];
curl_close($ch);
// Walk status channels: zero sends_remaining (or opted_out) → hold or
// skip the recipient; positive → the cap admits the send. The 429 loop
// below is the fallback when the snapshot went stale before dispatch.
var_export(array_keys($status));

Labelled error envelope — a send that would exceed the cap:

429

{
  "error": {
    "code": "FREQUENCY_CAP_EXCEEDED",
    "message": "Frequency cap exceeded for sms (3 per day per contact). Try again after the window resets."
  },
  "meta": { "request_id": "req_cap002", "timestamp": "2026-08-25T10:00:01Z" }
}

Defer that recipient and continue the batch (the main cookbook’s error table has the retriable-vs-terminal split). Caps are exclusion enforcement, not a block on your whole send plan — suppression lists and opt-outs gate in parallel (Opt-outs round trip above). Canonical pages: Frequency Caps API, Contacts API.

4. Usage: fetch a day of metering for guardrails

The metering guardrail read: the home-overview usage chart’s same daily timeline, pulled for a one-day window so your own guardrails (budget dashboards, spend alerts, anomaly heuristics) sit on the numbers the platform charts. Read-only; an explicit start_date / end_date pair takes precedence over the days trailing window.

curl "https://api.orbit.devotel.io/api/v1/stats/usage?start_date=2026-08-20&end_date=2026-08-20" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

const res = await fetch(
  'https://api.orbit.devotel.io/api/v1/stats/usage?start_date=2026-08-20&end_date=2026-08-20',
  { headers: { 'X-API-Key': process.env.ORBIT_API_KEY! } },
);
const { data } = await res.json();
console.log(data.totals.delivery_rate); // 98.61

import os
import requests

res = requests.get(
    "https://api.orbit.devotel.io/api/v1/stats/usage",
    headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
    params={"start_date": "2026-08-20", "end_date": "2026-08-20"},
    timeout=30,
)
res.raise_for_status()
print(res.json()["data"]["totals"]["delivery_rate"])  # 98.61

package main

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

func main() {
	req, err := http.NewRequest(http.MethodGet,
		"https://api.orbit.devotel.io/api/v1/stats/usage?start_date=2026-08-20&end_date=2026-08-20", nil)
	if err != nil {
		panic(err)
	}
	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()
	fmt.Println(res.StatusCode) // 200
}

require "net/http"
require "json"
require "uri"

uri = URI("https://api.orbit.devotel.io/api/v1/stats/usage?start_date=2026-08-20&end_date=2026-08-20")
req = Net::HTTP::Get.new(uri)
req["X-API-Key"] = ENV.fetch("ORBIT_API_KEY")
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts JSON.parse(res.body).dig("data", "totals", "delivery_rate") # 98.61

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/stats/usage?start_date=2026-08-20&end_date=2026-08-20');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('ORBIT_API_KEY')],
]);
$body = curl_exec($ch);
curl_close($ch);
echo json_decode($body, true)['data']['totals']['delivery_rate']; // 98.61

200

{
  "data": {
    "totals": {
      "total_sent": 2450,
      "total_delivered": 2416,
      "total_failed": 34,
      "total_read": 1720,
      "delivery_rate": 98.61,
      "read_rate": 71.19,
      "avg_delivery_time_ms": 1795
    },
    "time_series": [
      {
        "period": "2026-08-20T00:00:00.000Z",
        "period_date": "2026-08-20",
        "total_sent": 2450,
        "total_delivered": 2416,
        "total_failed": 34,
        "total_read": 1720,
        "delivery_rate": 98.61,
        "read_rate": 71.19,
        "avg_delivery_time_ms": 1795
      }
    ]
  },
  "meta": { "request_id": "req_usg001", "timestamp": "2026-08-21T09:00:00Z" }
}

Feed totals into a budget check before you queue a batch, or row-by-row into a daily anomaly heuristic. For spend-shaped guardrails instead of volume, the billing surface’s spend series and burn rate (the main cookbook’s task 22) price the same window. Labelled error envelope — an explicit pair with a missing end:

400

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid query parameters",
    "status": 400,
    "details": { "issues": ["start_date and end_date must be provided together"] }
  },
  "meta": { "request_id": "req_usg002", "timestamp": "2026-08-21T09:00:01Z" }
}

A lone start_date (or end_date) is a 400 — the pair refines together, and the details issues list names the fix instead of silently falling back to the trailing days window. Canonical page: Analytics API → per-day usage timeline. Finer-grained metering (rate a batch, credit notes): Usage metering.

WhatsApp

Developer console

Contact center

Guides

Admin

Messaging Controls

Audience & Support Tools

API recipes: contact lifecycle — opt-outs, segments, frequency caps

API recipes: contact lifecycle

1. Opt-outs: bulk suppress → export → re-opt-in one channel

2. Segments: autopilot → evaluate → materialize-lookalike → members

3. Frequency caps: read the rules behind a send decision

4. Usage: fetch a day of metering for guardrails

See also

​API recipes: contact lifecycle

​5. The contact record: create → upsert → enrich → consent → read back → dedupe

​1. Opt-outs: bulk suppress → export → re-opt-in one channel

​2. Segments: autopilot → evaluate → materialize-lookalike → members

​3. Frequency caps: read the rules behind a send decision

​4. Usage: fetch a day of metering for guardrails

​See also

API recipes: contact lifecycle

5. The contact record: create → upsert → enrich → consent → read back → dedupe

1. Opt-outs: bulk suppress → export → re-opt-in one channel

2. Segments: autopilot → evaluate → materialize-lookalike → members

3. Frequency caps: read the rules behind a send decision

4. Usage: fetch a day of metering for guardrails

See also