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
Most of these APIs authenticate with a credential your Cloudspire administrator provisions for you; there is no self-service key portal, so contact your administrator to obtain or rotate one. Custom Integrations are the exception: there the credential is yours, not ours; you enter the request headers your own endpoint expects, and you rotate them yourself. 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 | Request headers you set on the integration | You authenticate US: the platform sends the fixed headers you configure (a bearer token or API key); reject requests that do not carry them (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. |