Skip to main content

​
Ship a sample request with the Postman collections

The six pre-built Postman collections listed in API integration get you from zero to a real response in minutes. This page is the ordering that page leaves implicit: install the environment, set your key once, run one sample request per class, then iterate. Keep it open next to Postman the first time you import. You need an API key from Settings → API Keys — a dv_test_sk_… key for the sandbox, or a live key when you’re ready. Details: Authentication.

​
1. Import the collection and environment

Each of the six collections is a downloadable JSON; import the one matching the surface you’re building first: In Postman: Import → Link, paste the URL, import. Do the same for the environment so the {{base_url}} and {{api_key}} variables the collections reference resolve — either import the environment file the collections are wired against, or generate one custom to your org:
Both are downloads meant to be imported directly into Postman (Import → File), not parsed as API responses. The org-generated environment arrives with your base URL and org id pre-filled — the API-key variable is blank by design, since the same file is safe to share with a teammate. Full surface: Developer portal → Automate without writing an SDK integration. Which path to pick: the six static collections are curated per pillar with written sample bodies — start there. The org-generated collection is the full catalog pre-wired to your org — reach for it once you’re past the samples.

​
2. Set the API key once, inherit everywhere

Don’t paste the key into one request at a time — set it in the environment and let every request inherit:
  1. Open the imported environment and set api_key to dv_test_sk_… (as a secret-type variable — it never leaves your Postman vault).
  2. Select that environment in Postman’s environment picker.
  3. On the collection, open Authorization and make sure the type carries {{api_key}} as an X-API-Key header. Leave every request inside the collection on Inherit auth from parent.
The resolved header on every send is exactly what a curl call sets:
If you ever set auth on an individual request instead, that request’s setting wins over the collection — which is the state behind most “worked yesterday, 401 today” confusion (see Troubleshooting).

​
3. Three sample calls, three response shapes

Run one request per class. Each below is the same request the Core collection ships — with the response you should see.

​
Send a message (the write class)

Core → Messages → Send SMS:
Expect a 202 Accepted with the persisted message in the standard envelope — data.id (msg_…) is your handle for status polls, data.status starts as sent (or test_sent in sandbox). Re-run the same request and the Idempotency-Key header protects you from a duplicate send; drop the header and don’t.

​
Register a webhook endpoint (the config class)

Core → Webhooks → Create endpoint:
Expect 201 Created with the endpoint’s id and signing secret in data — store the secret, then verify X-Orbit-Signature on every delivery before trusting the body. Contract: Webhooks → Security.

​
Create an internal inbox ticket (the operator class)

POST /inbox/tickets/internal files a ticket directly into the unified inbox for channels with no native inbound path — a partner hand-off or a manual entry — so the row carries the same subject, priority, and assignment model as any inbound conversation.
Expect a 2xx with the created ticket in data; open Inbox in the dashboard and the row is there. Missing a required field is a 422 — the body names the field (see Troubleshooting).

​
4. Iterate: sandbox first, then production

Sandbox is the same base URL — https://api.orbit.devotel.io/api/v1 — gated by your key, not by a separate host. There is no sandbox. hostname to swap. The iteration loop:
  1. Run the request under a dv_test_sk_… environment. Sandbox send calls simulate delivery (test_sent), so to/from don’t have to be real numbers.
  2. When the body and response shape are what you want, flip only the environment: duplicate it, replace api_key with the dv_live_sk_… key, and re-select it. The collection and requests don’t change.
  3. Promotion checklist before a live key touches production traffic: Environments & promotion and, before going live, the go-live checklist.
Keep the two environments side by side — Orbit — Sandbox and Orbit — Live — so a wrong-environment send is a visible mistake in the picker, not a silent one inside one overloaded environment.

​
5. Troubleshooting

401 INVALID_API_KEY. Almost always the header never left Postman: the request’s Authorization tab got switched off Inherit auth from parent, so the collection-level X-API-Key is dropped for that one request. Check the generated headers in Postman’s console — you should see exactly one X-API-Key. Other causes: the key sits in the wrong environment variable (api_key unset in the active environment), the prefix doesn’t match the environment (a dv_test_sk_ key is rejected on a live-only surface and vice versa), or the key was revoked in Settings → API Keys. 422 with a details.field. A required field is missing or malformed — the body names it:
Branch on error.code, never on message wording. The typed failure classes — validation, rate limits, frequency caps, retriable vs terminal — with worked fixes: API error handling by example. Include meta.request_id when you open a support case. 202 but nothing arrives. In sandbox that’s the point — simulate, then promote. Against a live key, track the send: poll GET /messages/:id or subscribe your webhook endpoint to message.delivered / message.failed (section 3), and read the delivery state there.

​
See also