Recipes

Place an AI agent call

Written beside the API’s code, and read from it every hour.

Have one of your AI agents call one person: a reminder, a confirmation, a callback, a notice.

Pick an agent. GET /v1/agents lists them. It must be active, with outgoing_calls on (the Outgoing calls switch on the agent's Persona tab).
Place the call with who to call and why. The answer is 202 once the call is placed. Send an Idempotency-Key header, your own id for the request, so a retry after a timeout gets the same call instead of placing a second one.
Get the outcome. The agent greets, says the purpose, and handles the answer with its own jobs. It reports how it went the way it reports every message: through the message delivery and message action set on the agent in the portal, marked with your reference.

# 1. Find an agent that may place calls
curl https://api.vocatech.com/v1/agents \
  -H "Authorization: Bearer $VOCATECH_API_KEY"

# 2. Have it call one person (the Idempotency-Key makes a retry safe)
curl -X POST https://api.vocatech.com/v1/agents/7/calls \
  -H "Authorization: Bearer $VOCATECH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: visit-20260925-0900" \
  -d '{
    "to": "7185550142",
    "purpose": "confirm the Friday 9 AM visit",
    "person_name": "Jordan Reyes",
    "reference": "visit-20260925-0900"
  }'

import { vt } from './vocatech.mjs';

// 1. An agent that is on and may place calls
const { agents } = await vt('GET', '/v1/agents');
const agent = agents.find((a) => a.active && a.outgoing_calls);

// 2. One call, to one person
const { call } = await vt('POST', `/v1/agents/${agent.id}/calls`, {
  to: '7185550142',
  purpose: 'confirm the Friday 9 AM visit',
  person_name: 'Jordan Reyes',
  reference: 'visit-20260925-0900',
});
console.log(call.call_sid, call.state); // 202: placed

from vocatech import vt

# 1. An agent that is on and may place calls
agents = vt("GET", "/v1/agents")["agents"]
agent = next(a for a in agents if a["active"] and a["outgoing_calls"])

# 2. One call, to one person
call = vt("POST", f"/v1/agents/{agent['id']}/calls", {
    "to": "7185550142",
    "purpose": "confirm the Friday 9 AM visit",
    "person_name": "Jordan Reyes",
    "reference": "visit-20260925-0900",
})["call"]
print(call["call_sid"], call["state"])  # 202: placed

<?php
require __DIR__ . '/vocatech.php';

// 1. An agent that is on and may place calls
$agents = vt('GET', '/v1/agents')['agents'];
$agent = current(array_filter($agents, fn ($a) => $a['active'] && $a['outgoing_calls']));

// 2. One call, to one person
$call = vt('POST', "/v1/agents/{$agent['id']}/calls", [
    'to'          => '7185550142',
    'purpose'     => 'confirm the Friday 9 AM visit',
    'person_name' => 'Jordan Reyes',
    'reference'   => 'visit-20260925-0900',
])['call'];
echo $call['call_sid'], ' ', $call['state'], PHP_EOL; // 202: placed

GET /v1/agents response200 OK

{
  "agents": [
    {
      "id": 7,
      "name": "Front desk",
      "extension": "850",
      "active": true,
      "outgoing_calls": true,
      "provisioned": true
    }
  ],
  "meta": { "total": 1 }
}

POST /v1/agents/7/calls response202 Accepted

{
  "call": {
    "call_sid": "5d7e9a1c-3b2f-4c8e-a6d0-9f1b2c3d4e5f",
    "agent_id": 7,
    "from": "7185550100",
    "to": "7185550142",
    "state": "trying",
    "kind": "notice",
    "purpose": "confirm the Friday 9 AM visit",
    "reference": "visit-20260925-0900"
  }
}

One call per request. This is not a bulk dialer.
The agent calls inside its calling hours only: 8 AM to 9 PM in the agent's time zone, unless you changed them on its Persona tab. Outside them the call is refused with 422. Send "allow_quiet_hours": true to place it anyway.
to is a 10-digit US or Canadian number, or an extension of 2 to 6 digits.
It never dials 911 or another N11 service code, 933 or 988, a premium number (900 or 976), or an area code that belongs to another country, such as those in the Caribbean. US territories are fine.
Each key may place 10 agent calls a minute and 500 a day.

Before thisLook up a caller Next Open a support ticket