Place an outbound phone call

POST /api/v1/call

Place an outbound phone call. Credentials are passed inline — no dashboard pre-configuration required. The request returns immediately with a callId; the actual dial happens asynchronously and the call's lifecycle lands on the calls history row.

Authentication

Standard API key required:

X-API-Key: zsk_...

Request body

The request body is discriminated by type. For outbound, send type: "outbound".

Lifecycle webhook and AI-summary toggle live inside the agent config (webhook / enableSummarization — see Webhooks). For per-call variations of a saved agent, fetch its config, tweak it, and send it inline as agent.

callConfig

Discriminated by provider. Each provider has a different auth shape.

auth shape by provider

{
  "accountSid": "AC...",
  "authToken":  "..."
}

{
  "authId":        "MA_...",
  "authToken":     "...",
  "applicationId": "30378500269436896"
}

{ "authId": "MA...", "authToken": "..." }

{
  "apiKey":        "...",
  "apiSecret":     "...",
  "applicationId": "...",
  "privateKey":    "..."
}

{ "apiKey": "KEY...", "connectionId": "..." }

{ "provider": "smartflo", "phoneNumber": "+91..." }

Response

Returns HTTP 201 Created.

{
  "callId": "call_4e4e571f8c9b3cf8e99d",
  "status": "initiated"
}

callId is stable for the lifetime of the call and the history row. The provider's own call SID (Twilio CallSid, Vobiz call_uuid) gets stamped onto providerCallSid once the provider accepts the dial.

Examples

curl -X POST https://dashboard.zoxa.ai/api/v1/call \
  -H "X-API-Key: zsk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "outbound",
    "callConfig": {
      "provider": "twilio",
      "phoneNumber": "+14155550100",
      "auth": { "accountSid": "AC...", "authToken": "..." }
    },
    "toNumber": "+14155559999",
    "agentId": "550e8400-e29b-41d4-a716-446655440000",
    "contextVariables": { "customerName": "Aman" }
  }'

const res = await fetch("https://dashboard.zoxa.ai/api/v1/call", {
  method: "POST",
  headers: {
    "X-API-Key": "zsk_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    type: "outbound",
    callConfig: {
      provider: "twilio",
      phoneNumber: "+14155550100",
      auth: { accountSid: "AC...", authToken: "..." },
    },
    toNumber: "+14155559999",
    agentId: "550e8400-e29b-41d4-a716-446655440000",
    contextVariables: { customerName: "Aman" },
  }),
});

if (!res.ok) {
  console.error(res.status, await res.json());
} else {
  const { callId } = await res.json();
  console.log("Call placed:", callId);
}

import httpx

resp = httpx.post(
    "https://dashboard.zoxa.ai/api/v1/call",
    headers={"X-API-Key": "zsk_..."},
    json={
        "type": "outbound",
        "callConfig": {
            "provider": "twilio",
            "phoneNumber": "+14155550100",
            "auth": {"accountSid": "AC...", "authToken": "..."},
        },
        "toNumber": "+14155559999",
        "agentId": "550e8400-e29b-41d4-a716-446655440000",
        "contextVariables": {"customerName": "Aman"},
    },
    timeout=30,
)
resp.raise_for_status()
print("Call placed:", resp.json()["callId"])

With an inline transient agent (no saved record)

curl -X POST https://dashboard.zoxa.ai/api/v1/call \
  -H "X-API-Key: zsk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "outbound",
    "callConfig": {
      "provider": "vobiz",
      "phoneNumber": "+917971542879",
      "auth": { "authId": "MA_...", "authToken": "..." }
    },
    "toNumber": "+919755857161",
    "agent": {
      "name": "Support bot",
      "systemPrompt": "You are a friendly support agent. Keep replies short.",
      "languages": ["en"],
      "greeting": { "firstMessages": ["Hi! How can I help today?"] },
      "llm": { "provider": "openai", "model": "gpt-5.4-mini" },
      "tts": { "provider": "elevenlabs" },
      "stt": { "provider": "soniox", "interruptionMinWords": 2 }
    }
  }'

await fetch("https://dashboard.zoxa.ai/api/v1/call", {
  method: "POST",
  headers: {
    "X-API-Key": "zsk_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    type: "outbound",
    callConfig: {
      provider: "vobiz",
      phoneNumber: "+917971542879",
      auth: { authId: "MA_...", authToken: "..." },
    },
    toNumber: "+919755857161",
    agent: {
      name: "Support bot",
      systemPrompt: "You are a friendly support agent. Keep replies short.",
      languages: ["en"],
      greeting: { firstMessages: ["Hi! How can I help today?"] },
      llm: { provider: "openai", model: "gpt-5.4-mini" },
      tts: { provider: "elevenlabs" },
      stt: { provider: "soniox", interruptionMinWords: 2 },
    },
  }),
});

import httpx

httpx.post(
    "https://dashboard.zoxa.ai/api/v1/call",
    headers={"X-API-Key": "zsk_..."},
    json={
        "type": "outbound",
        "callConfig": {
            "provider": "vobiz",
            "phoneNumber": "+917971542879",
            "auth": {"authId": "MA_...", "authToken": "..."},
        },
        "toNumber": "+919755857161",
        "agent": {
            "name": "Support bot",
            "systemPrompt": "You are a friendly support agent. Keep replies short.",
            "languages": ["en"],
            "greeting": {"firstMessages": ["Hi! How can I help today?"]},
            "llm": {"provider": "openai", "model": "gpt-5.4-mini"},
            "tts": {"provider": "elevenlabs"},
            "stt": {"provider": "soniox", "interruptionMinWords": 2},
        },
    },
    timeout=30,
)

Varying a saved agent for one call

There is no per-call override field — a call runs either a saved agent as-is (agentId) or a full inline config (agent). For most per-call variation, contextVariables is the right tool: keep {{placeholders}} in the saved prompt and greeting, and fill them per call.

When you genuinely need different config (say, another voice) for one call, fetch the saved config, tweak it, and send it inline:

const { config } = await fetch(`https://dashboard.zoxa.ai/api/v1/agents/${agentUuid}`, {
  headers: { "X-API-Key": "zsk_..." },
}).then((r) => r.json());

config.greeting.firstMessages = ["Hi Aman — calling about your appointment."];
config.llm.temperature = 0.7;

await fetch("https://dashboard.zoxa.ai/api/v1/call", {
  method: "POST",
  headers: { "X-API-Key": "zsk_...", "Content-Type": "application/json" },
  body: JSON.stringify({ type: "outbound", callConfig, toNumber: "+14155559999", agent: config }),
});

The saved agent is untouched; the call's history row snapshots exactly what ran.

Using a saved telephony configuration

Instead of inline credentials, reference a telephony configuration saved in the dashboard by its id:

{
  "type": "outbound",
  "telephonyConfigurationId": 12,
  "toNumber": "+14155559999",
  "agentId": "550e8400-e29b-41d4-a716-446655440000"
}

The saved configuration supplies the provider, credentials, and outbound phoneNumber. Send telephonyConfigurationId or callConfig — not both.

Errors

The provider may still fail the call after the 201 (number busy, no answer, carrier reject). Those land asynchronously on the calls row as connectionStatus via the provider's status callback — query GET /calls/{callId} for the final outcome.

Error response shapes

Schema and cross-field validation failures return 400. The detail is an object: a top-level error summary plus a flat details list, one entry per failed field (path is the dot-joined field location, type is the Pydantic error code):

{
  "detail": {
    "error": "Agent configuration validation failed",
    "details": [
      {
        "path": "phone_number",
        "message": "Extra inputs are not permitted",
        "type": "extra_forbidden"
      },
      {
        "path": "agentId",
        "message": "Input should be a valid UUID, version 4",
        "type": "uuid_parsing"
      }
    ]
  }
}

Every other error is a single string under detail — including the 422 off-catalog-model error:

{ "detail": "invalid_credentials: authentication failed" }

The provider_rejected (400/502) and concurrency_limit_reached (429) errors carry their own structured objects under detail — see those rows in the table above.

What zoxaAI does after the 201

1. Writes the calls row with transport=outbound, callSource=api_outbound, status=pending, and the resolved agent snapshot. The raw POST body is stored under telephony_snapshot._rawRequest (with callConfig.auth stripped) for audit.
2. Builds two provider URLs:
   • Answer URL — https://dashboard.zoxa.ai/api/v1/telephony/run?call_id={callId}. The provider POSTs here when the callee answers; the response is TwiML/NCCO that opens a media stream to our agent.
   • Status URL — https://dashboard.zoxa.ai/api/v1/telephony/{provider}/status/by-call/{callId}. The provider POSTs lifecycle events here (initiated → ringing → answered → completed, or busy/no-answer/failed).
3. Issues the dial to the provider with both URLs attached and the inline credentials.
4. If the provider rejects the dial (e.g. invalid number format), the calls row is marked error with connectionStatus="dial_failed" (endedReason stays null — the call never connected) and a 500-class error is surfaced — though most dial failures happen async and arrive via the status URL.

Lifecycle states

The calls row transitions through these status values:

A typical successful outbound transitions pending → active → completed. A no-answer transitions pending → error with connectionStatus: no_answer (no active because the call never connected).

Polling for completion

There's no synchronous wait endpoint — poll GET /calls/{callId} until status is completed or error.

CALL_ID=$(curl -s -X POST https://dashboard.zoxa.ai/api/v1/call \
  -H "X-API-Key: zsk_..." \
  -H "Content-Type: application/json" \
  -d '{ /* ... */ }' | jq -r .callId)

while true; do
  STATUS=$(curl -s "https://dashboard.zoxa.ai/api/v1/calls/$CALL_ID" \
    -H "X-API-Key: zsk_..." | jq -r .status)
  echo "status=$STATUS"
  [[ "$STATUS" == "completed" || "$STATUS" == "error" ]] && break
  sleep 5
done

async function pollForCompletion(callId, intervalMs = 5000, timeoutMs = 600_000) {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const res = await fetch(`https://dashboard.zoxa.ai/api/v1/calls/${callId}`, {
      headers: { "X-API-Key": "zsk_..." },
    });
    const call = await res.json();
    if (call.status === "completed" || call.status === "error") return call;
    await new Promise((r) => setTimeout(r, intervalMs));
  }
  throw new Error("Timed out waiting for call completion");
}

import time, httpx

def poll_for_completion(call_id: str, interval_s: float = 5, timeout_s: float = 600):
    deadline = time.monotonic() + timeout_s
    while time.monotonic() < deadline:
        call = httpx.get(
            f"https://dashboard.zoxa.ai/api/v1/calls/{call_id}",
            headers={"X-API-Key": "zsk_..."},
        ).json()
        if call["status"] in ("completed", "error"):
            return call
        time.sleep(interval_s)
    raise TimeoutError("Call did not complete in time")

Idempotency

POST /call with type=outbound is not idempotent. Each request places a new dial. If you need exactly-once semantics, dedupe on your side with a client-generated request key and a database constraint before calling this endpoint.

Variable substitution

{{key}} placeholders are substituted at runtime (when the call connects), not at request time. The stored config_snapshot keeps the raw placeholders so the saved snapshot mirrors your API payload 1:1 — useful for debugging in the call-history UI.

Scope: recursive across every string field in the snapshot. Covered surfaces include systemPrompt, greeting.firstMessages, every inline tool's description, HTTP-tool server.url / server.headers (values) / request body, query-tool KB names/descriptions, endCall customMessages, transferCall destination and customMessage, and webhook.url. Single-pass — values containing their own {{...}} are not re-expanded.

Sources, in precedence order (lowest → highest)

1. The agent's saved contextVariables — defaults. An explicitly-saved blank renders empty (it never leaks the literal {{token}}).

2. This request's contextVariables — override a saved default only when non-blank; sending "" falls back to the saved default.

3. System built-ins — always win and can never be shadowed:

   Variable	Outbound calls	Inbound calls	Web / WebSocket
   {{user_number}}	toNumber (the human being dialed)	the caller's number	empty string
   {{agent_number}}	callConfig.phoneNumber (your DID)	your DID	empty string
   {{current_time}} / {{current_date}} / {{current_day}} / {{current_timezone}}	resolved against the config's timezone	same	same

   The intuition: user_number is always the end-user's phone, regardless of who initiated the call; agent_number is the platform-side DID.

Placeholders for keys in no source are left as-is in the string — deliberate, so a typo doesn't silently blank a URL. Key matching is case- and space-insensitive: customerName, customername, and customer name all fill {{customerName}}.

Example

{
  "type": "outbound",
  "callConfig": { "provider": "twilio", "auth": { "...": "..." }, "phoneNumber": "+19014463176" },
  "toNumber": "+14155551234",
  "agent": {
    "name": "Order lookup bot",
    "systemPrompt": "You're calling {{customerName}}.",
    "llm": { "provider": "openai", "model": "gpt-5.4-mini" },
    "tools": [{
      "type": "function",
      "name": "lookup_order",
      "description": "Look up the caller's open orders.",
      "config": {
        "server": {
          "url": "https://api.acme.com/orders?phone={{user_number}}",
          "method": "GET"
        }
      }
    }]
  },
  "contextVariables": { "customerName": "Aman" }
}

At runtime: {{customerName}} resolves to "Aman" (from contextVariables); {{user_number}} resolves to "+14155551234" (the dialed human on this outbound call). The HTTP tool's URL is rewritten before the request goes out.

Related

• POST /call (inbound) — register a number for inbound routing
• GET /calls/{callId} — fetch call lifecycle, transcript, recordings
• Agent Config schema — full inline-agent shape
• Webhook Events — agent.webhook lifecycle payload