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.
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 theX-API-Key header with every request:
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
EveryPOST 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 itstest_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 adata object and a meta object:
List Response (Paginated)
List endpoints include cursor-based pagination inmeta:
Error Response
Errors include a structurederror 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 anX-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:- Server SDKs
- Client SDKs
- Web (browser) — client-side / embeddable widgets
- Swift / iOS, Android, Flutter, React Native — publishable-key client SDKs