API Overview

The Orbit API is a RESTful JSON API that provides programmatic access to all Orbit services — messaging, voice, AI agents, flows, numbers, and verification.

Using the SDKs

Prefer the typed client, but this page’s endpoint has no helper yet — the generic request() keeps auth/retries and the { data, meta } envelope identical:

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

const { data } = await orbit.request<unknown>(
  "GET",
  "/me"
);

Python (same call via the SDK’s escape hatch):

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

res = client.request("GET", "/me")

The Python SDK is core-scope — it wraps the 8 core resources (messaging, voice, contacts, campaigns, verify, numbers) and reaches everything else through the generic client.request() escape hatch above. See the Python SDK. Raw curl in the body of this page works identically. Full SDK index at SDK quickstart.

Base URL

All API requests are made to:

https://api.orbit.devotel.io/api/v1/

Authentication

Include your API key in the X-API-Key header with every request:

curl https://api.orbit.devotel.io/api/v1/messages \
  -H "X-API-Key: dv_live_sk_your_key_here"

See Authentication for details on API key types and JWT bearer tokens.

Request Format

All request bodies must be JSON with Content-Type: application/json
Phone numbers must be in E.164 format (e.g., +14155552671)
Timestamps are ISO 8601 in UTC (e.g., 2026-03-08T12:00:00Z)
Pagination uses cursor-based pagination (no offset-based)

Idempotency

Every POST that creates a resource accepts an Idempotency-Key header. Orbit stores the completed response against the key for 24 hours: replay the exact same key + body and you get the original response back — no duplicate send, no second charge. Reuse a key with a different body and you get 409 IDEMPOTENCY_KEY_REUSED. On money-moving endpoints (top-up checkout and similar) the header is required, and every official SDK auto-generates a UUIDv4 key on every non-GET request. The full contract — re-entry guards on balance mutations, how to override the SDK key when retrying from your own queue — is in Idempotency and safe retries.

Response Format

Successful Response

Every successful response returns a data object and a meta object:

{
  "data": {
    "id": "msg_abc123",
    "status": "queued",
    "channel": "sms"
  },
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

List Response (Paginated)

List endpoints include cursor-based pagination in meta:

{
  "data": [
    { "id": "msg_001", "status": "delivered" },
    { "id": "msg_002", "status": "delivered" }
  ],
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2026-03-08T12:00:00Z",
    "pagination": {
      "cursor": "cur_abc123",
      "has_more": true,
      "total": 1542
    }
  }
}

Fetch the next page by passing the cursor:

curl "https://api.orbit.devotel.io/api/v1/messages?cursor=cur_abc123&limit=20" \
  -H "X-API-Key: dv_live_sk_..."

Error Response

Errors include a structured error object with a machine-readable code:

{
  "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_xyz789",
    "timestamp": "2026-03-08T12:00:00Z",
    "docs_url": "https://docs.orbit.devotel.io/errors/INVALID_PHONE_NUMBER"
  }
}

HTTP Status Codes

Status	Meaning
`200`	Success
`201`	Resource created
`400`	Bad request — malformed JSON or missing fields
`401`	Unauthorized — invalid or missing API key
`403`	Forbidden — insufficient permissions
`404`	Not found — resource doesn’t exist
`409`	Conflict — duplicate request or state conflict
`422`	Unprocessable — validation failed
`429`	Rate limited — too many requests
`500`	Internal server error
`503`	Service unavailable — transient dependency failure or unprovisioned secret; retry with backoff

Rate Limiting

Rate limits are enforced per API key. Current limits are returned in response headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests per window
`X-RateLimit-Remaining`	Remaining requests in current window
`X-RateLimit-Reset`	Unix timestamp when the window resets
`X-RateLimit-Bucket`	Identifier of the rate-limit bucket (present on 429 responses)
`RateLimit-Limit`	IETF standard equivalent of `X-RateLimit-Limit`
`RateLimit-Remaining`	IETF standard equivalent of `X-RateLimit-Remaining`
`RateLimit-Reset`	IETF standard equivalent of `X-RateLimit-Reset`

When rate limited, you receive a 429 response. Implement exponential backoff and respect the X-RateLimit-Reset header.

Request ID

Every response includes an X-Request-Id header and a request_id in the meta object. Include this ID when contacting support for faster debugging.

API Endpoints

The table below covers the major service groups. It is not exhaustive — the OpenAPI spec at /openapi.json is the authoritative, complete list of endpoints, parameters, and schemas.

Service	Base Path	Description
Messages	`/api/v1/messages`	Send SMS, WhatsApp, RCS, Viber, Email
Voice	`/api/v1/voice`	Calls, recordings, SIP
Fax	`/api/v1/fax`	Send and receive fax (T.38)
WhatsApp	`/api/v1/whatsapp`	WhatsApp Business templates, sessions, media
RCS	`/api/v1/rcs`	RCS Business Messaging agents and rich cards
Email	`/api/v1/email`	Transactional email, senders, deliverability, suppressions
Agents	`/api/v1/agents`	AI agent management
Flows	`/api/v1/flows`	Workflow automation
Numbers	`/api/v1/numbers`	Phone number management
Verify	`/api/v1/verify`	OTP verification
Contacts	`/api/v1/contacts`	Contact records and custom fields
Segments	`/api/v1/segments`	Dynamic audience segments
CDP	`/api/v1/cdp`	Customer data platform, reverse ETL, activations
Campaigns	`/api/v1/campaigns`	Bulk and scheduled campaign sends
Conversations	`/api/v1/conversations`	Unified inbox threads across channels
Surveys	`/api/v1/surveys`	Survey distribution and responses
Video	`/api/v1/video`	Video rooms, recordings, live captions
Analytics	`/api/v1/analytics`	Reporting, dashboards, goals
Billing	`/api/v1/billing`	Usage, invoices, and billing data
Integrations	`/api/v1/integrations`	Third-party connectors
Webhooks	`/api/v1/webhooks`	Webhook management

For the complete set of service groups (including ads, channels, commerce, compliance, knowledge, notifications, SCIM, team chat, Telegram, USSD, and more), refer to the OpenAPI spec.

SDKs

Use an official SDK for a better development experience:

Node.js / TypeScript — server-side
Web (browser) — client-side / embeddable widgets
Python, Go, Java, PHP, Ruby, .NET — coming soon. Until then, the REST API is fully usable from any HTTP client.

API Reference

All Endpoints

Orbit REST API overview: auth, pagination, and errors

API Overview

Using the SDKs

Base URL

Authentication

Request Format

Idempotency

Response Format

Successful Response

List Response (Paginated)

Error Response

HTTP Status Codes

Rate Limiting

Request ID

API Endpoints

SDKs

​API Overview

​Using the SDKs

​Base URL

​Authentication

​Request Format

​Idempotency

​Response Format

​Successful Response

​List Response (Paginated)

​Error Response

​HTTP Status Codes

​Rate Limiting

​Request ID

​API Endpoints

​SDKs

API Overview

Using the SDKs

Base URL

Authentication

Request Format

Idempotency

Response Format

Successful Response

List Response (Paginated)

Error Response

HTTP Status Codes

Rate Limiting

Request ID

API Endpoints

SDKs