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

# Start Outbound Call

> Initiate an outbound voice call from a provisioned number to a target phone number.

<Note>
  Every endpoint on this page requires either a Clerk-issued JWT (`Authorization: Bearer <token>`) or
  an organization API key (`x-api-key: pk_…`). Anonymous calls return `401 Unauthorized`. See
  [Authentication](/authentication) for the full setup.
</Note>

<Note>
  The `agent_id` must belong to a voice-enabled agent. The `phone_number_id` must be a provisioned outbound number in your organization — list them with [`GET /api/v1/phone-numbers`](/api-reference/phone-numbers/list).
</Note>

## Request

<ParamField path="phone_number_id" type="string" required>
  UUID of the outbound phone number to dial from.
</ParamField>

<ParamField body="to_phone_number" type="string" required>
  Destination number in E.164 format (e.g. `+971501234567`).
</ParamField>

<ParamField body="agent_id" type="string" required>
  UUID of the agent that will drive the conversation.
</ParamField>

<ParamField body="ttl" type="integer" default="100">
  Maximum call duration in seconds. The call is force-terminated when this elapses.
</ParamField>

<ParamField body="session_variables" type="object">
  Free-form key/value map. Every key is available as `{{key}}` in the system prompt **and** is echoed back verbatim in webhooks regardless of whether the prompt referenced it. Use this for both prompt context and correlation IDs. See [Session variables](/guides/session-variables).
</ParamField>

## Code examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST 'https://api.agntix.ai/api/v1/phone-numbers/fba8677f-e464-4362-ba4f-55bbdc3dab94/calls/start' \
    -H "x-api-key: $AGNTIX_API_KEY" \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
      "to_phone_number": "+971501234567",
      "agent_id": "d796c919-7ef3-413a-8bf1-351b6442953a",
      "ttl": 180,
      "session_variables": {
        "customerName": "Alex Morgan",
        "contextSummary": "Order #88291, placed 2026-05-09, status shipped, ETA 2026-05-14",
        "objective": "Confirm delivery slot and capture preferred time",
        "crmContactId": "CRM-7728"
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const phoneNumberId = "fba8677f-e464-4362-ba4f-55bbdc3dab94";

  const res = await fetch(
    `https://api.agntix.ai/api/v1/phone-numbers/${phoneNumberId}/calls/start`,
    {
      method: "POST",
      headers: {
        "x-api-key": process.env.AGNTIX_API_KEY,
        "Content-Type": "application/json",
        Accept: "application/json",
      },
      body: JSON.stringify({
        to_phone_number: "+971501234567",
        agent_id: "d796c919-7ef3-413a-8bf1-351b6442953a",
        ttl: 180,
        session_variables: {
          customerName: "Alex Morgan",
          contextSummary:
            "Order #88291, placed 2026-05-09, status shipped, ETA 2026-05-14",
          objective: "Confirm delivery slot and capture preferred time",
          crmContactId: "CRM-7728",
        },
      }),
    },
  );
  const { sessionId } = await res.json();
  console.log("Session:", sessionId);
  ```

  ```python Python theme={null}
  import os, requests

  phone_number_id = "fba8677f-e464-4362-ba4f-55bbdc3dab94"

  res = requests.post(
      f"https://api.agntix.ai/api/v1/phone-numbers/{phone_number_id}/calls/start",
      headers={
          "x-api-key": os.environ["AGNTIX_API_KEY"],
          "Content-Type": "application/json",
          "Accept": "application/json",
      },
      json={
          "to_phone_number": "+971501234567",
          "agent_id": "d796c919-7ef3-413a-8bf1-351b6442953a",
          "ttl": 180,
          "session_variables": {
              "customerName": "Alex Morgan",
              "contextSummary": "Order #88291, placed 2026-05-09, status shipped, ETA 2026-05-14",
              "objective": "Confirm delivery slot and capture preferred time",
              "crmContactId": "CRM-7728",
          },
      },
  )
  session_id = res.json()["sessionId"]
  ```
</CodeGroup>

## Sample response

```json theme={null}
{
  "sessionId": "4981804c-2658-4893-84ff-9c2fa90fb3c2"
}
```

The same `sessionId` flows in [`session.created` / `session.ended` webhooks](/webhooks/events) and is the path parameter for [`GET /api/v1/chat/sessions/{sessionId}`](/api-reference/chat/sessions/get).

<Tip>
  For high-volume outbound calling, use [Call Campaigns](/guides/call-campaigns) instead — they manage retries, scheduling, and contact lists automatically.
</Tip>