Vocatech API
Developer guide
Written beside the API’s code, and read from it every hour.
Connect your own software to your Vocatech account. Read calls, texts and faxes with their AI summaries, transcripts and recordings. Send texts and faxes. Look up who is calling, have an AI agent place a call, open a support ticket, and get an event the moment something happens.
- Base URL
https://api.vocatech.com/v1- Authentication
Authorization: Bearer <key>- Format
- JSON in and out, UTF-8
- Every field
- The API reference and the OpenAPI file
It is a plain HTTPS and JSON API for your servers. These hold everywhere.
- Server to server only. The API sends no CORS headers, so a web page cannot call it. A key never belongs in a browser, a mobile app or a code repository.
- JSON both ways. Send
Content-Type: application/jsonwith every request that has a body. Every answer is JSON, except204 No Content. - Times are UTC, in ISO 8601, like
2026-09-24T13:02:11.000Z. The dates you ask for are read in your time zone. See Pagination and dates. - Phone numbers are 10 digits in requests and reports, like
7185550142. Formatting and a leading 1 are stripped. Text and fax webhooks write numbers with +1, like+17185550142. - Your account only. A key reads and acts on its own account. Every read of calls, texts, faxes, recordings and caller history is written to your account's HIPAA access log, with the key that made it.
Support
Questions, a key that leaked, or an endpoint that does not behave, reach us, and a person picks up.
Tell us the time, the path and the status you got. Never send us your key.
Call a company for someone
This is the order Call for me sends from Callpop, placed from your own software. Your agent calls a company for one of your people, gets through the phone menu and the hold, then gets them on the line or gets the thing done. Send "kind": "errand" with the company's number in to, one description in about of what the call is about and what it needs to do (with anything the agent may give when asked, like an account number), and for_name, whom the agent calls for.
- Get me a person (
"mode": "person", the default). The moment a live person answers, the agent says it is calling for them and ringsconnect_to, their extension or a 10-digit number. Picking up joins the call. When they do not pick up within fifteen seconds, the agent tells the company they were caught up on another call and will call back. - Handle it for me (
"mode": "handle"). The agent works the matter in the description, gives what the description holds only when it is asked for, and reports back the way it reports every message, marked with yourreference. - Now or not at all. It goes at the company's own hours, so the agent's calling hours,
allow_quiet_hoursandqueue_if_quietdo not apply. Your system watches and steers it like any call it places, and/endstops it even before anyone answers.
# Call the company and ring extension 105 the moment a person answers
curl -X POST https://api.vocatech.com/v1/agents/12/calls \
-H "Authorization: Bearer $VOCATECH_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: crm-ticket-311" \
-d '{
"to": "7185550199",
"kind": "errand",
"about": "Ask about the October bill. The account number is 4455667788.",
"mode": "person",
"for_name": "Dina Roth",
"connect_to": "105",
"reference": "crm-ticket-311"
}'
# Stop it, answered or still ringing
curl -X POST https://api.vocatech.com/v1/agents/12/calls/CALL_SID/end \
-H "Authorization: Bearer $VOCATECH_API_KEY"Outreach calls, steering a call, and the do-not-call list
A sales call ("kind": "sales", with job naming the agent's Sales job) is outreach, and so is a notice or callback you send with "outreach": true. An outreach call follows these rules, kept by the platform whoever asks.
- It says who is calling. The agent opens by naming your business. It says a disclosure first when the agent's Outgoing calls card has its box ticked, in your words.
- It gets through. 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.
- Business hours, the called number's own. 9 AM to 5 PM in the number's time zone, Monday to Friday. Outside them the call is refused with
422, or held for the next window when you send"queue_if_quiet": true(the answer is202with"state": "queued"andnot_before). - 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": truerecords your own statement that the person agreed. - Never a number on your do-not-call list.
GET /v1/agents/do-not-callreads it,POSTadds a number,DELETEremoves one. When a person asks not to be called again on a sales call, the agent adds the number itself.
from_number names one of your account's numbers to show the person called; another number is refused. Today the phone system stamps the trunk's main number on the way out, so the request is checked and recorded and is honored the day the switch allows it.
Your system is on every call it places. GET /v1/agents/{id}/calls/{call} says where the call stands (queued, placing, placed, talking, ended, failed) and, once a person answered, every line of the exchange. While a person is on the line, POST /v1/agents/{id}/calls/{call}/say hands the agent words to act on in its own voice, /connect rings an extension or number and joins them ("to": "105", or the call's connect_to), /message has the agent wrap up with a call back, and /end ends the call. Before a person answers, /say, /connect and /message answer 409, and /end hangs the call up at the phone system. The agent.call.started, agent.call.status and agent.call.ended webhooks tell you as it goes; the ended event carries the transcript, every record the agent filed (a Sales record's how_it_ended is one of demo, person, email, later, no, do_not_call or wrong_person) and the call's page in the portal.
# A sales call, held for the number's next business-hours window if it is outside them
curl -X POST https://api.vocatech.com/v1/agents/12/calls \
-H "Authorization: Bearer $VOCATECH_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: crm-88" \
-d '{
"to": "7185550142",
"kind": "sales",
"job": "Sales",
"purpose": "your phones",
"person_name": "Jordan Reyes",
"reference": "crm-88",
"connect_to": "105",
"queue_if_quiet": true
}'
# Where it stands, with every line of the exchange once a person answered
curl https://api.vocatech.com/v1/agents/12/calls/CALL_SID \
-H "Authorization: Bearer $VOCATECH_API_KEY"
# Steer it while a person is on the line
curl -X POST https://api.vocatech.com/v1/agents/12/calls/CALL_SID/say \
-H "Authorization: Bearer $VOCATECH_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "text": "Ask them whether they have a fax line." }'
# The do-not-call list
curl -X POST https://api.vocatech.com/v1/agents/do-not-call \
-H "Authorization: Bearer $VOCATECH_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "number": "7185550142", "reason": "asked by email" }'