Cloudspire API Reference
Developer documentation for the Cloudspire REST APIs. These endpoints let your own applications — CRMs, schedulers, ERPs, automation tools, and AI platforms — exchange messages and place AI voice calls through the Cloudspire platform.
Each API below is a separate integration with its own endpoint, authentication, and payloads. Select an API to view its full reference.
APIs
Conventions
The following conventions apply across all Cloudspire APIs unless an individual reference states otherwise.
Base URL
All endpoints are served over HTTPS from a single host:
https://api.cloudspirevoice.com/Plain HTTP is not supported. Requests must use TLS.
Content Type
Request and response bodies are JSON (Content-Type: application/json) unless an endpoint documents a different format. Always send a Content-Type header that matches your body.
Authentication
Every API authenticates with a credential that your Cloudspire administrator provisions for you. There is no self-service key portal — contact your administrator to obtain or rotate a credential. The credential differs per API:
| API | Credential | Sent As |
|---|---|---|
| Webhook SMS API | Per-DID webhook secret | secret field in the JSON body (outbound), or your configured Auth Header (inbound delivery) |
| AI Outbound Calling API | Per-campaign API key | Authorization: Bearer {key} header |
| AI Agent Custom Integrations | A secret you embed in your endpoint URL | You authenticate US: reject requests without your URL token (deliveries are not signed; see the reference) |
| External AI Provider Hooks | Per-engine API token / webhook signing key | token query parameter (tool endpoints), or the x-retell-signature header (lifecycle webhook); see the reference — it varies per hook |
Treat every credential as a secret. Do not embed it in client-side code, public repositories, or URLs. If a credential is exposed, ask your administrator to rotate it — rotation invalidates the old value immediately.
Phone Number Format
Phone numbers use E.164 (a +, the country code, then the national number, e.g. +17705551234). Some endpoints accept or return a digits-only variant; each reference documents the exact format expected per field. Always include the country code.
Timestamps
Timestamps are ISO 8601 with a timezone offset (e.g. 2026-02-13T14:30:00-05:00).
HTTP Status Codes
| Range | Meaning |
|---|---|
2xx | Success. The request was accepted. Note that 202 Accepted means a request was queued for asynchronous processing, not that the underlying action (message sent, call placed) has already completed. |
4xx | A problem with the request: bad input, a missing or invalid credential, or a state that blocks the action (e.g. a disabled campaign). Do not retry without changing the request. |
5xx | A server-side error. Retry with backoff only where the request is idempotent. Queueing an outbound call is not idempotent (each accepted request dials once -- posting twice calls twice), and neither are the mutating tool calls on the External AI Provider Hooks surface (message taking, ticket/issue creation, CRM writes): after a timeout or 5xx the operation may have partially completed, so reconcile from queue/report data before re-invoking rather than blind-retrying. |