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

# Trigger a Single AI-Powered Call via the Scalysis API

> Learn how to place a single outbound AI call using the Scalysis API — configure your payload, send the request, and capture the order ID.

Scalysis lets you fire a single outbound AI call programmatically in seconds. Whether you're confirming a cash-on-delivery order, following up on a lead, or running a quick notification, the trigger endpoint places the call immediately and returns a unique `order_id` you can use to retrieve the outcome once the conversation is complete.

## Prerequisites

Before you make your first call, make sure you have the following:

* **API key** — Generate one from your [Scalysis dashboard](https://app.scalysis.com). Pass it as a `Bearer` token in every request.
* **Script ID** — Open the script you want the AI to use in the dashboard and copy its numeric ID (e.g. `2207`). Every call must be tied to a script.
* **Phone number** in the correct format — see the tip at the bottom of this page.

***

<Steps>
  <Step title="Build the request payload">
    The request body is a JSON object. The table below describes every field.

    | Field           | Type   | Required       | Description                                                      |
    | --------------- | ------ | -------------- | ---------------------------------------------------------------- |
    | `scriptId`      | number | ✅ Yes          | Numeric ID of the script the AI will follow.                     |
    | `customerPhone` | string | ✅ Yes          | Destination phone number for the call.                           |
    | `brand_name`    | string | ⚠️ Conditional | Required when the script references a `{{brand_name}}` variable. |
    | `customerName`  | string | No             | Customer's name, passed into script variables.                   |
    | `orderNumber`   | string | No             | Your internal order reference (e.g. `ORD-1001`).                 |
    | `orderNotes`    | string | No             | Any extra notes the AI should be aware of during the call.       |
    | `campaignName`  | string | No             | Associates this call with a named campaign for reporting.        |

    <Warning>
      If your script uses a `{{brand_name}}` placeholder and you omit the `brand_name` field, the API returns a **400** error:

      ```json theme={null}
      {
        "error": "Missing required script variables: brand_name"
      }
      ```

      Check your script in the dashboard for any `{{ }}` variable placeholders and include a matching field for each one in your request body.
    </Warning>
  </Step>

  <Step title="Send the request">
    Use the curl command below as a starting point. Replace `YOUR_API_KEY` with your real key and adjust the field values as needed.

    ```bash theme={null}
    curl -sS -X POST 'https://app.scalysis.com/api/v1/calls/trigger' \
      -H 'Authorization: Bearer YOUR_API_KEY' \
      -H 'Content-Type: application/json' \
      -d '{
        "scriptId": 2207,
        "customerPhone": "9149874123",
        "customerName": "Rahul",
        "orderNumber": "ORD-1001",
        "brand_name": "Scalysis"
      }'
    ```

    <Tip>
      **Phone number format:** Include the country dialing code when calling numbers outside your default region. For Indian numbers, prefix with `91` — for example, `919149874123`. Do **not** include `+`, spaces, or hyphens; pass the digits only as a plain string.
    </Tip>
  </Step>

  <Step title="Handle the response">
    On success, the API returns HTTP **200** with a JSON body similar to this:

    ```json theme={null}
    {
      "success": true,
      "action": "trigger_call",
      "order_id": 1368642,
      "script_id": 2207,
      "call_status": "in_progress",
      "message": "Call started"
    }
    ```

    Here's what each field means:

    | Field         | Description                                                                                      |
    | ------------- | ------------------------------------------------------------------------------------------------ |
    | `success`     | `true` when the call was accepted and queued successfully.                                       |
    | `action`      | Always `"trigger_call"` for this endpoint.                                                       |
    | `order_id`    | **Save this value.** It uniquely identifies the call and is required to fetch the outcome later. |
    | `script_id`   | Echo of the `scriptId` you sent — useful for verification.                                       |
    | `call_status` | `"in_progress"` means the call has been placed and is connecting or live.                        |
    | `message`     | Human-readable confirmation.                                                                     |

    <Note>
      Store the `order_id` in your database or application state right away. Without it, you cannot retrieve the call transcript, outcome, or cost.
    </Note>
  </Step>

  <Step title="What happens next">
    The moment Scalysis accepts your request, the AI dials the customer immediately — there is no additional step required to initiate the call. Your job now is to wait for the call to finish and then retrieve the result.

    * Typical calls last **30 seconds to a few minutes** depending on the script and conversation flow.
    * Once the call ends, use your saved `order_id` to call the **Get Outcome** endpoint and read the transcript, call outcome, and cost.
    * See [Fetch Call Outcomes](/guides/fetch-outcomes) for the full walkthrough.
  </Step>
</Steps>