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.

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)

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

API Overview

API Overview

Base URL

Authentication

Request Format

Response Format

Successful Response

List Response (Paginated)

Error Response

HTTP Status Codes

Rate Limiting

Request ID

API Endpoints

SDKs

​API Overview

​Base URL

​Authentication

​Request Format

​Response Format

​Successful Response

​List Response (Paginated)

​Error Response

​HTTP Status Codes

​Rate Limiting

​Request ID

​API Endpoints

​SDKs

API Overview

Base URL

Authentication

Request Format

Response Format

Successful Response

List Response (Paginated)

Error Response

HTTP Status Codes

Rate Limiting

Request ID

API Endpoints

SDKs