Skip to main content

​
Explore the API from the Postman workbench

The Developer hub ships a Postman page that exports a Postman collection and environment generated from the live API surface — one request per public endpoint, every JSON body seeded with a working example. Open it from Developer → Postman Collection in the dashboard. This page covers where it lives, how import works, how auth is pre-wired, how to run sandbox and production side by side, and how to keep a local Postman workspace in sync. The import mechanics and first-response shapes are the same ones you’d use with the curated per-channel collections — the companion walkthrough: Ship a sample request with the Postman collections. The difference here is that the dashboard export is generated per-organization over the whole catalog, not a static sample set.

​
1. Where it lives

In the dashboard sidebar, open Developer → Postman Collection. The page renders two download buttons:
  • Download Postman Collection — one request per public endpoint, grouped into folders by tag (Messages, Numbers, Flows, Webhooks, Billing, and so on).
  • Download Postman Environment — three variables pre-filled for your organization: orbit_base_url, orbit_org_id, and a blank orbit_api_key marked as a secret.
The downloads are served over your dashboard session, so the generated environment hits your organization rather than a shared template. Both buttons are plain GETs with a short timeout — click and either file is on disk in a second or two.
The seeded baseline — static/orbit-postman-collection.json — is regenerated from the published OpenAPI spec whenever the docs are rebuilt, so following the same pattern offline means the collection you import matches the published contract, not a stale export.

​
2. Import into Postman

From Postman’s top bar: Import → File, pick the downloaded collection JSON, then repeat for the environment JSON. Postman registers the environment as Orbit — <your org name> and the collection as Orbit CPaaS — <your org name>. If you prefer the command line — or need to pull the artifacts outside an active dashboard session — the same endpoints the buttons call respond to any signed X-API-Key request:

​
3. Auth is auto-injected at collection level

The exported collection carries one auth.apikey block pointing at the X-API-Key header with value {{orbit_api_key}}, and every request inside it is set to Inherit auth from parent. That means you paste your key ONCE — into the environment’s orbit_api_key secret — and every request resolves the same header as a signed curl call:
The dashboard download DOESN’T embed a key — the environment arrives with orbit_api_key blank by design, so the file is safe to share with a teammate. After import, open the environment, paste a dv_test_sk_… or dv_live_sk_… key into orbit_api_key, and select the environment in Postman’s picker. The variable is typed secret, so it stays in Postman’s vault rather than syncing to the shared workspace.
If one request ever returns 401 while the rest work, check its Authorization tab — a request individually switched off Inherit auth from parent drops the collection-level X-API-Key, which is the state behind most “worked yesterday, 401 today” confusion.

​
4. Sandbox and production, side by side

There is no separate sandbox host — {{orbit_base_url}} resolves to the same base; the environment gates sandbox via the key prefix, not the URL (full map: Sandbox & base URLs). Keep two environments in the picker so a wrong-environment send is a visible mistake:
  1. Orbit — Sandbox — orbit_api_key set to dv_test_sk_…. Send calls simulate delivery (test_sent), so to/from don’t have to be real numbers.
  2. Orbit — Live — orbit_api_key set to dv_live_sk_…. The collection itself never changes — only the active environment does.
Saved requests live inside the collection, so every save you make (a renamed request, a tweaked body) persists across environment flips. Promotion before a live key touches real traffic: Environments & promotion and the go-live checklist.

​
5. Keeping a local Postman app in sync

The exported JSON is a plain Collection v2.1 file, so import it once into your local Postman app (or a team workspace), then re-import in place whenever you’ve rotated a key or the API surface has changed. The dashboard page re-exports on every click — it never serves a cached artifact — so grabbing a fresh download is the whole sync loop. If you share an exported collection with a teammate, re-import the same environment or one generated for THEIR organization — orbit_org_id is baked in per-organization, and a mixed org id on org-scoped endpoints produces 403s with no obvious cause. Rotated your key? Paste the new value into orbit_api_key before the old key’s grace window expires (default 24 hours, up to 7 days) or requests start returning 401.

​
6. Three examples to fire first

Pick one request per class — a write, a read, a config create — against the Environment you just imported.

​
send-message (write class)

Messages → POST /messages/sms:
Expect 202 Accepted with data.id (msg_…) and data.status (sent, or test_sent in sandbox). Re-run the same request and the Idempotency-Key header protects you from a duplicate send.

​
list-numbers (read class)

Numbers → GET /numbers — pass ?limit=10 to keep the first page small:
Expect 200 OK with an array under data and pagination controls under meta — the shape explains why list endpoints never return scalar counts. Details: Numbers API.

​
create-flow (config class)

Flows → POST /flows:
Expect 201 Created with data.id (flow_…) — that id is the handle for POST /flows/:id/execute and every version snapshot the builder writes. Shapes and trigger types: Flows API.

​
Troubleshooting

The failure classes here are the same ones the curated collections walk through, so branch on error.code and check the active environment’s orbit_api_key first — never on message wording. Worked examples for the two shapes you hit first (401 from missing inherit-auth, 422 with a details.field): Postman collections troubleshooting.

​
See also