Skip to main content

​
Where a worked sample belongs

These docs publish worked request and response samples through two different surfaces: the editorial overlay attached to each endpoint reference page, and the task-oriented cookbook at REST API recipes. They are not redundant — they answer different questions. This page explains the split so the next sample lands on the right surface, and readers know which surface to reach for.

​
What the recipe page covers

REST API recipes owns 25 numbered, task-shaped flows — from sending and tracking a message to the pillar-level loops for voice, numbers, WhatsApp, loyalty, flows, knowledge bases, and the Orby copilot — plus the thin A–D pack covering Telegram, USSD, MMS, and Voice. Each flow pairs curl with an SDK tab and walks a full loop: request, success envelope, polling or webhook, error branch. Everything outside those flows is deliberately not there. The cookbook assumes no endpoint-ordering knowledge a single endpoint would impose, which is why account, auth, SAML headers, and feedback categories live in overlays instead of recipes. Readers looking for those use the per-endpoint pages; only flows that span several endpoints graduate to the cookbook.

​
Endpoint-level overlay vs recipe-level cookbook

Every endpoint reference page (the auto-generated pages under API reference) carries an editorial overlay — the Worked request and response samples block — sewn into the page at regeneration time. Use this decision rule when you add a sample: Pick the endpoint overlay when the sample needs exactly one endpoint. One call, one success envelope, one error set. The overlay sits next to the parameter table so a reader can resolve the contract without leaving the page. Examples in the shipped tree: the Feedback submit sample, the Auth SAML round-trip steps, the Account error classes. Pick the recipe cookbook when the value is the chain. The sample steps across endpoints (send → poll → webhook → error path) or stitches an SDK tab for several languages. Recipes are numbered so support can cite them; the per-endpoint pages link back to the recipe for the canonical loop. Example: the Messaging overlay is self-sufficient, but Task 1 of the cookbook is the canonical send → poll → webhook chain. When both fit, prefer the overlay: shorter samples age better, and the cookbook’s task index stays readable at 25 entries. Split the decision at the intent you are serving — a contract question (one endpoint) or a workflow question (several).
  • How to read a worked sample — the four response envelope shapes and how to translate any sample into a runnable call. Every overlay points readers here instead of re-describing envelopes.
  • REST API recipes — the 25-task cookbook this page triages against.
  • Messaging API — the canonical worked-sample shape to copy: a send → poll → receive the delivery webhook DLR chain with per-step envelopes. New overlays should imitate that sequencing whenever the endpoint has a delivery or status lifecycle.

​
Contributing rules for new samples

Consistency beats style preference. When you add or update a worked sample:
  1. Match the platform envelope exactly. Success samples carry { data, meta }; error samples carry { error, meta } with a stable error.code. Never invent a shape outside the four envelopes in How to read a worked sample.
  2. Use sandbox keys in every sample. dv_test_sk_YOUR_KEY (cURL) or process.env.ORBIT_API_KEY (code tabs) — never a live-prefix key, and never a concrete-looking key a reader might copy verbatim.
  3. Keep request ids stable and tagged. Render meta.request_id as req_<tag> (for example req_sms_send, req_msg_get) so two samples on the same page never share an id and a reader can tell ids from data.
  4. Copy a shipped shape before inventing one. The messaging DLR chain above is the reference; for pure failures-only pages the Account overlay matrix is the reference.
Docs readers run samples against the sandbox first; a sample that drifts from these rules costs them a debugging session. Keep the receipt small and the envelope exact.