Vocatech

Vocatech API

API reference

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

Plain text

Every route of the Vocatech API with its parameters, its fields, its answers and its errors, read from the API’s own file every hour. To learn a job step by step, start with the developer guide.

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 secret of 48 characters (32 on a key made before 2026-11-15). It is not a JWT. Make keys in the Vocatech portal on your company's Integrations page, under API keys: up to 10 in use, one for each system or integrator, each with its own name and its own access. The API cannot create or change keys.

Where to start. The developer guide walks through common tasks with code in four languages, and the webhook test tool shows live events.

Every route

Getting started

Calls

Messages

Faxes

Media

Callers

Contacts

AI agents

Support

Knowledge

Old paths

Webhook endpoints

Every webhook event

Scopes

Every key carries an access setting in the portal: Full access, which reaches every route, or any of Texting (messaging), Calls (calls) and AI Agent (agents), alone or together. A limited key carries those scopes, and a call to a route outside them gets 403 with scopes and path in the body. Every key may call GET /v1/whoami. Access says what a key may reach. It changes nothing about how a text is sent or priced: every key that can text sends it the same way (see Rate limits).

ScopeReaches
messaging/v1/messages (send, history, queue), /v1/reports/messages, /v1/media (message attachments only), /v1/webhooks (message events only)
calls/v1/calls, /v1/reports/calls, /v1/contacts, /v1/media (call recordings only), /v1/webhooks (call events only). Not /v1/callers, whose answer carries a number's texts
agents/v1/agents, /v1/callers, /v1/contacts/lookup, /v1/webhooks (the agent.call.* events only)
support/v1/support, /v1/knowledge (made by Vocatech on request)
knowledge/v1/knowledge (made by Vocatech on request)

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. The list is optional on every key, and an empty list allows any address. A key with a list sends up to 5,000 texts a day; a key with none sends up to 500. 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.

CounterRequestsPer minutePer hourPer day
defaulteverything not listed below6003,600100,000
reportsGET /v1/calls, GET /v1/messages, /v1/reports/*3003,000100,000
messagesPOST /v1/messages100,000 (a backstop; the pace is the queue's, below)
faxesPOST /v1/faxes, per account350 faxes sent
dialPOST /v1/agents/{id}/calls10500
ticketsPOST /v1/support/tickets10200
knowledgeGET or POST /v1/knowledge/answer302,000
  • Texting is the same on every key. A key's sends are accepted and paced by its own queue: 60 message parts a minute, and 5,000 texts a day for a key locked to fixed IP addresses or 500 a day for a key that works from any address (Vocatech may set a key's own figures). A text past the minute is accepted and queued (202); a text past the day is answered 429. 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. Until 2026-11-15 a key with Full access was refused past 20 texts a minute and 200 a day instead of queued.
  • Texts sent through the API are paid, $0.02 for each outgoing part, and are outside the account's included texting limit (50 texts an hour and 150 a day as standard): that limit counts only the texts the account's people send, it never holds an API text back, and an API text never uses it up.
  • 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.
JSON
{"error":"Rate limit exceeded","period":"minute","limit":20,"counter":"messages","retry_after":37}

Errors

StatusMeaning
400Bad input: a date, a number, a window over 366 days, an end before a start.
401No key, or a key that is wrong or turned off.
403Outside the key's scopes, an address not on the allow-list, or the request was refused (for example, from is not your number, or the recipient opted out).
404Not found, or not yours.
409A conflict: a queued message already sending or finished, or a support ticket being worked (retry after Retry-After).
410The media file is no longer available.
413A fax document over 20 MB.
422A field failed validation. The message says which.
429A rate limit. See above.
502A service we rely on answered and refused.
503Retry. The key could not be checked just now (Retry-After: 5), or a service could not be reached.
504A text send was not confirmed. It may have gone out. Check GET /v1/messages before you retry.

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.