# Place an AI agent call

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

1. **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).
2. **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.
3. **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`.

**curl**

```bash
# 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"
  }'
```

**Node**

```javascript
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
```

**Python**

```python
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**

```php
<?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 OKCopy**

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

**POST /v1/agents/7/calls response202 AcceptedCopy**

```json
{
  "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.