Vocatech

By area

AI agents

Read from the API’s own reference file every hour.

Plain text

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/agents

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"

Answers

200
Your agents.
FieldTypeDescription
agents requiredarray of objects
agents[].id requiredintegerUse it with POST /v1/agents/{id}/calls.
agents[].name requiredstring
agents[].extension requiredstringThe agent's extension.
agents[].active requiredbooleanThe agent is switched on.
agents[].outgoing_calls requiredbooleanThe agent's Outgoing calls switch is on. It must be on to place calls.
agents[].provisioned requiredbooleanThe agent is set up on the phone system.
meta requiredobject
meta.total requiredinteger
Example
{
  "agents": [
    {
      "id": 12,
      "name": "Front Desk",
      "extension": "150",
      "active": true,
      "outgoing_calls": true,
      "provisioned": true
    }
  ],
  "meta": {
    "total": 1
  }
}
401
No key, or a key that is wrong or turned off.
403
Refused. The key is scoped away from this route, the request came from an address not on the key's allow-list, or the route refused the request (the message says why).
429
A rate limit was reached. Wait Retry-After seconds. The body names the counter, the window and the limit.
HeaderTypeDescription
Retry-AfterintegerSeconds to wait before you try again.
503
Try again shortly. The key could not be checked just now (Retry-After: 5), or a service this route needs could not be reached.
HeaderTypeDescription
Retry-AfterintegerSeconds to wait before you try again.

Place an outgoing AI agent call

POST/v1/agents/{id}/calls

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.
  • to is 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_hours is true.
  • Send purpose or instructions, or both. A call for someone sends about instead.
  • 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 sales call, and a notice or callback sent with outreach: 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_quiet holds 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. A sales call 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; consent records 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, /message and /end steer it while a person is on the line, and the agent.call.started, agent.call.status and agent.call.ended webhooks 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"
  }'

Parameters

NameInTypeDescription
id requiredpathintegerThe agent's id, from GET /v1/agents. For example 12.
Idempotency-KeyheaderstringYour 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

FieldTypeDescription
to requiredstringWho 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.
purposestringWhy the agent is calling, in one line. It says this after its greeting. Longer text is cut to 200 characters. Up to 200 characters.
subjectstringAnother name for purpose.
instructionsstringMore for the agent to know or do on this call. Longer text is cut to 2,000 characters. Up to 2,000 characters.
detailsstringBackground 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_namestringThe name of the person being called. Cut to 80 characters. Up to 80 characters.
referencestringYour 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}$.
jobstringThe name of the agent job the call starts with. Cut to 80 characters. Up to 80 characters.
kindstringnotice 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.
aboutstringFor 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.
modestringFor 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_namestringFor 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_hoursbooleanAllow 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.
outreachbooleanThe 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.
consentbooleanYour 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_quietbooleanAn 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_numberstringOne 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_tostringAn 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.
businessstringYour 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.
Example
{
  "to": "7185550142",
  "purpose": "Confirm the Friday 10 AM appointment",
  "person_name": "Jordan Reyes",
  "reference": "appt-2291",
  "kind": "notice"
}

Answers

202
The call is placed.
FieldTypeDescription
call requiredobject
call.call_sid requiredstringThe id of the placed call.
call.agent_id requiredinteger
call.from requiredstringThe number the call comes from.
call.to requiredstring
call.state requiredstringThe 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.not_beforestringOn a queued call, when the window opens (ISO 8601).
call.kind requiredstringOne of notice, callback or sales.
call.purpose requiredstring
call.reference requiredstring
call.outreachbooleanThe call is outreach (every sales call, and a notice or callback sent with outreach).
Example
{
  "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"
  }
}
400
The agent id is not a number.
Example body
Example
{
  "error": {
    "code": 400,
    "type": "BAD_REQUEST",
    "message": "The agent id must be a number."
  }
}
401
No key, or a key that is wrong or turned off.
403
Refused. The key is scoped away from this route, the request came from an address not on the key's allow-list, or the route refused the request (the message says why).
404
No agent with that id on your account.
Example body
Example
{
  "error": {
    "code": 404,
    "type": "NOT_FOUND",
    "message": "No agent with that id on this account."
  }
}
422
A field failed a check, the agent or its outgoing calls are off, it is quiet hours, or the platform refused the call.
Example bodies
Example
{
  "error": {
    "code": 422,
    "type": "UNPROCESSABLE_ENTITY",
    "message": "Outgoing calls are switched off on this agent. Turn them on under Persona, Outgoing calls."
  }
}
Example
{
  "error": {
    "code": 422,
    "type": "UNPROCESSABLE_ENTITY",
    "message": "to is required: the number to call, or an extension."
  }
}
Example
{
  "error": {
    "code": 422,
    "type": "UNPROCESSABLE_ENTITY",
    "message": "to may not be an emergency or service number."
  }
}
Example
{
  "error": {
    "code": 422,
    "type": "UNPROCESSABLE_ENTITY",
    "message": "purpose or instructions is required: the agent has to know why it is calling."
  }
}
Example
{
  "error": {
    "code": 422,
    "type": "UNPROCESSABLE_ENTITY",
    "message": "This agent is switched off."
  }
}
429
The dial counter is full (10 a minute, 500 a day per key), or another request limit was reached. Wait Retry-After seconds.
HeaderTypeDescription
Retry-AfterintegerSeconds to wait before you try again.
Example body
Example
{
  "error": "Rate limit exceeded",
  "period": "minute",
  "limit": 10,
  "counter": "dial",
  "retry_after": 42
}
502
The agent platform did not answer, or answered that it failed. The call may have been placed; check for the placed-call tag before you retry, or retry with the same Idempotency-Key.
Example body
Example
{
  "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."
  }
}
503
Outgoing calls are not available right now, or the key could not be checked.
HeaderTypeDescription
Retry-AfterintegerSeconds to wait before you try again.
Example body
Example
{
  "error": {
    "code": 503,
    "type": "ERROR",
    "message": "Outgoing calls are not available right now."
  }
}

List the calls your system placed

GET/v1/agents/calls

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

NameInTypeDescription
limitqueryintegerDefault 20. From 1 to 50.

Answers

200
The calls.
FieldTypeDescription
callsarray of objects
calls[].call_sidstring
calls[].agent_idinteger
calls[].statestring
calls[].outcomestring
calls[].summarystring
calls[].opened_atstring
calls[].closed_atstring
calls[].linesinteger
calls[].last_lineobject
metaobject
meta.totalinteger
meta.limitinteger
401
No key, or a key that is wrong or turned off.
403
Refused. The key is scoped away from this route, the request came from an address not on the key's allow-list, or the route refused the request (the message says why).
502
The agent platform did not answer.

Where a placed call stands

GET/v1/agents/{id}/calls/{call}

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

NameInTypeDescription
id requiredpathinteger
call requiredpathstringThe call_sid the placing answer gave.

Answers

200
The call.
FieldTypeDescription
call requiredobject
call.call_sidstring
call.agent_idinteger
call.statestringqueued, placing, placed (dialing, or nobody answered), talking (a person is on the line), ended, failed.
call.tostring
call.fromstring
call.placed_atstring
call.errorstring
call.exchangeobjectThe lines of the call while it was up, once a person answered.
call.exchange.statestring
call.exchange.outcomestring
call.exchange.summarystring
call.exchange.opened_atstring
call.exchange.closed_atstring
call.exchange.linesarray of objects
call.exchange.lines[].idinteger
call.exchange.lines[].whostringagent (a status line) or person (your own line).
call.exchange.lines[].statusstring
call.exchange.lines[].textstring
call.exchange.lines[].decisionstring
call.exchange.lines[].atstring
Example
{
  "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"
        }
      ]
    }
  }
}
401
No key, or a key that is wrong or turned off.
403
Refused. The key is scoped away from this route, the request came from an address not on the key's allow-list, or the route refused the request (the message says why).
404
No agent with that id on your account, or no call with that id on this agent.
502
The agent platform did not answer.

Steer a call while it is up

POST/v1/agents/{id}/calls/{call}/{action}

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 no to, the call's connect_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

NameInTypeDescription
id requiredpathinteger
call requiredpathstring
action requiredpathstringOne of say, connect, message or end.

Body

FieldTypeDescription
textstringFor say (required) and message (optional). Up to 600 characters. Up to 600 characters.
tostringFor connect. An extension of 2 to 6 digits or a 10-digit number.
Example
{
  "text": "Ask them whether they have a fax line."
}

Answers

200
The line reached the call.
FieldTypeDescription
okboolean
call_sidstring
actionstring
line_idinteger
Example
{
  "ok": true,
  "call_sid": "c7d2e9a4-1f3b-4c8e-9a6d-0b5e2f7c1a93",
  "action": "say",
  "line_id": 7
}
401
No key, or a key that is wrong or turned off.
403
Refused. The key is scoped away from this route, the request came from an address not on the key's allow-list, or the route refused the request (the message says why).
404
No agent with that id on your account, or no such action.
409
Nobody has answered yet, or the call has ended.
Example body
Example
{
  "error": {
    "code": 409,
    "type": "CONFLICT",
    "message": "That call is not one of yours, or the person has not answered yet."
  }
}
422
text or to is missing or not one the agent may dial.
502
The agent platform did not answer.

The do-not-call list

GET/v1/agents/do-not-call

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

200
The list.
FieldTypeDescription
numbersarray of objects
numbers[].numberstringE.164.
numbers[].reasonstring
numbers[].sourcestringapi (you), sales (the person asked on a sales call), staff.
numbers[].added_bystring
numbers[].call_sidstring
numbers[].created_atstring
metaobject
meta.totalinteger
401
No key, or a key that is wrong or turned off.
403
Refused. The key is scoped away from this route, the request came from an address not on the key's allow-list, or the route refused the request (the message says why).

Put a number on the do-not-call list

POST/v1/agents/do-not-call

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

FieldTypeDescription
number requiredstringA 10-digit US or Canadian number. Punctuation and a leading 1 are ignored.
reasonstringUp to 255 characters.
Example
{
  "number": "7185550142",
  "reason": "asked by email"
}

Answers

201
Listed.
FieldTypeDescription
listedboolean
numberstring
Example
{
  "listed": true,
  "number": "+17185550142"
}
401
No key, or a key that is wrong or turned off.
403
Refused. The key is scoped away from this route, the request came from an address not on the key's allow-list, or the route refused the request (the message says why).
422
number is not a 10-digit number.

Take a number off the do-not-call list

DELETE/v1/agents/do-not-call

Body

FieldTypeDescription
number requiredstring

Answers

200
Removed, or it was not on the list.
FieldTypeDescription
removedboolean
numberstring
401
No key, or a key that is wrong or turned off.
403
Refused. The key is scoped away from this route, the request came from an address not on the key's allow-list, or the route refused the request (the message says why).
422
number is not a 10-digit number.