Tutorial: your first playground request, end to end

The API playground guide describes what the playground’s three panes hold. This tutorial walks a concrete example through them: send one SMS in sandbox mode, turn that request into a script you can run from your terminal, verify what you sent in Request Logs, and promote the exact same call to production. You need two things first:

An Orbit account with the owner, admin, or developer role — those roles open Developer → API playground.
One active API key. If you have none, create a sandbox key (dv_test_sk_…) under Settings → API keys.

Step 1 — Send one request in the playground

Open Developer → API playground. Keep the Sandbox/Live toggle in the builder header on Sandbox.
In the left pane, pick Messages → Send SMS (POST /messages).
Fill the form:
- from — one of your numbers in E.164, for example +16572262362.
- to — a magic-number recipient, for example +15005550002. The trailing digit 2 makes the sandbox simulator return a delivered receipt (see Sandbox magic numbers).
- body — any text, for example Hello from Orbit.
Read the code pane (right). Switch it to the cURL tab — it already carries the full request against https://api.orbit.devotel.io/api/v1/messages, with a masked key in the X-API-Key header.
Hit Send.

The response panel shows a 2xx status, the send duration, and the envelope: the message fields land under data (id, status: test_sent, the from/to/body you sent), and meta.request_id names this run. That request_id is the handle for everything after this tutorial — log it whenever you ask support to trace a call. The Send button is disabled? The playground picks the first active key on your account that matches the current mode — a dv_test_sk_… key in sandbox, a dv_live_sk_… key in live. With no matching key, Send stays disabled until you create one under Settings → API keys. Sandbox Send stays a no-op in live mode as well. A 422 back? The error names the bad field verbatim — a recipient that is not E.164, a body over the length limit. Fix the field named and resend.

Step 2 — Turn the form values into a script

The playground runs one request at a time. To loop the same request — try every magic-number trailing digit, say — parameterize the values you just typed. The Node script below is the same POST the playground sent, with the form fields read from environment variables:

// first-playground-request.mjs — run with: node first-playground-request.mjs
const sandbox = process.env.ORBIT_SANDBOX !== "false"; // "false" switches to live
const key = sandbox ? process.env.ORBIT_SANDBOX_KEY : process.env.ORBIT_LIVE_KEY;
if (!key) throw new Error(`Set ORBIT_SANDBOX_KEY (or ORBIT_LIVE_KEY for a live send)`);

const res = await fetch("https://api.orbit.devotel.io/api/v1/messages", {
  method: "POST",
  headers: { "X-API-Key": key, "Content-Type": "application/json" },
  body: JSON.stringify({
    // The same three fields you filled in the builder
    from: process.env.ORBIT_FROM ?? "+16572262362",
    to: process.env.ORBIT_TO ?? "+15005550002",
    body: process.env.ORBIT_BODY ?? "Hello from Orbit",
  }),
});

const payload = await res.json();
console.log(res.status, res.headers.get("x-ratelimit-remaining"), payload);

Run it and compare the printed envelope to the playground’s response panel — same data fields, same meta.request_id. Back in the playground, open the cURL tab in the code pane: the request rendered there is this same call in a single line. Copy it when you want the terminal version instead; the key appears masked in the preview, so paste your full key in before the snippet leaves the dashboard. The script reads the key from an environment variable for the same reason the playground masks it: a copied snippet never carries a usable credential. Put the key in your shell profile or a secrets manager — never in the file you commit.

Step 3 — Make the sandbox toggle a variable

The script’s first line is the playground’s Sandbox/Live toggle rewritten as an environment variable — the mode is data the script reads, not a code edit:

ORBIT_SANDBOX=true  node first-playground-request.mjs   # simulated send, unbilled
ORBIT_SANDBOX=false node first-playground-request.mjs   # live send, billed

The mode-vs-key pairing holds here too — the server rejects a live request signed with a test key and vice versa, so ORBIT_SANDBOX=false with only ORBIT_SANDBOX_KEY set fails at the key check, not at the carrier.

Step 4 — Look the request up in Request Logs

The playground’s recent-request list in the right pane is a per-browser scratchpad — the last 50 runs, localStorage only. It is not where you look up what you sent last week. The durable record is the Request Logs console at Developer → Request logs (/[locale]/developer/request-logs). Every API call — from the playground, from your script, from the SDKs — lands there workspace-wide, with the request and response payloads retained for a year. The page accepts deep links, so /developer/request-logs?method=POST&path=/messages&status=5xx opens already scoped to the failures. When a send behaves unexpectedly, find it there before re-sending — the recorded payload shows exactly what reached the API. See the Request Logs console guide for the filters and payload views.

Step 5 — Carry the same call into production

Sandbox and live differ in exactly one input: which key signs the request. There is no separate production base URL and no body change. The clear-to-production pattern keeps that one input split:

Set the live key in the environment — export ORBIT_LIVE_KEY=dv_live_sk_… — so the value never sits in source. The snippet you copied from the playground already reads ORBIT_LIVE_KEY in live mode; nothing in the request body changes.
Point the recipient at a real number. Magic-number recipients (+1500555000x) only simulate; in live mode the same to is dialed as a real destination.
Re-verify in Request Logs. Live sends appear in the same console; sandbox runs carry test_mode in the response meta, live runs do not — that flag is how you tell which mode a recorded call ran in.

Before you call the endpoint in anger, add an Idempotency-Key header per send so a retry never double-sends — the playground’s generated snippet does not add one because a Send in a browser is a single deliberate action; a retrying worker is not. See Idempotency and safe retries.

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

Tutorial: your first API playground request, end to end

Tutorial: your first playground request, end to end

Step 1 — Send one request in the playground

Step 2 — Turn the form values into a script

Step 3 — Make the sandbox toggle a variable

Step 4 — Look the request up in Request Logs

Step 5 — Carry the same call into production

See also

​Tutorial: your first playground request, end to end

​Step 1 — Send one request in the playground

​Step 2 — Turn the form values into a script

​Step 3 — Make the sandbox toggle a variable

​Step 4 — Look the request up in Request Logs

​Step 5 — Carry the same call into production

​See also

Tutorial: your first playground request, end to end

Step 1 — Send one request in the playground

Step 2 — Turn the form values into a script

Step 3 — Make the sandbox toggle a variable

Step 4 — Look the request up in Request Logs

Step 5 — Carry the same call into production

See also