> ## 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 Call — POST /api/v1/calls/trigger

> Instantly dispatch a single AI-powered outbound call to a customer using a configured script, phone number, and optional order context.

Use this endpoint to trigger an immediate, single outbound call through the Scalysis AI calling engine. You supply the script you want the agent to follow, the customer's phone number, and any optional context — such as an order number or notes — that the agent should have during the conversation. The call begins as soon as the request is accepted.

**Endpoint**

```text theme={null}
POST https://app.scalysis.com/api/v1/calls/trigger
```

**Authentication**

Include your API key in the request using either the `Authorization` header as a Bearer token or the `X-API-Key` header.

```text theme={null}
Authorization: Bearer <your_api_key>
```

```text theme={null}
X-API-Key: <your_api_key>
```

***

## Request Body

<ParamField body="scriptId" type="number" required>
  The numeric ID of the AI agent script you want to use for this call. You can find script IDs in your Scalysis dashboard under **Scripts**.
</ParamField>

<ParamField body="customerPhone" type="string" required>
  The customer's phone number to dial. Include the country code (e.g. `+14155550123`).
</ParamField>

<ParamField body="brand_name" type="string">
  Your brand name, required when the selected script references it. If you receive a `400` error with the message `Missing required script variables: brand_name`, add this field to your request.
</ParamField>

<ParamField body="customerName" type="string">
  The customer's full name. When provided, the agent can address the customer by name during the call.
</ParamField>

<ParamField body="orderNumber" type="string">
  Your internal order or reference number. Passed to the agent as context and stored on the resulting order record.
</ParamField>

<ParamField body="orderNotes" type="string">
  Free-text notes about the order or customer that the agent should be aware of during the call.
</ParamField>

<ParamField body="campaignName" type="string">
  An optional label to associate this call with a named campaign for reporting purposes.
</ParamField>

***

## Example Request

```bash theme={null}
curl --request POST \
  --url https://app.scalysis.com/api/v1/calls/trigger \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "scriptId": 2207,
    "customerPhone": "+14155550123",
    "brand_name": "Acme Store",
    "customerName": "Jane Smith",
    "orderNumber": "demo-order-001",
    "orderNotes": "Customer requested a callback about delivery",
    "campaignName": "spring-outreach"
  }'
```

***

## Response Fields

<ResponseField name="success" type="boolean">
  `true` when the call was successfully initiated.
</ResponseField>

<ResponseField name="action" type="string">
  The action that was performed. Always `"trigger_call"` for this endpoint.
</ResponseField>

<ResponseField name="order_id" type="number">
  The unique identifier assigned to this call record. Use this value with the [Get Outcome](/api-reference/orders/get-outcome) endpoint to retrieve results after the call completes.
</ResponseField>

<ResponseField name="script_id" type="number">
  The ID of the script used for this call, echoed back from your request.
</ResponseField>

<ResponseField name="call_status" type="string">
  The current status of the call. Returns `"in_progress"` immediately after triggering.
</ResponseField>

<ResponseField name="message" type="string">
  A human-readable status message. Returns `"Call started"` on success.
</ResponseField>

***

## Example Success Response

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

***

## Error Reference

<Warning>
  **400 Bad Request** — A required field is missing or invalid. Check that `scriptId` and `customerPhone` are present. If the error message reads `Missing required script variables: brand_name`, add the `brand_name` field to your request body.
</Warning>

<Warning>
  **401 Unauthorized** — Your API key is missing or invalid. Verify that your `Authorization` or `X-API-Key` header is correctly set.
</Warning>