> ## 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.

# Trigger outbound call

> Place an immediate outbound campaign call via project API key

Starts a real-time outbound voice call using a campaign configured in the dashboard.

**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="X-API-Key" 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 queued and dispatched.
</ResponseField>

<ResponseField name="campaign_call_id" type="string" required>
  Created campaign call ID.
</ResponseField>

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

## Errors

<ResponseField name="400" type="Bad Request">
  Missing/invalid body, invalid phone, or campaign not ready.
</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/trigger-call" \
    -H "Content-Type: application/json" \
    -H "X-API-Key: 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}/trigger-call`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-API-Key": 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_call_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}/trigger-call",
      headers={
          "Content-Type": "application/json",
          "X-API-Key": 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_call_id"])
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "status": "success",
    "message": "Outbound call successfully queued and dispatched.",
    "data": {
      "success": true,
      "campaign_call_id": "665f1a2b3c4d5e6f7a8b9c0d",
      "message": "Call initiated to +14155552671"
    },
    "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 X-API-Key header.",
    "data": null,
    "status_code": 401
  }
  ```
</ResponseExample>