Create outbound call

curl -X POST "https://backend.botcadence.com/organizations/ORG_ID/projects/PROJECT_ID/campaigns/CAMPAIGN_ID/calls" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer bot_live_YOUR_KEY" \
  -d '{
    "phone_number": "+14155552671",
    "name": "Alex Rivera",
    "order_id": "ORD-1042"
  }'

const response = await fetch(
  `https://backend.botcadence.com/organizations/${organizationId}/projects/${projectId}/campaigns/${campaignId}/calls`,
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${process.env.BOTCADENCE_API_KEY}`,
    },
    body: JSON.stringify({
      phone_number: "+14155552671",
      name: "Alex Rivera",
      order_id: "ORD-1042",
    }),
  }
);
const result = await response.json();
console.log(result.data.campaign_queue_id);

import os
import requests

response = requests.post(
    f"https://backend.botcadence.com/organizations/{organization_id}/projects/{project_id}/campaigns/{campaign_id}/calls",
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {os.environ['BOTCADENCE_API_KEY']}",
    },
    json={
        "phone_number": "+14155552671",
        "name": "Alex Rivera",
        "order_id": "ORD-1042",
    },
)
response.raise_for_status()
print(response.json()["data"]["campaign_queue_id"])

{
  "status": "success",
  "message": "Call initiated to +14155552671",
  "data": {
    "success": true,
    "campaign_queue_id": "665f1a2b3c4d5e6f7a8b9c0d",
    "message": "Call initiated to +14155552671",
    "scheduled": false,
    "scheduled_for": null
  },
  "status_code": 200
}

{
  "status": "error",
  "message": "phone_number is required.",
  "data": null,
  "status_code": 400
}

{
  "status": "error",
  "message": "Missing API Key. Please provide Authorization header.",
  "data": null,
  "status_code": 401
}

POST

organizations

{organization_id}

projects

{project_id}

campaigns

{campaign_id}

calls

curl -X POST "https://backend.botcadence.com/organizations/ORG_ID/projects/PROJECT_ID/campaigns/CAMPAIGN_ID/calls" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer bot_live_YOUR_KEY" \
  -d '{
    "phone_number": "+14155552671",
    "name": "Alex Rivera",
    "order_id": "ORD-1042"
  }'

const response = await fetch(
  `https://backend.botcadence.com/organizations/${organizationId}/projects/${projectId}/campaigns/${campaignId}/calls`,
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${process.env.BOTCADENCE_API_KEY}`,
    },
    body: JSON.stringify({
      phone_number: "+14155552671",
      name: "Alex Rivera",
      order_id: "ORD-1042",
    }),
  }
);
const result = await response.json();
console.log(result.data.campaign_queue_id);

import os
import requests

response = requests.post(
    f"https://backend.botcadence.com/organizations/{organization_id}/projects/{project_id}/campaigns/{campaign_id}/calls",
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {os.environ['BOTCADENCE_API_KEY']}",
    },
    json={
        "phone_number": "+14155552671",
        "name": "Alex Rivera",
        "order_id": "ORD-1042",
    },
)
response.raise_for_status()
print(response.json()["data"]["campaign_queue_id"])

{
  "status": "success",
  "message": "Call initiated to +14155552671",
  "data": {
    "success": true,
    "campaign_queue_id": "665f1a2b3c4d5e6f7a8b9c0d",
    "message": "Call initiated to +14155552671",
    "scheduled": false,
    "scheduled_for": null
  },
  "status_code": 200
}

{
  "status": "error",
  "message": "phone_number is required.",
  "data": null,
  "status_code": 400
}

{
  "status": "error",
  "message": "Missing API Key. Please provide Authorization header.",
  "data": null,
  "status_code": 401
}

Queues an outbound voice call on a campaign configured in the dashboard. The call follows the campaign’s rules:

Calling hours: inside the campaign’s calling hours the call starts right away. Outside them it waits for the next window.
Capacity: if every calling slot is busy, the call waits in the campaign queue and starts when one frees up.
Retries: unanswered calls are retried using the campaign’s retry settings.

To call at any time of day, widen the campaign’s calling hours. Required scope: calls:create

Prerequisites

Outbound campaign with workflow (or static script + voice) and caller ID
Project API key with calls:create for the same organization and project

You do not need a dial list or to start the campaign for API-triggered calls.

Authentication

string

required

Project API key with the calls:create scope. Format: bot_live_…

See Authentication.

Path parameters

string

required

Organization ID. Must match the API key.

string

required

Project ID. Must match the API key.

string

required

Outbound campaign ID.

Body

Send a JSON object representing the customer. Extra fields are available in prompts as {{ customer.<key> }}.

string

required

Destination number. Prefer E.164 (for example +14155552671).

string

Optional display name ({{ customer.name }}).

string

Optional email ({{ customer.email }}).

string | number | boolean

Any additional keys (for example order_id) are available as {{ customer.order_id }}.

Response

boolean

required

true when the call was accepted (started or queued).

string

required

Campaign queue ID for this call.

string

required

Human-readable confirmation.

boolean

required

false when the call has started. true when it is waiting: for the campaign’s calling hours, for a free calling slot, or because a call to this number is already queued.

string

When the call is waiting for the campaign’s calling hours, the ISO 8601 time it will be placed.

Errors

Bad Request

Missing/invalid body, invalid phone, campaign not ready, or campaign past its end date.

Unauthorized

Missing, invalid, or revoked API key.

Forbidden

Missing calls:create, or key does not match org/project.

Not Found

Campaign not found.

Internal Server Error

Unexpected dispatch failure.

curl -X POST "https://backend.botcadence.com/organizations/ORG_ID/projects/PROJECT_ID/campaigns/CAMPAIGN_ID/calls" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer bot_live_YOUR_KEY" \
  -d '{
    "phone_number": "+14155552671",
    "name": "Alex Rivera",
    "order_id": "ORD-1042"
  }'

const response = await fetch(
  `https://backend.botcadence.com/organizations/${organizationId}/projects/${projectId}/campaigns/${campaignId}/calls`,
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${process.env.BOTCADENCE_API_KEY}`,
    },
    body: JSON.stringify({
      phone_number: "+14155552671",
      name: "Alex Rivera",
      order_id: "ORD-1042",
    }),
  }
);
const result = await response.json();
console.log(result.data.campaign_queue_id);

import os
import requests

response = requests.post(
    f"https://backend.botcadence.com/organizations/{organization_id}/projects/{project_id}/campaigns/{campaign_id}/calls",
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {os.environ['BOTCADENCE_API_KEY']}",
    },
    json={
        "phone_number": "+14155552671",
        "name": "Alex Rivera",
        "order_id": "ORD-1042",
    },
)
response.raise_for_status()
print(response.json()["data"]["campaign_queue_id"])

{
  "status": "success",
  "message": "Call initiated to +14155552671",
  "data": {
    "success": true,
    "campaign_queue_id": "665f1a2b3c4d5e6f7a8b9c0d",
    "message": "Call initiated to +14155552671",
    "scheduled": false,
    "scheduled_for": null
  },
  "status_code": 200
}

{
  "status": "error",
  "message": "phone_number is required.",
  "data": null,
  "status_code": 400
}

{
  "status": "error",
  "message": "Missing API Key. Please provide Authorization header.",
  "data": null,
  "status_code": 401
}

Getting Started

Organization

Projects

Operate

Insights

Outreach

Build

Deploy

Admin

API Reference

Prerequisites

Authentication

Path parameters

Body

Response

Errors

​Prerequisites

​Authentication

​Path parameters

​Body

​Response

​Errors

Prerequisites

Authentication

Path parameters

Body

Response

Errors