> ## Documentation Index
> Fetch the complete documentation index at: https://docs.botcadence.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create outbound call

> Queue an outbound campaign call via project API key

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

<ParamField header="Authorization" type="string" required>
  Project API key with the `calls:create` scope. Format: `bot_live_…`
</ParamField>

See [Authentication](/docs/api-reference/authentication).

## Path parameters

<ParamField path="organization_id" type="string" required>
  Organization ID. Must match the API key.
</ParamField>

<ParamField path="project_id" type="string" required>
  Project ID. Must match the API key.
</ParamField>

<ParamField path="campaign_id" type="string" required>
  Outbound campaign ID.
</ParamField>

## Body

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

<ParamField body="phone_number" type="string" required>
  Destination number. Prefer E.164 (for example `+14155552671`).
</ParamField>

<ParamField body="name" type="string">
  Optional display name (`{{ customer.name }}`).
</ParamField>

<ParamField body="email" type="string">
  Optional email (`{{ customer.email }}`).
</ParamField>

<ParamField body="[custom fields]" type="string | number | boolean">
  Any additional keys (for example `order_id`) are available as `{{ customer.order_id }}`.
</ParamField>

## Response

<ResponseField name="success" type="boolean" required>
  `true` when the call was accepted (started or queued).
</ResponseField>

<ResponseField name="campaign_queue_id" type="string" required>
  Campaign queue ID for this call.
</ResponseField>

<ResponseField name="message" type="string" required>
  Human-readable confirmation.
</ResponseField>

<ResponseField name="scheduled" type="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.
</ResponseField>

<ResponseField name="scheduled_for" type="string">
  When the call is waiting for the campaign's calling hours, the ISO 8601 time it will be placed.
</ResponseField>

## Errors

<ResponseField name="400" type="Bad Request">
  Missing/invalid body, invalid phone, campaign not ready, or campaign past its end date.
</ResponseField>

<ResponseField name="401" type="Unauthorized">
  Missing, invalid, or revoked API key.
</ResponseField>

<ResponseField name="403" type="Forbidden">
  Missing `calls:create`, or key does not match org/project.
</ResponseField>

<ResponseField name="404" type="Not Found">
  Campaign not found.
</ResponseField>

<ResponseField name="500" type="Internal Server Error">
  Unexpected dispatch failure.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript JavaScript theme={null}
  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);
  ```

  ```python Python theme={null}
  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"])
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "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
  }
  ```

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

  ```json 401 theme={null}
  {
    "status": "error",
    "message": "Missing API Key. Please provide Authorization header.",
    "data": null,
    "status_code": 401
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.