POST /calls — Create a phone call (v1)

This is version 1 of the endpoint. It is unchanged and keeps working. For a new integration, use version 2, which answers the same envelope as every other resource.

The Calls API places outbound phone calls programmatically. You provide a destination number and one of your workspace phone numbers; Verbeo dials the destination over that number’s LiveKit SIP trunk and connects your AI agent. You can pass dynamic variables that are injected into the agent’s system prompt at call time, so you can personalize each call without creating separate agents.

This endpoint requires a private API key (prefix vbr_). Public keys (vbr_pub_) are not accepted and return a 401 error.

Endpoint

POST https://api.verbeo.ai/calls

Request body

string

required

Destination phone number in E.164 format (e.g., "+1234567890").

string

required

The phone number to call from, in E.164 format. Must be an active phone number in your workspace.

string

UUID of the agent that will handle the call. Optional — if omitted, Verbeo uses the outbound agent configured on the fromNumber. If neither is set, the request returns 400.

object

Key-value pairs that are substituted into the agent’s system prompt at call time. Reference them in the prompt as {{variable_name}}. Values must be strings.

{
  "customer_name": "Jane Smith",
  "order_id": "ORD-98765"
}

The response returns immediately once the call is created — it does not wait for the destination to answer. The agent places the call in the background; track the outcome with the call_started / call_ended / call_analyzed webhooks.

Request

curl -X POST "https://api.verbeo.ai/calls" \
  -H "Authorization: Bearer vbr_your_private_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "toNumber": "+1234567890",
    "fromNumber": "+1987654321",
    "agentId": "550e8400-e29b-41d4-a716-446655440000",
    "dynamicVariables": {
      "customer_name": "Jane Smith",
      "order_id": "ORD-98765",
      "account_tier": "premium"
    }
  }'

curl -X POST "https://api.verbeo.ai/calls" \
  -H "Authorization: Bearer vbr_your_private_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "toNumber": "+1234567890",
    "fromNumber": "+1987654321"
  }'

const response = await fetch("https://api.verbeo.ai/calls", {
  method: "POST",
  headers: {
    Authorization: "Bearer vbr_your_private_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    toNumber: "+1234567890",
    fromNumber: "+1987654321",
    agentId: "550e8400-e29b-41d4-a716-446655440000",
    dynamicVariables: {
      customer_name: "Jane Smith",
      order_id: "ORD-98765",
    },
  }),
});
const call = await response.json();

import requests

response = requests.post(
    "https://api.verbeo.ai/calls",
    headers={
        "Authorization": "Bearer vbr_your_private_api_key",
        "Content-Type": "application/json",
    },
    json={
        "toNumber": "+1234567890",
        "fromNumber": "+1987654321",
        "agentId": "550e8400-e29b-41d4-a716-446655440000",
        "dynamicVariables": {
            "customer_name": "Jane Smith",
            "order_id": "ORD-98765",
        },
    },
)
call = response.json()

Response

The request returns 201 Created as soon as the call is created.

boolean

required

true when the call was created.

string

required

Verbeo UUID for this call. Use it to retrieve call details and correlate webhook events.

string

required

Call status. "queued" — the call has been created and is being placed.

string

required

The destination phone number as provided.

string

required

The phone number the call was placed from.

string

required

UUID of the agent handling the call (the resolved agent, whether you passed it or it came from the phone number).

string

required

Display name of the agent.

string

required

Human-readable confirmation message.

Example response

{
  "success": true,
  "callId": "772g0622-g41d-63f6-c938-668877662222",
  "status": "queued",
  "toNumber": "+1234567890",
  "fromNumber": "+1987654321",
  "agentId": "550e8400-e29b-41d4-a716-446655440000",
  "agentName": "Customer Support Agent",
  "message": "Outbound call created"
}

Error responses

Status	Error	Description
`400`	Missing required fields	`toNumber` or `fromNumber` was not provided
`400`	No agent specified	No `agentId` was passed and the `fromNumber` has no outbound agent configured
`401`	Unauthorized	API key is invalid, expired, or is a public key
`402`	Insufficient balance	Your balance is below the amount needed to start a call — add funds on the Billing page
`403`	Account paused	Billing is paused — contact support@verbeo.ai
`404`	Not found	The specified agent or phone number does not exist in your workspace
`429`	Concurrency limit reached	You have reached the maximum number of simultaneous calls for your plan — wait for active calls to complete or upgrade
`502`	Failed to initiate call	The telephony provider could not place the call

To personalize calls at scale, define placeholder tokens like {{customer_name}} in your agent’s system prompt and pass the actual values through dynamicVariables on each call. The agent sees the resolved values during the conversation.

Overview

Assistants

Tools

Phone Numbers

Calls

Campaigns

Webhooks

POST /calls — Create a phone call (v1)

Endpoint

Request body

Request

Response

Example response

Error responses

​Endpoint

​Request body

​Request

​Response

​Example response

​Error responses

Endpoint

Request body

Request

Response

Example response

Error responses