AI Outbound Calling API

Queue calls that an AI agent places for you and receive each result at a callback URL.

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. A request that carries call_at waits in the queue until that time instead (see Placing a Call at a Set Time).
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). An attempt that is not answered, reaches voicemail (when the campaign retries on voicemail), or is answered but accomplishes nothing re-queues the call for another attempt after the retry delay. With the campaign’s Retry When set to Call didn’t finish, a conversation the called party cut short is retried too. The final attempt is never re-queued: it produces the result, so the result of a request that keeps failing arrives with its last attempt; with 3 attempts 30 minutes apart, about an hour after the first dial. One exception: when the last attempt could not be placed at all (the dial itself failed), the request is marked failed one retry delay later.

Pausing a campaign. A paused campaign refuses new requests (409). Calls already queued wait and dial as soon as the campaign is active again, unless they are cancelled: the Pause button cancels them as it pauses, and a paused campaign’s queue view offers Cancel queued calls. Setting the status to paused on the campaign form keeps them.

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.

Testing the callback before your endpoint exists. Ask Cloudspire support for your agent’s Test receiver address (staff issue it, because it carries the agent’s platform token): an address on this platform that records whatever is posted to it and acts on nothing. Send it as the webhook_response_url on a test call, with any query string you plan to use, and the delivery appears under Deliveries to the test receiver on the agent’s Tools card with the address exactly as it was dialed (credential values redacted), the headers and the body. If the agent also has a custom integration pointed at the same address, the two deliveries for one call show the same call_id. The receiver keeps only the newest deliveries for each agent, so it is for proving the contract, not for collecting results.

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,
  "seconds_to_answer": 11,
  "disconnection_reason": "agent_hangup",
  "ai_summary": "Confirmed the appointment for March 20th at 2:30 PM with Dr. Smith.",
  "ai_sentiment": "Positive",
  "ai_successful": true,
  "call_id": "sip1.atl.cloudspirevoice.com-1789678613.22316"
}

One Callback per Request

Each request produces one completion callback, sent when the request reaches its terminal status, however many attempts that took. When an attempt connects, the callback follows that attempt (after its analysis) and carries that attempt’s call_id. When no attempt connects, the callback follows the last attempt, with call_id null and the outcome in status and disconnection_reason. When the final attempt was answered but did not succeed (a carrier recording, a silent line), the callback follows that attempt like any answered call, with its call_id and status failed. Attempts that are retried send nothing, and a request cancelled before its final attempt sends none at all (the result lookup shows it as cancelled). Your external_id is on every callback. In the rare case of a platform restart between sending and recording a callback, the same callback can be sent a second time, so treat queue_id as the de-duplication key.

Callback Fields

Disconnection Reasons

disconnection_reason says how an answered call ended. Read the outcome from status; the reason adds detail, and new values can be added, so handle a value you do not recognize by its status.

Looking Up a Result

The callback is sent once and is not retried, so if your endpoint was unreachable when it fired, ask for the result instead. The lookup uses the same campaign API key as the intake, reads only your own campaign’s requests, places no call, and answers whatever the campaign’s status is.

GET https://api.cloudspirevoice.com/agent/campaign-result.php?external_id=CRM-12345
GET https://api.cloudspirevoice.com/agent/campaign-result.php?queue_id=84213
Authorization: Bearer {campaign_api_key}

Pass exactly one of external_id (your reference) or queue_id (the id returned in the 202). The response carries the same fields as the completion callback, plus attempts, created_at, completed_at and terminal (false while the request is still queued, dialing or connected, so you can tell a result from a request in progress):

{
  "campaign_id": 5,
  "count": 1,
  "results": [{
    "queue_id": 84213,
    "call_id": "sip1.atl.cloudspirevoice.com-1789678613.22316",
    "campaign_id": 5,
    "external_id": "CRM-12345",
    "to_number": "+17705551234",
    "contact_name": "John Doe",
    "status": "completed",
    "terminal": true,
    "attempts": 1,
    "duration_sec": 92,
    "seconds_to_answer": 11,
    "disconnection_reason": "agent_hangup",
    "ai_summary": "Confirmed the appointment for March 20th at 2:30 PM with Dr. Smith.",
    "ai_sentiment": "Positive",
    "ai_successful": true,
    "created_at": "2026-03-18 14:02:11",
    "completed_at": "2026-03-18 14:04:03"
  }]
}

Because the intake does not de-duplicate on external_id, a lookup by external_id returns every request that carried it, newest first (up to 10). ai_summary and the other analysis fields fill in a short while after the call ends, exactly when the callback would have been sent. Errors: 400 when neither or both parameters are passed, 401 for a missing or unknown key, 404 when your campaign has no request with that reference. That includes a lookup made before the request was submitted: a reference exists only once its POST has returned 202, so start looking after the 202, or read a 404 as “not submitted yet”.

The lookup is the fallback for a callback you missed, not a live feed. Checking every 30 to 60 seconds is plenty. Posting the same external_id again places a new call, so do not re-submit a request to find out how it went.

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 placeholder the prompt references but no variable supplies is left in the prompt as written, and the agent may read it aloud, so send every key the prompt uses or give it a default on the campaign.
• 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 with the result lookup (by your external_id) or 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 two ceilings, both configured by your administrator:

• Campaign concurrency: maximum simultaneous calls for this campaign, from 1 to 10.
• Account concurrency: maximum simultaneous AI outbound calls across all of the account's campaigns, 5 unless your administrator has set another limit. A campaign set higher than this still runs at this ceiling.

If each result you write back uses a resource your side limits (a licensed login, an API rate limit), keep the campaign concurrency at or below that limit.

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.

Placing a Call at a Set Time

To have a call placed later, for example at the time a contact asked to be called back, send call_at with the request. The request is accepted with a 202 as usual, immediate reads scheduled, and the response echoes the call_at it will use. The call waits in the queue and the per-minute worker places it on its first run at or after that time, so it rings within about a minute of the time you asked for.

• Give the time with its offset (-04:00) or in UTC (Z). A time without one is rejected, so a call never rings at a time zone you did not mean.
• The campaign's calling window still applies. A call_at outside it is placed when the window next opens.
• Concurrency, retries and the completion callback work as for any other request. A retry after an unanswered scheduled call follows the campaign's retry delay from that attempt.
• A scheduled call can be cancelled from the campaign's queue view until it is placed. Pausing the campaign with its Pause button cancels it too.

Getting Calls Answered

Mobile carriers screen incoming calls with call-protection services that score each calling number. A number with a low score can be labeled as spam or diverted without ringing the phone at all. In that case the carrier answers the call itself within two or three seconds and plays the person’s voicemail greeting, so the result reads voicemail even though the phone never rang. Four things help:

• Signed caller ID. Every call from your campaign number carries full (A) STIR/SHAKEN attestation under Cloudspire’s certificate. Nothing to do on your side.
• A caller name. Ask Cloudspire support to register an outbound caller name (CNAM) for your campaign number; carriers pick it up as their databases refresh, which can take a few days.
• Registration. Register the number at the Free Caller Registry, which reaches the major call-protection providers (First Orion, Hiya and TNS). The registry accepts only the business that makes the calls, not a provider registering on its behalf, so this one is yours to do.
• Saved contacts. Ask the people you call regularly to save the number in their contacts under a name they will recognize.

To catch a number being diverted, read seconds_to_answer: a voicemail result, or a failed one, answered within two or three seconds usually means the carrier took the call instead of ringing the phone.

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.