API Integration

Orbit is API-first. Every feature you can click in the dashboard is backed by a REST endpoint you can call from your own code. This page is the map to the rest of the API reference — where to start, what to test against, and what to watch for in production.

Base URLs

There’s one base URL. Sandbox is not a separate host — it’s the same API, switched into test mode per request.

Environment	Base URL	Use for
Production & Sandbox	`https://api.orbit.devotel.io/api/v1`	Live traffic is billed; sandbox traffic is free

You select sandbox by how you authenticate, not by changing the URL:

Server-to-server: use a test secret key (dv_test_sk_…). Any request signed with a test key runs in sandbox automatically.
From the dashboard (Clerk session): send X-Test-Mode: true. This header is honored only for dashboard sessions — a live API key (dv_live_sk_…) cannot flip into sandbox with it.

Sandbox mirrors production endpoints 1:1. Requests don’t move real money, don’t deduct credits, and don’t dispatch real messages (SMS/WhatsApp/RCS/email/voice are simulated, not sent). Simulated sends return deterministic delivery receipts so you can exercise both the success and failure paths.

Sandbox responses carry "test_mode": true in the meta block. Assert on that to confirm a request ran in sandbox — there is no separate environment header or hostname.

Authentication

Every request needs an API key in the X-API-Key header:

curl https://api.orbit.devotel.io/api/v1/messages \
  -H "X-API-Key: dv_live_sk_abc123..." \
  -H "Content-Type: application/json"

Keys are per-tenant. Subaccounts get their own scoped keys.
Keys have prefix: dv_live_sk_ (production) or dv_test_sk_ (sandbox).
Rotate keys anytime at Settings → API Keys — rotation is instant, old keys invalidate.
Leaked a key? Revoke immediately; Orbit does not charge you for traffic after the revoke timestamp.

Full detail: Authentication.

Channels covered by the API

Everything in the dashboard is available via API. Same payloads, same behavior.

Channel	Endpoint	Reference
SMS (including 10DLC, short-code, toll-free)	`POST /messages/sms`	Messaging API
WhatsApp Business	`POST /messages/whatsapp`	Messaging API
RCS Business Messaging	`POST /messages/rcs`	Messaging API
Viber Tier 1 (one-way basic, SMPP)	`POST /messages/viber`	Viber channel docs
Viber Tier 2 (two-way advanced, Business HTTP)	`POST /messages/viber`	Viber channel docs
Email (SMTP + transactional)	`POST /messages/email`	Messaging API
Voice (inbound, outbound, AI agent, IVR)	`/voice/calls`	Voice API
Verify (OTP codes, Silent Auth)	`/verify`	Verify API
Numbers (search, purchase, release, port)	`/numbers`	Numbers API
Contacts & lists	`/contacts`	Contacts API
Campaigns	`/campaigns`	Campaigns API
AI Agents	`/agents`	Agents API
Flows	`/flows`	Flows API
Billing & usage	`/billing`	Billing API

Each channel has its own endpoint and its own request schema under the /messages prefix — POST /messages/sms, /messages/whatsapp, /messages/rcs, /messages/viber, and /messages/email. There is no single channel-polymorphic /messages route and no top-level channel discriminator: the body shape differs per channel (an SMS send takes to/from/body, a WhatsApp template send takes a template block, and so on) rather than being switched by a channel field. Pick the endpoint that matches the channel you’re sending on.

Your first API call

The fastest way to confirm your key works:

curl https://api.orbit.devotel.io/api/v1/messages/sms \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+16572262362",
    "to": "+15555551234",
    "body": "Hello from Orbit"
  }'

Response — 202 Accepted. The send result is wrapped in the standard envelope ({ data, meta }); the message fields live under data, and meta carries the request_id you should log:

{
  "data": {
    "id": "msg_01HXYZ...",
    "channel": "sms",
    "direction": "outbound",
    "from": "+16572262362",
    "to": "+15555551234",
    "status": "sent",
    "external_id": "prov_7f3c91...",
    "created_at": "2026-04-17T10:23:00Z"
  },
  "meta": {
    "request_id": "req_01HXYZ...",
    "timestamp": "2026-04-17T10:23:00Z"
  }
}

status reflects the persisted state at send time (sent once the provider accepts, queued/scheduled for deferred sends, test_sent in sandbox). There is no top-level cost_estimate on the send response — pull cost and segment counts from GET /messages/:id (or the delivery webhook) once billing settles. Sandbox sends add "test_mode": true to meta. Check status at GET /messages/:id or subscribe to delivery webhooks (recommended).

Webhooks

Webhooks are how Orbit tells your backend about events: a message was delivered, a call connected, an agent escalated a conversation, a number was ported in. You register a URL and we POST events to it. Setup

Dashboard → Settings → Webhooks → Add endpoint
Enter your HTTPS URL (HTTP rejected in production)
Pick the event types you want (or subscribe to * for everything)
Copy the signing secret (whsec_...) — you need it to verify signatures

Every Orbit webhook carries an X-Orbit-Signature header (the canonical signature). We also still emit X-Devotel-Signature with the same value for back-compat — older integrations can keep reading it. During a signing-secret rotation grace window a third header, X-Orbit-Signature-Next, carries the rotation-candidate signature. Verify the signature before trusting the payload. The header is Stripe-style, t=<unix>,v1=<hex> — not a bare hex digest:

X-Orbit-Signature: t=1715357600,v1=4f9c2e6b8a1d3f5e7c9b1a3d5f7e9c1b3a5d7f9e1c3b5a7d9f1e3c5b7a9d1f3e

// Node example
import { createHmac, timingSafeEqual } from "node:crypto";

// Pass the `X-Orbit-Signature` (or back-compat `X-Devotel-Signature`) header value.
function verify(body: string, header: string, secret: string) {
  const [t, v1] = header.split(",").map(p => p.split("=")[1]);
  const expected = createHmac("sha256", secret)
    .update(`${t}.${body}`)
    .digest("hex");
  return timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}

Replay protection: reject any signature whose t (timestamp) is older than 5 minutes. Retries Orbit retries failed webhook deliveries on a fixed 6-step schedule: the initial delivery plus up to 6 retries (7 attempts total). Each retry fires a set interval after the previous attempt fails — 1 minute, 5 minutes, 30 minutes, 2 hours, 8 hours, then 24 hours — not a smooth exponential curve from a short base delay. Every delay gets up to 20% extra jitter on top, so a burst of failures against one endpoint doesn’t retry in lockstep and re-overload it on recovery. Because the last two steps are 8 and 24 hours apart, an endpoint that stays down keeps receiving retries for roughly 35 hours before the schedule is exhausted. Size your delivery monitoring around that full window — the largest gap between two attempts is a full day, not seconds. The event stays in your log either way, so you can replay it from Dashboard → Webhooks → Event log. A webhook is “successful” if your server returns any 2xx within 30 seconds. Anything else (timeout, 5xx, 4xx except 410 Gone) triggers retry. Return 410 Gone to permanently disable a single event (e.g., you’ve deprecated handling for that type). Dead endpoints If we see 50 consecutive failures, we auto-disable the endpoint and email the org admin. Re-enable it from the dashboard once you’ve fixed it. Full detail: Webhooks overview, Event catalog, Security.

Rate limits

Default limits apply per API key. Higher limits available on request.

Endpoint family	Default rate	Notes
`/messages/sms` (send)	100 / min	Per-key, per-channel. There is no shared cross-channel send bucket.
`/messages/whatsapp` (send)	80 / min	Per-key. Meta has its own WABA throttling on top.
`/messages/email` (send)	200 / min	Per-key.
`/messages/rcs` (send)	50 / min	Per-key. Apple / carrier throttling on top.
`/messages/viber` (send)	50 / min	Per-key.
`/messages` (read)	120 / min	Authenticated read cap — `GET /messages` and `GET /messages/:id`.
`/voice/calls` (outbound)	60 / min	Per-number concurrency limits also apply from your provider.
`/contacts`, `/campaigns`, `/agents`, `/flows` (read)	120 / min	Authenticated read cap — list / get.
`/contacts`, `/campaigns`, `/agents`, `/flows` (write)	60 / min	Authenticated write cap — `POST` / `PUT` / `PATCH` / `DELETE`.
`/numbers/search`	60 / min	Fans out to multiple upstream carriers, so it uses the write cap.
`/billing`	120 / min
Auth / signup / password reset	10 / min per IP	`POST /auth/forgot-password` is tighter at 3 / min per IP.

Rate-limit headers are on every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 83
X-RateLimit-Reset: 1713357600

When you exceed the limit you get HTTP 429 with:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 12 seconds.",
    "status": 429,
    "details": { "retry_after": 12 }
  },
  "meta": {
    "request_id": "req_01HXYZ...",
    "timestamp": "2026-04-17T10:23:00Z"
  }
}

Use details.retry_after (seconds), not fixed backoff. Full detail: Rate Limits.

Error codes

All errors follow the same shape:

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Your wallet balance of $0.12 is below the $0.50 minimum to send this WhatsApp conversation. Add funds or lower send volume.",
    "status": 402
  },
  "meta": {
    "request_id": "req_01HXYZ...",
    "timestamp": "2026-04-17T10:23:00Z",
    "docs_url": "https://docs.orbit.devotel.io/errors/INSUFFICIENT_BALANCE"
  }
}

Error codes are UPPERCASE constants (e.g. INSUFFICIENT_BALANCE) — match on error.code exactly. Always log meta.request_id — support can trace it end-to-end. Common codes you’ll hit during integration:

Code	HTTP	Meaning	Fix
`INVALID_API_KEY`	401	Key revoked, wrong env, or typo	Check `Settings → API Keys`
`FORBIDDEN`	403	Tenant suspended — usually billing or compliance	Check dashboard banner
`RATE_LIMITED`	429	Too many requests	Respect `details.retry_after`
`INSUFFICIENT_BALANCE`	402	Wallet empty or below channel min	Top up wallet
`INVALID_PHONE_NUMBER`	422	Not E.164 or not reachable	Validate upstream
`NOT_SMS_CAPABLE`	422	Toll-free without 10DLC reg, or inbound-only number	Register or swap number
`TEMPLATE_NOT_APPROVED`	422	WhatsApp template still pending	Check `status` in `/templates`
`CHANNEL_NOT_CONFIGURED`	422	Tenant hasn’t finished channel onboarding	Go to `Settings → Channels`
`IDEMPOTENCY_KEY_REUSED`	409	Same `Idempotency-Key` reused with different body	Use unique keys per send
`VALIDATION_ERROR`	422	Payload shape wrong — `details.issues` lists each issue	Read `details.issues`

Full list: Error Codes.

Idempotency

Every POST that creates a resource (message, call, contact, campaign) accepts an Idempotency-Key header. Use it.

curl https://api.orbit.devotel.io/api/v1/messages/sms \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Idempotency-Key: order-conf-98421" \
  -H "Content-Type: application/json" \
  -d '{...}'

Orbit stores the response for 24 hours. Replay the exact same key + body → you get the cached response, not a duplicate send. Replay with a different body → 409 IDEMPOTENCY_KEY_REUSED. This is the single most important pattern for production reliability. Use it on every creation endpoint.

Pagination

List endpoints return cursor-paginated results:

{
  "data": [...],
  "meta": {
    "pagination": {
      "cursor": "eyJpZCI6Im1zZ18wMUhYWVovLi4uIn0=",
      "has_more": true,
      "total": 1542
    }
  }
}

Pass ?cursor=<meta.pagination.cursor>&limit=100 for the next page. No offset — cursor is stable against concurrent inserts. Full detail: Pagination.

Postman collections

Pre-built collections per channel — import one and you’re testing in 30 seconds.

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

Each collection has variables for {{base_url}} and {{api_key}} pre-wired. Default environment is sandbox. Also available: OpenAPI 3.1 spec at https://api.orbit.devotel.io/api/v1/openapi.json — import into any codegen (openapi-generator, oats, orval, kiota).

SDKs

If you’d rather not hand-roll HTTP, we maintain official SDKs. They handle auth, retries, pagination, webhook signature verification, and typed models.

Node.js / TypeScript — generally available
Web (browser) — generally available
Python, Go, Java, PHP, Ruby, C# / .NET — in beta, pending publication to their package registries (PyPI, pkg.go.dev, Packagist, RubyGems, Maven Central, NuGet). The source lives in the monorepo today; until each is published you can’t install it from the package manager, so call the REST API directly — our cURL examples translate cleanly into any language.

Browser: use the Orbit Web SDK for client-side widgets (chat embed, voice browser calling). Never ship a secret key (dv_live_sk_… / dv_test_sk_…) to the browser — client-side code uses a publishable key (dv_live_pk_… / dv_test_pk_…). The widget then bootstraps a short-lived visitor session JWT by calling POST /widget/session with your public widget_id; every other widget request carries that token as Authorization: Bearer <token>.

Environments & promotion

Recommended integration flow:

Develop against sandbox with dv_test_sk_* keys (or X-Test-Mode: true from the dashboard)
Stage against sandbox with your staging webhook URL (not production)
Prod swap keys + webhook URL; everything else identical

Sandbox retains data for 30 days then purges. Do not rely on it for long-term storage.

Support

API questions & bugs: developer-support@devotel.io
Compliance (WhatsApp/10DLC/RCS): compliance@devotel.io
Urgent production: in-app chat (Dashboard → bottom-right) — 24/7 for paid tenants, business hours for Free tier
Status page: status.orbit.devotel.io

Always include request_id from the failing response in any support ticket — it’s our fastest route to root cause.

​API Integration

​Base URLs

​Authentication

​Channels covered by the API

​Your first API call

​Webhooks

​Rate limits

​Error codes

​Idempotency

​Pagination

​Postman collections

​SDKs

​Environments & promotion

​Support

API Integration

Base URLs

Authentication

Channels covered by the API

Your first API call

Webhooks

Rate limits

Error codes

Idempotency

Pagination

Postman collections

SDKs

Environments & promotion

Support