Voizematic API Reference

The Voizematic REST API lives at https://voizematic.ai/api/v1, authenticates with a bearer key issued in the panel, and lets your own systems place calls, manage agents and contacts, read transcripts and receive webhook events. It is the same engine the panel uses; anything you can do here is billed per connected minute from the wallet, exactly as a panel call is.

Docs: Getting started · Configuration · Integrations · API reference · MCP connector · Tutorials · FAQ

How do I authenticate?

Open the gear icon → Global Settings → API Keys and create a key. It starts with vz_live_. Send it on every request:

Authorization: Bearer vz_live_…
Content-Type: application/json

Keys act under your account. Rate limit: 1,000 requests per minute.

Which endpoints exist?

Method	Path	Purpose
GET	/api/v1/agents	List your agents (id, name, operation type, assigned number).
POST	/api/v1/agents	Create an agent (name, system prompt, greeting, voice, operation type).
PUT	/api/v1/agents/:agentId	Update an agent's prompt or settings.
POST	/api/v1/calls	Place an outbound call now: to_number (E.164), agent_id, optional knowledge_base_id, optional context (≤ 2,000 characters of details for this one call, e.g. cart contents or an order number).
GET	/api/v1/calls	List recent calls with status and outcome.
GET	/api/v1/calls/:callId	One call: status, duration, outcome, recording.
GET	/api/v1/calls/:callId/transcript	The transcript and Call Intelligence fields once available.
GET	/api/v1/contacts	List contacts.
POST	/api/v1/contacts	Add one contact (phone, name, optional email/company/list).
POST	/api/v1/contacts/bulk	Add many contacts in one request.
POST	/api/v1/webhooks	Register a webhook endpoint; /api/v1/webhooks/test sends a test event.

How do I place a call with context?

curl -X POST https://voizematic.ai/api/v1/calls \
  -H "Authorization: Bearer vz_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "to_number": "+919876543210",
    "agent_id": 42,
    "context": "Abandoned cart: 2 × running shoes size 8, ₹4,998. Coupon SAVE10 valid till Friday."
  }'

The call is queued and dialled by the platform's call worker; the response carries the scheduled call's id. The agent receives the context as background for that one call — it is never read out verbatim and is not treated as instructions.

What do webhook events look like?

Events: call.started, call.answered, call.ended, call.completed, call.failed, call.transcribed, call.transferred. Each POST carries a JSON body with the event name, timestamp and call data, plus two headers: X-Voizematic-Event (the event name) and X-Voizematic-Signature (an HMAC-SHA256 of the raw body using your webhook secret, so you can verify origin). call.transcribed includes the transcript. Respond with a 2xx status promptly.

Errors

Status	Meaning
401	Missing or invalid key.
402	Insufficient wallet balance to place the call (the body reports the current balance).
404	Agent, call or contact not found under this account.
400	Validation failed — to_number and agent_id are required; context must be a string (it is truncated to 2,000 characters).
429	Rate limit exceeded.

Prefer an assistant-driven integration instead of code? See the MCP connector. Code samples in JavaScript and Python are in the panel's API Reference page after sign-in.

---