> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Ship a sample request with the Postman collections

> Get the six Orbit Postman collections running end to end — import the collection and environment, set your API key once, send three sample requests, iterate between sandbox and production, and read the two failure shapes you'll hit first.

# Ship a sample request with the Postman collections

The six pre-built Postman collections listed in [API integration](/guides/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](/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:

| Collection                                        | Import link                                                                                    |
| ------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Orbit — Core (auth, messages, contacts, webhooks) | [postman/orbit-core.json](https://docs.devotel.io/postman/orbit-core.json)                     |
| Orbit — Voice & IVR                               | [postman/orbit-voice.json](https://docs.devotel.io/postman/orbit-voice.json)                   |
| Orbit — Campaigns & Flows                         | [postman/orbit-campaigns.json](https://docs.devotel.io/postman/orbit-campaigns.json)           |
| Orbit — Agents (AI)                               | [postman/orbit-agents.json](https://docs.devotel.io/postman/orbit-agents.json)                 |
| Orbit — Numbers & Verify                          | [postman/orbit-numbers-verify.json](https://docs.devotel.io/postman/orbit-numbers-verify.json) |
| Orbit — Billing & Usage                           | [postman/orbit-billing.json](https://docs.devotel.io/postman/orbit-billing.json)               |

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:

```bash theme={null}
curl -O "https://api.orbit.devotel.io/api/v1/developers/postman-environment" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

# The org-generated collection covering every public endpoint also downloads here:
curl -O "https://api.orbit.devotel.io/api/v1/developers/postman-collection" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"
```

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](/guides/developer-portal).

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:

```bash theme={null}
curl https://api.orbit.devotel.io/api/v1/messages \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"
```

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](#5-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:**

```bash theme={null}
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" \
  -H "Idempotency-Key: postman-first-send-1" \
  -d '{
    "from": "+16572262362",
    "to": "+14155552671",
    "body": "Hello from Postman."
  }'
```

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:**

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/webhooks \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.example/orbit/events",
    "events": ["message.delivered", "message.failed"]
  }'
```

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](/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.

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/inbox/tickets/internal \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Callback requested via partner portal",
    "priority": "normal",
    "external_ref": "partner-handoff-7713"
  }'
```

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](#5-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](/guides/api-integration#environments--promotion) and, before going live, the [go-live checklist](/guides/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:

```json theme={null}
{
  "error": {
    "code": "INVALID_PHONE_NUMBER",
    "message": "The 'to' field must be a valid E.164 phone number",
    "status": 422,
    "details": { "field": "to", "value": "+1234", "expected": "E.164 format e.g. +14155552671" }
  },
  "meta": { "request_id": "req_abc123", "docs_url": "https://docs.orbit.devotel.io/errors/INVALID_PHONE_NUMBER" }
}
```

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](/guides/error-handling-examples). 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

* [API integration](/guides/api-integration) — the six collections with download links, base URLs, idempotency, pagination
* [Developer portal](/guides/developer-portal) — the org-generated collection and environment endpoints
* [API error handling by example](/guides/error-handling-examples) — typed errors beyond the two shapes above
* [Authentication](/authentication) — key formats, roles, rotation
* [Go-live checklist](/guides/go-live-checklist) — promotion gate before live traffic