Skip to main content

​
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://orbit-api.devotel.io/api/v1/

​
Authentication

Include your API key in the X-API-Key header with every request: 
curl https://orbit-api.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": {
    "message_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": [
    { "message_id": "msg_001", "status": "delivered" },
    { "message_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://orbit-api.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://orbit-docs.devotel.io/errors/INVALID_PHONE_NUMBER"
  }
}

​
HTTP Status Codes

StatusMeaning
200Success
201Resource created
400Bad request — malformed JSON or missing fields
401Unauthorized — invalid or missing API key
403Forbidden — insufficient permissions
404Not found — resource doesn’t exist
409Conflict — duplicate request or state conflict
422Unprocessable — validation failed
429Rate limited — too many requests
500Internal server error

​
Rate Limiting

Rate limits are enforced per API key. Current limits are returned in response headers:
HeaderDescription
X-RateLimit-LimitMaximum requests per window
X-RateLimit-RemainingRemaining requests in current window
X-RateLimit-ResetUnix timestamp when the window resets
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

ServiceBase PathDescription
Messages/v1/messagesSend SMS, WhatsApp, RCS, Viber, Email
Voice/v1/voiceCalls, recordings, SIP
Agents/v1/agentsAI agent management
Flows/v1/flowsWorkflow automation
Numbers/v1/numbersPhone number management
Verify/v1/verifyOTP verification
Webhooks/v1/webhooksWebhook management

​
SDKs

Use an official SDK for a better development experience: