Start Outbound Call

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 for the full setup.

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.

Request

string

required

UUID of the outbound phone number to dial from.

string

required

Destination number in E.164 format (e.g. +971501234567).

string

required

UUID of the agent that will drive the conversation.

integer

default:"100"

Maximum call duration in seconds. The call is force-terminated when this elapses.

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.

Code examples

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"
    }
  }'

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);

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"]

Sample response

{
  "sessionId": "4981804c-2658-4893-84ff-9c2fa90fb3c2"
}

The same sessionId flows in session.created / session.ended webhooks and is the path parameter for GET /api/v1/chat/sessions/{sessionId}.

For high-volume outbound calling, use Call Campaigns instead — they manage retries, scheduling, and contact lists automatically.

Overview

Agents

Chat

Voice

Tools

Phone Numbers

Start Outbound Call

Request

Code examples

Sample response

​Request

​Code examples

​Sample response

Request

Code examples

Sample response