How to read a worked sample

Every endpoint guide in these docs ships a worked sample — a request you can copy verbatim, and the exact response envelope the platform returns. This index shows you how to turn a sample into a running call, and where the rest of the worked examples live.

Reading an endpoint’s sample

A worked sample is a complete request: method, path, headers, and body. Nothing in it is a placeholder except your API key — so translating the curl block to your language is mechanical.

Copy the request as written. Base URL is always https://api.orbit.devotel.io/api/v1; substitute a Test key (dv_test_sk_…) for X-API-Key and the sample runs against the sandbox.
Translate it per language. The headers and JSON body carry over unchanged — only the HTTP client differs.

cURL

curl -X POST https://api.orbit.devotel.io/api/v1/messages/sms \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+14155552671", "body": "Hello from Orbit." }'

fetch

const res = await fetch("https://api.orbit.devotel.io/api/v1/messages/sms", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.ORBIT_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ to: "+14155552671", body: "Hello from Orbit." }),
});
const { data } = await res.json(); // same envelope the sample documents

The Node SDK collapses the same call to one line — orbit.messages.send({ channel: "sms", to, body }) — and returns the same data the raw response carries. Pick whichever you read faster; the envelope below is identical either way.

Typed SDK tab, or raw fetch — one canonical pattern

Every endpoint page renders the same slice of languages: cURL, Node.js (TypeScript), and for the most-used operations Python, Go, Ruby, and PHP. Which client each tab shows is one decision, made once — here is the whole rule.

Why the non-published-language tabs use raw HTTP

The SDK coverage matrix tells you which SDKs are on a registry today. Only Node and Web (npm) and Python (PyPI) install from a package manager — Go, Ruby, PHP, Java, and .NET live in workspace source, unpublished. A tab for a language whose SDK has no published package renders the raw HTTP call (plain fetch, requests, net/http, curl_exec) against the documented path, so the sample compiles and runs the day you paste it. This is deliberate, not a gap: an import that 404s on a registry is a worse sample than no import at all.

When the Node tab switches to the typed SDK

The Node SDK is feature-complete and published, so the Node tab has a real choice. Use Typed SDK whenever a typed method for the route exists — which today means one of the six core resources: orbit.messages, orbit.contacts, orbit.campaigns, orbit.verify, orbit.voice, and orbit.webhooks (check the coverage matrix before writing). Fall back to raw fetch() only for a route no typed method covers — and when you do, keep the escape-hatch shape (import { Orbit } + constructor, then the raw call) so a reader can move the call inside a typed client later without restructuring auth.

Never mix. Every raw-HTTP block on an endpoint page sets its own X-API-Key header explicitly, and every typed block constructs new Orbit({ apiKey: process.env.ORBIT_API_KEY }). Pick one per block — do not construct the client and then hand-fetch next to it, and do not import the SDK for a raw HTTP call.

Migrating a sample from fetch to the typed SDK

The swap is verbatim — same body, same envelope; only the transport changes. Messaging send, before:

fetch (before)

const res = await fetch("https://api.orbit.devotel.io/api/v1/messages/sms", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.ORBIT_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ to: "+14155552671", body: "Your pickup is ready." }),
});
const { data } = await res.json();

Typed, after — the client handles the header, JSON body, retries, and the Idempotency-Key on every non-GET:

Node SDK (after)

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

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

const { data } = await orbit.messages.send({
  channel: "sms",
  to: "+14155552671",
  body: "Your pickup is ready.",
});

Same { data, meta } envelope comes back — see the four envelope shapes for what you branch on either way.

The snippet template contributors follow

New samples and doc overlays copy this shape exactly — the readers’ tabs stay uniform:

Snippet template — escape-hatch signature

// 1. Typed method exists → construct once in the file (or inline for a
//    single snippet) and call it.
import { Orbit } from "@devotel-orbit/node";

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

// ... one typed call per request ...

// 2. Unpublished-language tab, or a route with no typed method → raw HTTP,
//    complete request (method, path, headers, body), key via the env var,
//    envelope destructured the same way.
const res = await fetch("https://api.orbit.devotel.io/api/v1/<route>", {
  method: "POST",
  headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
  body: JSON.stringify({ /* body */ }),
});

Two rules hold on every endpoint page: never a raw-HTTP block without an explicit X-API-Key, and never an SDK import on a block that only uses fetch. The SDK index is the source of truth for “is the language published and does the route have a typed method” — if the matrix says no, the tab says raw fetch.

The four envelope shapes

Every response the platform returns is one of four shapes. Recognize the shape at a glance and you know how to read the body:

Success envelope — { data, meta }, HTTP 2xx. The resource (or a resource id) sits under data; meta carries the request correlation id:

{ "data": { "id": "msg_9e8d7c6b5a4f3021e5d6c7b8a1b2c3d4", "status": "queued" }, "meta": { "request_id": "req_abc123" } }

Success with pagination — the same { data, meta }, with meta.pagination telling you how to fetch the next page:

{ "data": [ ... ], "meta": { "pagination": { "cursor": "cur_msg_abc123", "has_more": true, "total": 1542 } } }

207 Multi-Status batch envelope — bulk endpoints answer 207 on partial success and give you one row per recipient; branch on status per row, never blanket-retry the batch:

{ "data": { "results": [ { "recipient": "+14155552671", "status": "sent", "verification_id": "vrf_3f1c0b…" }, { "recipient": "+1234", "status": "failed", "error": { "code": "INVALID_PHONE_NUMBER", "message": "…" } } ] } }

Canonical sample: Bulk sends (207 and all) and the Verify API.

Error envelope — { error, meta } on any non-2xx status. Branch on the stable error.code, never on the human-readable error.message:

{ "error": { "code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry after 4 seconds.", "status": 429, "retry_after": 4 }, "meta": { "request_id": "req_xyz789" } }

Canonical sample: API error handling by example.

Branching on a 207 in code

Bulk sends — POST /messages/batch, POST /verify/bulk — answer with one result row per recipient. Treat the HTTP status as a summary and handle each row by its own status:

Idempotency on the batch call. POST endpoints that create resources accept an Idempotency-Key header; the SDK mints one per call, raw fetch must set it explicitly. A retry with the same key returns the original envelope — no duplicate sends, no second charge. The full contract lives in Idempotency and safe retries.

Node

const res = await fetch("https://api.orbit.devotel.io/api/v1/verify/bulk", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.ORBIT_API_KEY!,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(), // set explicitly over raw HTTP
  },
  body: JSON.stringify({ channel: "sms", recipients: ["+14155552671", "not-a-number"] }),
});

const { data } = await res.json();

if (res.status === 207) {
  // Partial success — act row-by-row; never blanket-retry the batch.
  for (const row of data.results) {
    if (row.status === "sent") {
      remember(row.recipient, row.verification_id);
    } else {
      // row.error.code names the gate; fix the cause, not the batch.
      logFailure(row.recipient, row.error.code);
    }
  }
}

Python

import uuid
from orbit_sdk import OrbitClient

client = OrbitClient.from_env()

res = client.request(
    "POST",
    "/api/v1/verify/bulk",
    json_body={"channel": "sms", "recipients": ["+14155552671", "not-a-number"]},
    headers={"Idempotency-Key": str(uuid.uuid4())},  # one key per attempt
)

for row in res["data"]["results"]:
    if row["status"] == "sent":
        remember(row["recipient"], row["verification_id"])
    else:
        # row["error"]["code"] names the gate; fix the cause, not the batch.
        log_failure(row["recipient"], row["error"]["code"])

The full 207/400/503 response matrix with its handling table: Bulk sends (207 and all).

Where the worked examples live

Samples are spread across the docs deliberately — each sits next to the endpoint it exercises. This page is the index:

REST API recipes — sixteen task-by-task worked samples (messaging, voice, campaigns, CDP, webhook round trips), each pairing curl with Node or Python.
API recipes: operations endpoints — the operational surfaces as six runnable loops: the Verify second-officer approvals round trip, a cascade policy previewed through route-preview before smart-send arms it, the message-history q= search DSL over the API, the SMPP no-delivery receipt window on a termination rule, the brand-identity trust posture read, and a risk-score pre-send gate.
API recipes: contact lifecycle — opt-outs bulk export/re-opt-in round trip, AI segment autopilot through a materialized lookalike audience, per-contact frequency-cap rules behind the send decision, and a day of usage for metering guardrails.
Error handling by example — three worked failures with the fix in code.
Endpoint worked samples — each endpoint family page carries a curated sample block (messaging, campaigns, voice, and the rest).
Starter examples and the Quickstart — five runnable repos and the end-to-end first call, when a single request/response isn’t enough.

Pagination in one paragraph

List endpoints paginate one of two ways, and the response tells you which: most endpoints are cursor-based — read meta.pagination.cursor when has_more is true and pass it back as ?cursor=…; a smaller set of dashboard-oriented families is offset-based — the page metadata (items, total, limit, offset) lives inside the data envelope instead. The shape of the response you’re holding identifies the style.

The cursor loop in code

Node

let cursor: string | undefined;
do {
  const page = await orbit.messages.list({ limit: 100, cursor });
  for (const message of page.data) {
    // consume one message per iteration
  }
  cursor = page.meta.pagination.has_more
    ? page.meta.pagination.cursor
    : undefined;
} while (cursor);

Python

import requests

cursor = None
while True:
    params = {"limit": 100}
    if cursor:
        params["cursor"] = cursor
    page = requests.get(
        "https://api.orbit.devotel.io/api/v1/messages",
        headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
        params=params,
    ).json()

    for message in page["data"]:
        # consume one message per iteration
        pass
    pagination = page["meta"]["pagination"]
    if not pagination.get("has_more"):
        break
    cursor = pagination["cursor"]

The full contract — both loops with both styles, per-endpoint caps, and which families are offset-based: Pagination.

WhatsApp

Developer console

Contact center

Guides

Messaging Controls

Audience & Support Tools

How to read a worked sample

How to read a worked sample

Reading an endpoint’s sample

Typed SDK tab, or raw fetch — one canonical pattern

Why the non-published-language tabs use raw HTTP

When the Node tab switches to the typed SDK

Migrating a sample from fetch to the typed SDK

The snippet template contributors follow

The four envelope shapes

Branching on a 207 in code

Where the worked examples live

The cursor loop in code

​How to read a worked sample

​Reading an endpoint’s sample

​Typed SDK tab, or raw fetch — one canonical pattern

​Why the non-published-language tabs use raw HTTP

​When the Node tab switches to the typed SDK

​Migrating a sample from fetch to the typed SDK

​The snippet template contributors follow

​The four envelope shapes

​Branching on a 207 in code

​Where the worked examples live

​Pagination in one paragraph

​The cursor loop in code

How to read a worked sample

Reading an endpoint’s sample

Typed SDK tab, or raw fetch — one canonical pattern

Why the non-published-language tabs use raw HTTP

When the Node tab switches to the typed SDK

Migrating a sample from fetch to the typed SDK

The snippet template contributors follow

The four envelope shapes

Branching on a 207 in code

Where the worked examples live

Pagination in one paragraph

The cursor loop in code