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.

Quick smoke test

The same call — GET /api/v1/me, the account probe you run first after minting a key — in six supported forms. The SDKs auto-retry, keep auth, and unpack the { data, meta } envelope; the Go, Ruby, and PHP forms use plain HTTP clients so they run without any Orbit SDK installed.
Prefer the typed client where it covers your resources — the Node SDK is full-surface, and the Python SDK wraps the core resources (messaging, voice, contacts, campaigns, verify, numbers) and reaches everything else through the generic client.request() escape hatch above. Every official SDK exposes the same untyped request method; raw curl works identically. Full SDK index at SDK quickstart, and per-language pages at Node.js, Python, Go, Ruby, and PHP.

Base URL

All API requests are made to:

Authentication

Include your API key in the X-API-Key header with every request:
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.

Sandbox delivery behavior

Sandbox sends never reach a carrier. The message keeps its test_sent status, while the recipient number’s trailing digit selects one of ten simulated delivery-receipt scenarios. Those receipts are sent to your sandbox webhook only; they do not promote the stored message to delivered or failed. See Sandbox Magic Numbers for the complete digit-to-outcome table.

Response Format

Successful Response

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

List Response (Paginated)

List endpoints include cursor-based pagination in meta:
Fetch the next page by passing the cursor:

Error Response

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

HTTP Status Codes

Rate Limiting

Rate limits are enforced per API key. Current limits are returned in response headers: 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. 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. Every official SDK is listed on the SDK index: The REST API is fully usable from any HTTP client for languages that do not have a published package yet.