By area
AI agents
Read from the API’s own reference file every hour.
Your AI agents: one outgoing call through one of them, where it stands, steering it while it is up, and the account's do-not-call list.
List AI agents
GET/v1/
Your AI agents, with what you need to pick one for POST /v1/agents/{id}/calls. Agents are set up in the portal. An agent can place calls only when active and outgoing_calls are both true.
Keys with the agents scope can call this route.
Request
curl https://api.vocatech.com/v1/agents \
-H "Authorization: Bearer YOUR_API_KEY"const res = await fetch("https://api.vocatech.com/v1/agents", {
headers: { Authorization: "Bearer YOUR_API_KEY" },
});
console.log(res.status, await res.json());import requests
r = requests.get(
"https://api.vocatech.com/v1/agents",
headers={"Authorization": "Bearer YOUR_API_KEY"},
timeout=30,
)
print(r.status_code, r.json())<?php
require 'vendor/autoload.php';
$client = new GuzzleHttp\Client([
'base_uri' => 'https://api.vocatech.com',
'headers' => ['Authorization' => 'Bearer YOUR_API_KEY'],
'http_errors' => false,
]);
$res = $client->get('/v1/agents');
echo $res->getStatusCode(), PHP_EOL, $res->getBody(), PHP_EOL;Answers
| Field | Type | Description |
|---|---|---|
agents required | array of objects | |
agents[]. required | integer | Use it with POST /v1/agents/{id}/calls. |
agents[]. required | string | |
agents[]. required | string | The agent's extension. |
agents[]. required | boolean | The agent is switched on. |
agents[]. required | boolean | The agent's Outgoing calls switch is on. It must be on to place calls. |
agents[]. required | boolean | The agent is set up on the phone system. |
meta required | object | |
meta. required | integer |
{
"agents": [
{
"id": 12,
"name": "Front Desk",
"extension": "150",
"active": true,
"outgoing_calls": true,
"provisioned": true
}
],
"meta": {
"total": 1
}
}Retry-After seconds. The body names the counter, the window and the limit.| Header | Type | Description |
|---|---|---|
Retry-After | integer | Seconds to wait before you try again. |
Retry-After: 5), or a service this route needs could not be reached.| Header | Type | Description |
|---|---|---|
Retry-After | integer | Seconds to wait before you try again. |
Place an outgoing AI agent call
POST/v1/
Your AI agent places one outgoing call: a reminder, a confirmation, a callback, a notice. The agent opens with its outgoing greeting, says the purpose, and handles the answer with the jobs it has. A job that changes an appointment files the change.
A call for someone ("kind": "errand") is the order Callpop's Call for me sends: the company's number in to, one description in about (what the call is about and what it needs to do, with anything the agent may give when asked, like an account number), for_name (whom the agent calls for) and mode. With "mode": "person" (Get me a person, the default) the agent gets through the phone menu and the hold and rings connect_to, an extension or a 10-digit number, the moment a live person answers; picking up joins the call. With "mode": "handle" (Handle it for me) the agent works the matter in the description and reports back. It is placed now or not at all, at the company's own hours, so the agent's calling hours, allow_quiet_hours and queue_if_quiet do not apply to it.
The outcome reaches you the way every message from the agent does: through the agent's message delivery and message action, opening with a tag that names your reference.
Rules.
- One call per request. This is not a bulk dialer.
tois a 10-digit US or Canadian number, or an extension of 2 to 6 digits. Never an emergency or service number (911 and the other N11 codes, 933, 988), a premium number (900, 976), or an area code that is another country.- The agent must be on, and its Outgoing calls switch must be on (in the portal, under Persona, Outgoing calls).
- A call outside the agent's own calling hours (8 AM to 9 PM in the agent's time zone unless its Persona tab says otherwise) is refused unless
allow_quiet_hoursis true. - Send
purposeorinstructions, or both. A call for someone sendsaboutinstead. - An agent places at most 50 calls a day (or the cap set on it); past that the request is refused (
422) until the next day. - Outreach (every
salescall, and a notice or callback sent withoutreach: true): the call is placed only between 9 AM and 5 PM in the called number's own time zone, Monday to Friday (queue_if_quietholds it for the next window instead of a refusal). The agent opens by saying which business is calling; it says a disclosure first when the agent's Outgoing calls card has its box ticked, in the words written there. Asalescall listens first: it works a phone menu to the front desk, waits out a hold of up to five minutes, and says its opening to the first live person. - Whom you call is yours to answer for. The platform does not check whether a number is a mobile line. You decide whom your agent calls and what your calls must say, as with any calling you do;
consentrecords your own statement that the person agreed. - The do-not-call list: a number on your list (
GET /v1/agents/do-not-call) is never called, by any kind of call. The agent puts a number there itself when the person asks on a sales call. - Your system is on the call:
GET /v1/agents/{id}/calls/{call}reads where it stands,POST .../say,/connect,/messageand/endsteer it while a person is on the line, and theagent.call.started,agent.call.statusandagent.call.endedwebhooks tell you as it goes.
The answer is 202 once the call is placed. state is the first state the phone system reported.
A retry is safe with an Idempotency-Key. Send the header, your own id for the request (up to 80 characters): a repeat within a day answers the same call (202, the same call_sid) instead of placing a second one. Without it, the same agent, to and reference within two minutes is treated as the same request. A 502 means the platform did not answer and the call may have been placed: check for the placed-call tag before you retry, or retry with the same key.
Keys with the agents scope can call this route.
Request
curl -X POST https://api.vocatech.com/v1/agents/12/calls \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "7185550142",
"purpose": "Confirm the Friday 10 AM appointment",
"person_name": "Jordan Reyes",
"reference": "appt-2291",
"kind": "notice"
}'const res = await fetch("https://api.vocatech.com/v1/agents/12/calls", {
method: "POST",
headers: {
Authorization: "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
to: "7185550142",
purpose: "Confirm the Friday 10 AM appointment",
person_name: "Jordan Reyes",
reference: "appt-2291",
kind: "notice",
}),
});
console.log(res.status, await res.json());import requests
r = requests.post(
"https://api.vocatech.com/v1/agents/12/calls",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={
"to": "7185550142",
"purpose": "Confirm the Friday 10 AM appointment",
"person_name": "Jordan Reyes",
"reference": "appt-2291",
"kind": "notice",
},
timeout=30,
)
print(r.status_code, r.json())<?php
require 'vendor/autoload.php';
$client = new GuzzleHttp\Client([
'base_uri' => 'https://api.vocatech.com',
'headers' => ['Authorization' => 'Bearer YOUR_API_KEY'],
'http_errors' => false,
]);
$res = $client->post('/v1/agents/12/calls', [
'json' => [
'to' => '7185550142',
'purpose' => 'Confirm the Friday 10 AM appointment',
'person_name' => 'Jordan Reyes',
'reference' => 'appt-2291',
'kind' => 'notice',
],
]);
echo $res->getStatusCode(), PHP_EOL, $res->getBody(), PHP_EOL;Parameters
| Name | In | Type | Description |
|---|---|---|---|
id required | path | integer | The agent's id, from GET /v1/agents. For example 12. |
Idempotency-Key | header | string | Your own id for this request, up to 80 characters. A repeat within a day answers the same call instead of placing a second one. Up to 80 characters. For example visit-20260925-0900. |
Body
| Field | Type | Description |
|---|---|---|
to required | string | Who to call: a 10-digit US or Canadian number, or an extension of 2 to 6 digits; a call for someone goes to a company's 10-digit number. Punctuation and a leading 1 are ignored. For example 7185550142. |
purpose | string | Why the agent is calling, in one line. It says this after its greeting. Longer text is cut to 200 characters. Up to 200 characters. |
subject | string | Another name for purpose. |
instructions | string | More for the agent to know or do on this call. Longer text is cut to 2,000 characters. Up to 2,000 characters. |
details | string | Background for the questions the person may ask once they have heard the message (what was found, what was done, what to try). The agent answers from it in plain words, one thing at a time, and never reads it out as written; when they ask something it does not cover, it says so and offers a person. Longer text is cut to 4,000 characters. Up to 4,000 characters. |
person_name | string | The name of the person being called. Cut to 80 characters. Up to 80 characters. |
reference | string | Your own id for this call, echoed in the agent's message about it. Letters, digits, dots, dashes, colons and underscores. Matches ^[A-Za-z0-9._:-]{1,80}$. |
job | string | The name of the agent job the call starts with. Cut to 80 characters. Up to 80 characters. |
kind | string | notice tells the person something. callback answers something they asked for. sales is a sales call the agent's Sales job runs (send job); it is outreach, see below. errand is a call for someone, the order Callpop's Call for me sends (send about, for_name and mode). Any other value reads as notice. One of notice, callback, sales or errand. Default notice. |
about | string | For a call for someone: one description of what the call is about and what it needs to do, with anything the agent may give when asked (an account number, a service address). Its first sentence is the call's purpose. Required with kind errand. Longer text is cut to 1,000 characters. Up to 1,000 characters. |
mode | string | For a call for someone. person (Get me a person) rings connect_to the moment a live person answers, and picking up joins the call; the agent apologizes to the company when nobody picks up within fifteen seconds. handle (Handle it for me) has the agent work the matter in about and report back. One of person or handle. Default person. |
for_name | string | For a call for someone: whom the agent calls for ("Hi, this is Dina's assistant"). Required with kind errand. Cut to 80 characters. Up to 80 characters. |
allow_quiet_hours | boolean | Allow a call outside the agent's own calling hours (8 AM to 9 PM in its time zone unless its Persona tab says otherwise). It never opens the called number's own hours on an outreach call. Default false. |
outreach | boolean | The call is outreach: it is placed only between 9 AM and 5 PM in the called number's own time zone on a business day (Monday to Friday), and never to a number on your do-not-call list. Every sales call is outreach. Default false. |
consent | boolean | Your statement that the person agreed to be called. It is kept on the call; the platform does not check line types, and you answer for whom you call. Default false. |
queue_if_quiet | boolean | An outreach call outside the called number's hours is held for the next window instead of refused: the answer is 202 with state: queued and not_before, and agent.call.started says when it goes. Default false. |
from_number | string | One of your account's numbers, 10 digits: the number to show the person called. Another number is refused (422). The phone system stamps the trunk's main number on the way out today; the request is checked and recorded so it is honored the day the switch allows it. |
connect_to | string | An extension of 2 to 6 digits or a 10-digit number: who POST .../connect rings when you do not name one in the request. On a call for someone it is the person's own number or extension, rung the moment a person answers (mode person, where it is required) or when the company will only deal with them. |
business | string | Your business's name as the agent says it in the opening. Your account's name unless you send one. Cut to 80 characters. Up to 80 characters. |
{
"to": "7185550142",
"purpose": "Confirm the Friday 10 AM appointment",
"person_name": "Jordan Reyes",
"reference": "appt-2291",
"kind": "notice"
}Answers
| Field | Type | Description |
|---|---|---|
call required | object | |
call. required | string | The id of the placed call. |
call. required | integer | |
call. required | string | The number the call comes from. |
call. required | string | |
call. required | string | The first state the phone system reported, for example trying; queued when queue_if_quiet held the call for the called number's next window (then not_before says when, and call_sid is empty until it goes). |
call. | string | On a queued call, when the window opens (ISO 8601). |
call. required | string | One of notice, callback or sales. |
call. required | string | |
call. required | string | |
call. | boolean | The call is outreach (every sales call, and a notice or callback sent with outreach). |
{
"call": {
"call_sid": "c7d2e9a4-1f3b-4c8e-9a6d-0b5e2f7c1a93",
"agent_id": 12,
"from": "7185550100",
"to": "7185550142",
"state": "trying",
"kind": "notice",
"purpose": "Confirm the Friday 10 AM appointment",
"reference": "appt-2291"
}
}Example body
{
"error": {
"code": 400,
"type": "BAD_REQUEST",
"message": "The agent id must be a number."
}
}Example body
{
"error": {
"code": 404,
"type": "NOT_FOUND",
"message": "No agent with that id on this account."
}
}Example bodies
{
"error": {
"code": 422,
"type": "UNPROCESSABLE_ENTITY",
"message": "Outgoing calls are switched off on this agent. Turn them on under Persona, Outgoing calls."
}
}{
"error": {
"code": 422,
"type": "UNPROCESSABLE_ENTITY",
"message": "to is required: the number to call, or an extension."
}
}{
"error": {
"code": 422,
"type": "UNPROCESSABLE_ENTITY",
"message": "to may not be an emergency or service number."
}
}{
"error": {
"code": 422,
"type": "UNPROCESSABLE_ENTITY",
"message": "purpose or instructions is required: the agent has to know why it is calling."
}
}{
"error": {
"code": 422,
"type": "UNPROCESSABLE_ENTITY",
"message": "This agent is switched off."
}
}dial counter is full (10 a minute, 500 a day per key), or another request limit was reached. Wait Retry-After seconds.| Header | Type | Description |
|---|---|---|
Retry-After | integer | Seconds to wait before you try again. |
Example body
{
"error": "Rate limit exceeded",
"period": "minute",
"limit": 10,
"counter": "dial",
"retry_after": 42
}Idempotency-Key.Example body
{
"error": {
"code": 502,
"type": "ERROR",
"message": "The agent platform did not answer. The call may have been placed; check for the placed-call tag before you retry."
}
}| Header | Type | Description |
|---|---|---|
Retry-After | integer | Seconds to wait before you try again. |
Example body
{
"error": {
"code": 503,
"type": "ERROR",
"message": "Outgoing calls are not available right now."
}
}List the calls your system placed
GET/v1/
The calls your account's agents placed for your system in the last day that a person answered, newest first, each with its state (talking or ended), its outcome and its last line. A call nobody answered has no exchange yet: read it by its id with GET /v1/agents/{id}/calls/{call}.
Keys with the agents scope can call this route.
Request
curl "https://api.vocatech.com/v1/agents/calls?limit=10" \
-H "Authorization: Bearer YOUR_API_KEY"Parameters
| Name | In | Type | Description |
|---|---|---|---|
limit | query | integer | Default 20. From 1 to 50. |
Answers
| Field | Type | Description |
|---|---|---|
calls | array of objects | |
calls[]. | string | |
calls[]. | integer | |
calls[]. | string | |
calls[]. | string | |
calls[]. | string | |
calls[]. | string | |
calls[]. | string | |
calls[]. | integer | |
calls[]. | object | |
meta | object | |
meta. | integer | |
meta. | integer |
Where a placed call stands
GET/v1/
The call as it stands: queued (held for the called number's window), placing, placed (dialing, or nobody answered), talking (a person is on the line), ended, or failed with error. Once a person answered, exchange holds every line of the call so far: the agent's status lines (a person answered; a record filed, with how it ended; connecting; the call ended) and your own lines.
Keys with the agents scope can call this route.
Request
curl https://api.vocatech.com/v1/agents/12/calls/c7d2e9a4-1f3b-4c8e-9a6d-0b5e2f7c1a93 \
-H "Authorization: Bearer YOUR_API_KEY"Parameters
| Name | In | Type | Description |
|---|---|---|---|
id required | path | integer | |
call required | path | string | The call_sid the placing answer gave. |
Answers
| Field | Type | Description |
|---|---|---|
call required | object | |
call. | string | |
call. | integer | |
call. | string | queued, placing, placed (dialing, or nobody answered), talking (a person is on the line), ended, failed. |
call. | string | |
call. | string | |
call. | string | |
call. | string | |
call. | object | The lines of the call while it was up, once a person answered. |
call. | string | |
call. | string | |
call. | string | |
call. | string | |
call. | string | |
call. | array of objects | |
call. | integer | |
call. | string | agent (a status line) or person (your own line). |
call. | string | |
call. | string | |
call. | string | |
call. | string |
{
"call": {
"call_sid": "c7d2e9a4-1f3b-4c8e-9a6d-0b5e2f7c1a93",
"agent_id": 12,
"state": "talking",
"to": "7185550142",
"from": "7185550100",
"placed_at": "2026-11-02T15:00:02+00:00",
"error": "",
"exchange": {
"state": "open",
"outcome": "",
"summary": "your phones",
"opened_at": "2026-11-02T15:00:20+00:00",
"closed_at": "",
"lines": [
{
"id": 1,
"who": "agent",
"status": "started",
"text": "Calling Jordan Reyes now.",
"decision": "",
"at": "2026-11-02T15:00:20+00:00"
},
{
"id": 2,
"who": "agent",
"status": "person",
"text": "A person answered. The agent is talking to them.",
"decision": "",
"at": "2026-11-02T15:00:31+00:00"
}
]
}
}
}Steer a call while it is up
POST/v1/
Steer a call your system placed while a person is on the line, the way a person steers a call they ordered from the Callpop panel.
say{ "text": "..." }: the agent acts on your words with the person, in its own voice. It never reads them as a script and never says they were written. One thing at a time, a sentence or two.connect{ "to": "105" }: the agent says one line and rings the extension or 10-digit number, joining them to the call; it leaves once they join. With noto, the call'sconnect_to; when the call has none, the agent says so on the exchange.message: the agent wraps up: your office will call back; it takes a direct number and a good time as the call's message.end: the agent ends the call politely.
Each lands on the exchange the agent reads every few seconds. A call nobody has answered yet has no exchange: say, connect and message answer 409, try again once agent.call.status says a person answered. end before an answer hangs the call up at the phone system, still ringing or not, and answers "ended": true. Keys with the agents scope can call these routes.
Request
curl -X POST https://api.vocatech.com/v1/agents/12/calls/c7d2e9a4-1f3b-4c8e-9a6d-0b5e2f7c1a93/say \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "text": "Ask them whether they have a fax line." }'Parameters
| Name | In | Type | Description |
|---|---|---|---|
id required | path | integer | |
call required | path | string | |
action required | path | string | One of say, connect, message or end. |
Body
| Field | Type | Description |
|---|---|---|
text | string | For say (required) and message (optional). Up to 600 characters. Up to 600 characters. |
to | string | For connect. An extension of 2 to 6 digits or a 10-digit number. |
{
"text": "Ask them whether they have a fax line."
}Answers
| Field | Type | Description |
|---|---|---|
ok | boolean | |
call_sid | string | |
action | string | |
line_id | integer |
{
"ok": true,
"call_sid": "c7d2e9a4-1f3b-4c8e-9a6d-0b5e2f7c1a93",
"action": "say",
"line_id": 7
}Example body
{
"error": {
"code": 409,
"type": "CONFLICT",
"message": "That call is not one of yours, or the person has not answered yet."
}
}text or to is missing or not one the agent may dial.The do-not-call list
GET/v1/
The numbers none of your agents will call, whoever asks: your system through this API, the portal, the Callpop panel or an agent's own order. A call to one is refused with This number asked not to be called again. The agent itself puts a number on the list when the person asks on a sales call (source: sales).
Keys with the agents scope can call this route.
Answers
| Field | Type | Description |
|---|---|---|
numbers | array of objects | |
numbers[]. | string | E.164. |
numbers[]. | string | |
numbers[]. | string | api (you), sales (the person asked on a sales call), staff. |
numbers[]. | string | |
numbers[]. | string | |
numbers[]. | string | |
meta | object | |
meta. | integer |
Put a number on the do-not-call list
POST/v1/
Request
curl -X POST https://api.vocatech.com/v1/agents/do-not-call \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "number": "7185550142", "reason": "asked by email" }'Body
| Field | Type | Description |
|---|---|---|
number required | string | A 10-digit US or Canadian number. Punctuation and a leading 1 are ignored. |
reason | string | Up to 255 characters. |
{
"number": "7185550142",
"reason": "asked by email"
}Answers
| Field | Type | Description |
|---|---|---|
listed | boolean | |
number | string |
{
"listed": true,
"number": "+17185550142"
}number is not a 10-digit number.Take a number off the do-not-call list
DELETE/v1/
Body
| Field | Type | Description |
|---|---|---|
number required | string |
Answers
| Field | Type | Description |
|---|---|---|
removed | boolean | |
number | string |
number is not a 10-digit number.