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.

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.

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.
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 full contract, with both loops in code: Pagination.

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

How to read a worked sample

How to read a worked sample

Reading an endpoint’s sample

The four envelope shapes

Where the worked examples live

​How to read a worked sample

​Reading an endpoint’s sample

​The four envelope shapes

​Where the worked examples live

​Pagination in one paragraph

How to read a worked sample

Reading an endpoint’s sample

The four envelope shapes

Where the worked examples live

Pagination in one paragraph