API reference

The Vocatech API connects your own systems to your phone system. Read your calls, texts and faxes. Send texts and faxes. Look up who is calling. Keep your contacts in sync. Have your AI agent place a call. Open a support ticket. Get every event pushed to your server by webhook.

Base URL: https://api.vocatech.com. Paths start with /v1. Requests and responses are JSON.

Server to server only. The API sends no CORS headers. Keep your key on your server. Never put it in a web page or a mobile app.

Keys. Send your key on every request as Authorization: Bearer YOUR_API_KEY. A key is an opaque 32-character secret. It is not a JWT. Make the main key in the Vocatech portal on your company's Integrations page (Generate or Regenerate). Make metered texting keys under Textdock > API Messaging, one per integrator, up to 10. The API cannot create or change keys.

Every route

Getting started

• GET/v1/whoamiCheck your key

Calls

• GET/v1/callsList calls

Messages

• POST/v1/messagesSend a text
• GET/v1/messagesList messages
• GET/v1/messages/queueSee the send queue
• DELETE/v1/messages/queueCancel every queued message
• DELETE/v1/messages/queue/{id}Cancel one queued message

Faxes

• POST/v1/faxesSend a fax
• GET/v1/faxesList faxes

Media

• GET/v1/media/{id}Get a media link

Callers

• GET/v1/callers/{number}Look up a caller

Contacts

• GET/v1/contacts/fieldsList contact fields
• GET/v1/contactsList contacts
• POST/v1/contactsCreate or update contacts
• DELETE/v1/contactsDelete contacts
• GET/v1/contacts/lookupFind contacts by phone number

AI agents

• GET/v1/agentsList AI agents
• POST/v1/agents/{id}/callsPlace an outgoing AI agent call

Support

• POST/v1/support/ticketsOpen a support ticket

Knowledge

• GET/v1/knowledge/answerAsk the knowledge base
• POST/v1/knowledge/answerAsk the knowledge base (POST)

Old paths

• GET/v1/reports/callsList calls (old path)
• GET/v1/reports/messagesList messages (old path)

Webhook endpoints

• GET/v1/webhooksList webhook endpoints
• POST/v1/webhooksCreate a webhook endpoint
• GET/v1/webhooks/failuresList failed deliveries
• GET/v1/webhooks/{id}Get a webhook endpoint
• PATCH/v1/webhooks/{id}Update a webhook endpoint
• DELETE/v1/webhooks/{id}Delete a webhook endpoint
• POST/v1/webhooks/{id}/testSend a test delivery

Every webhook event

• POSTcall.startedAn extension started ringing or dialing
• POSTcall.answeredAn extension answered
• POSTcall.endedA call ended
• POSTcall.transcriptionA recorded call has its transcript
• POSTmessage.sentA text went out through the API or an automation
• POSTmessage.receivedA text or WhatsApp message arrived
• POSTmessage.status_updatedThe carrier reported on a text
• POSTfax.sentAn outgoing fax is in progress
• POSTfax.receivedAn incoming fax is arriving
• POSTfax.deliveredA fax completed
• POSTfax.failedA fax failed

Scopes

The main key reaches every route. A key can be narrowed to one or more scopes. A scoped key that calls a route outside its scopes gets 403 with scopes and path in the body. Every key may call GET /v1/whoami.

A scoped key sees and changes only the webhooks it created, and only their failures.

IP allow-list

A key can be locked to exact IPv4 or IPv6 addresses in the portal. Ranges are not supported. An empty list allows any address. A request from any other address gets 403 with client_ip in the body. Call GET /v1/whoami first and enter the address exactly as it shows client_ip.

Rate limits

Every key has a separate counter for each kind of request. Windows are fixed and run on UTC: a minute, an hour and a day each reset on the clock. Refused requests count too.

• A metered API Messaging key (scope messaging) is not held to 20 a minute and 200 a day. Its sends are accepted and paced by its own queue: message parts per minute (60 by default) and messages per day (5,000 by default), set per key by Vocatech. The backstop of 100,000 requests a day still applies. A company-wide cap of 960 T-Mobile-bound messages a day, shared with the company's broadcasts, also paces the queue (limits.tmobile_day_allowance in GET /v1/messages/queue); T-Mobile's day resets at midnight Pacific, and every number is looked up for its carrier before the send.
• A metered API Messaging key's sends are paid per message and are outside the account's included texting limit (50 texts an hour and 150 a day as standard): that limit never holds them back and they never use it up. Texts sent with a main key count toward it, together with the texts the account's people send, and past it the send is answered 429.
• A request without a live key (missing, wrong or turned off) is counted by source address: 60 a minute and 600 an hour.
• Faxes are counted per account, not per key: 3 requests a minute, and 50 faxes actually sent a day, counted by the Eastern calendar day (a dry run or a refused request does not count toward the 50). A fax is a PDF of at most 25 pages. The fax API is for sending your own documents; it is not for marketing or bulk faxing.
• Each account also has a monthly allowance of outbound fax pages, 1,000 a month for each fax line on the account (unless Vocatech set another figure), pooled across the lines, so an account with three lines may send 3,000 pages a month from any one of them. It is the same count the portal and email to fax keep. Past it, POST /v1/faxes answers 429.
• Every 429 from a counter carries a Retry-After header: the seconds until that window resets.

{"error":"Rate limit exceeded","period":"minute","limit":20,"counter":"messages","retry_after":37}

Errors

Errors come in a few shapes:

• Key errors (401, the key-check 503): {"error":"Unauthorized","message":"Missing or invalid Authorization header."}
• Access errors (403 scope or address): {"error":"Forbidden","message":"...","scopes":"messaging","path":"/v1/calls"} or {"error":"Forbidden","message":"...","client_ip":"198.51.100.7"}
• Rate limits (429): see above.
• Action errors, from a route that ran: {"error":{"code":404,"type":"NOT_FOUND","message":"Attachment not found."}}. type is BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT, UNPROCESSABLE_ENTITY, RATE_LIMIT_EXCEEDED, SERVER_ERROR, or ERROR for any other status.
• Route errors, for an unknown path, a wrong method, a webhook that is not found, or an unexpected fault: {"statusCode":404,"error":{"type":"RESOURCE_NOT_FOUND","description":"Webhook not found."}}

Conventions

• Times in responses are UTC, ISO 8601, like 2026-09-24T14:05:09.000Z, unless a field says otherwise.
• Report windows (start_date, end_date) are local days in timezone, which defaults to America/New_York.
• Phone numbers in reports are digits without the leading 1, like 7185550142. Message and fax webhooks use E.164, like +17185550142.
• Lists page with page (from 1) and limit. meta carries the totals.
• Durations are in seconds.
• info.version is the date this reference was last checked against the code. New fields can appear in responses. Build clients that ignore fields they do not know.

The file behind this reference

The whole reference is one OpenAPI 3.1 file, the API’s own, kept with its code. Hand the file to a coding tool or import it into an API client. Each page here is also plain text for an AI, and the whole reference is one file.