AI Outbound Calling API

The AI Outbound Calling API lets an external system — a CRM, scheduler, ERP, or any custom application — queue outbound calls that a Cloudspire AI agent places and conducts. You POST one request per call; the platform dials the number, the AI agent handles the conversation, and (optionally) the result is POSTed back to a callback URL of your choice when the call completes.

Calls route through the same PBX infrastructure as every other call on the platform, so they carry proper caller ID, STIR/SHAKEN attestation, and call recording.

How It Works

1. Your system POSTs a call request to the webhook endpoint, authenticated with the campaign's API key.
2. The request is validated and added to the campaign's outbound queue.
3. The platform attempts to place the call immediately. If concurrency is exhausted or the request arrives outside the campaign's calling schedule, the call stays queued and a worker (running every minute) places it as soon as conditions allow.
4. The AI agent converses with the called party using the per-call variables you supplied.
5. When the call ends and is analyzed, the queue record is updated with the outcome. If you supplied a webhook_response_url, the result is POSTed there.

Prerequisites

Before your requests will result in placed calls, your Cloudspire administrator must have the following in place. Several of these are the reason a request can be accepted (queued) yet not dial.

Base URL

https://api.cloudspirevoice.com/

Authentication

Authenticate every request with the campaign's API key as a Bearer token:

Authorization: Bearer {campaign_api_key}

The key maps the request to exactly one campaign — which determines the tenant, AI agent, From DID, schedule, concurrency limits, and retry behavior. There is no separate campaign ID to send; it is implied by the key.

• A missing or malformed Authorization header returns 401.
• An unrecognized key returns 401.
• Keep the key server-side. Regenerating it from the campaign edit form invalidates the previous key at once.

Queue an Outbound Call

Queue a single outbound AI call.

Endpoint

POST https://api.cloudspirevoice.com/agent/campaign-intake.php

Headers

Request Body

{
  "to_number": "+17705551234",
  "contact_name": "John Doe",
  "variables": {
    "appointment_date": "March 20th",
    "appointment_time": "2:30 PM",
    "provider": "Dr. Smith"
  },
  "external_id": "CRM-12345",
  "webhook_response_url": "https://your-system.example.com/cloudspire/callback"
}

Request Fields

Success Response

HTTP 202 Accepted

{
  "status": "queued",
  "queue_id": 84213,
  "campaign_id": 5,
  "immediate": "dialing"
}

The immediate Field

Common values:

Error Responses

All error bodies are JSON of the form {"error": "..."}. The 409 Campaign is not active response additionally includes campaign_status.

Call Lifecycle & Queue Statuses

Each queued call moves through a series of statuses. You observe the final outcome via the completion callback; the intermediate states are visible in the campaign's queue view in the admin portal.

Retry behavior is set on the campaign (max attempts and retry delay). Transient outcomes — no answer, busy, dial failed, provider error, and (when configured) voicemail — re-queue the call with a future attempt time until attempts are exhausted.

Completion Callback

If you include a webhook_response_url on the request, Cloudspire POSTs the call result to that URL once the call reaches a terminal status (completed, voicemail, or failed) and post-call analysis has finished. This is how you get the transcript summary and sentiment back into your system.

Delivery Details

Callback Payload

{
  "queue_id": 84213,
  "campaign_id": 5,
  "external_id": "CRM-12345",
  "to_number": "+17705551234",
  "contact_name": "John Doe",
  "status": "completed",
  "duration_sec": 92,
  "disconnection_reason": "agent_hangup",
  "ai_summary": "Confirmed the appointment for March 20th at 2:30 PM with Dr. Smith.",
  "ai_sentiment": "Positive",
  "ai_successful": 1
}

Callback Fields

Dynamic Variables

The variables object carries per-call values into the AI agent's prompt. The campaign can define default variables; your per-call variables are merged over those defaults (per-call wins on a key clash). Reference them in the agent prompt with double-brace syntax, e.g. {{appointment_date}}.

• Use a flat object of string-friendly key/value pairs.
• Keep keys aligned with what the agent prompt expects — an unreferenced variable is simply ignored; a referenced-but-missing one renders empty.
• Do not put secrets in variables; they become part of the call context.

Idempotency & Reconciliation

Each accepted POST creates exactly one queue entry and one call attempt sequence. The endpoint does not de-duplicate on external_id or to_number — if you POST the same record twice, the number is called twice. To stay idempotent:

• Track which records you have already submitted on your side, and POST each once.
• Set external_id to your record's unique ID so the completion callback can be matched back without ambiguity.
• On a 5xx or a network timeout where you did not receive a 202, the request may still have been accepted and the call placed — reconcile against the queue view/reports before resubmitting (queueing is not idempotent; posting twice calls twice). On a 4xx, fix the request first.

Concurrency & Scheduling

You can POST calls faster than they are dialed; the queue absorbs the burst and the worker drains it within the configured limits. Placement is bounded by three ceilings, all configured by your administrator:

• Campaign concurrency — maximum simultaneous calls for this campaign.
• Tenant concurrency — maximum simultaneous AI outbound calls across all of the account's campaigns.
• Workspace threshold — a platform-wide safety ceiling on the underlying AI voice provider.

Calls submitted outside the campaign's scheduled calling window (days of week and a daily start/end time in the campaign's timezone) remain queued and are placed automatically when the next window opens. There is no need to time your POSTs to the window — load the queue whenever it suits your system.

Integrating an External System (CRM / ERP)

Because the endpoint is push-only, integrating a system that exposes its own API (for example, an ERP you query for the day's appointments) means writing a small connector that:

1. Reads the records to call from your source system (authenticate to it, query the relevant entity).
2. Maps each record to a request body: to_number in E.164, a contact_name, the variables the agent prompt needs, and external_id set to the source record's unique ID.
3. POSTs each call to this endpoint with the campaign's Bearer key.
4. Consumes the completion callback (or polls your own results store) and writes the outcome back to the source record, matched on external_id.

The connector holds the credentials for both sides and owns the business logic of which records to call and when. Cloudspire's responsibility begins at the POST and ends at the callback.

Example: queue a call with curl

curl -X POST https://api.cloudspirevoice.com/agent/campaign-intake.php \
  -H "Authorization: Bearer {campaign_api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "to_number": "+17705551234",
    "contact_name": "John Doe",
    "variables": { "appointment_date": "March 20th", "appointment_time": "2:30 PM" },
    "external_id": "CRM-12345",
    "webhook_response_url": "https://your-system.example.com/cloudspire/callback"
  }'

HTTP/1.1 202 Accepted
{ "status": "queued", "queue_id": 84213, "campaign_id": 5, "immediate": "dialing" }

Billing & Limits

• Placed AI calls draw on the account's AI Voice Minutes pool (included minutes plus any overage) -- the same pool inbound AI voice uses. Outbound additionally requires the AI Outbound Calling add-on.
• Without both the AI Voice Minutes pool and the AI Outbound Calling add-on, requests are accepted (202) but stay queued and are not dialed.
• The variables payload is capped at 64 KB per call.
• Numbers on the tenant blacklist are never dialed — they are rejected at submit time (409) or marked blacklisted at placement.