API Reference

Authentication

Requests you make to Voitex carry your Auth-Key header. Requests Voitex makes to your webhook are signed with your account secret, so you can prove they came from us.

POST https://notify.voitexapi.com/notify/
Auth-Key: your_auth_key
Content-Type: application/x-www-form-urlencoded

Send fields as form data: application/x-www-form-urlencoded, or multipart/form-data when you attach a file. Request examples below show the fields as JSON or key=value lines for readability.

The request

Every request is a POST with a JSON body. It always carries the call and your saved state, plus the details for that event.

{
  "version": "1.0",
  "event": "call.started",
  "call": {
    "id": "c_8f2k41",
    "from": { "number": "+12125550187", "name": "SARAH KLEIN" },
    "to":   { "did": "+12125550100" }
  },
  "state": null
}

The reply

Reply 200 OK with application/json: a list of actions and, if you like, new state. The whole reply is checked before anything plays.

{
  "actions": [
    { "action": "say", "text": "Thanks for calling Riverside Academy." },
    { "action": "gather", "num_digits": 1, "timeout": 6,
      "prompts": [
        { "action": "say", "text": "Press 1 for the office, 2 for today's schedule." }
      ],
      "inputs": {
        "1": [ { "action": "dial", "extension": "101" } ],
        "2": [ { "action": "play", "url": "https://example.com/today.mp3" },
               { "action": "hangup" } ]
      }
    }
  ],
  "state": { "menu": "main" }
}

State

Return a state object and it comes back to you, word for word, on every request for that call. Use it for the menu they are in, an account you looked up, or how many times they missed a prompt.

Instant inputs

Every request is dead air for the caller. Put the answers you already know in a gather’s inputs and they run the moment the key is pressed, up to three menus deep. Anything that depends on a lookup, like a balance or who is on shift, still goes to your server.

Actions

Each item in actions is an object with an action name and its options. Mix them in any order.

{ "action": "say", "text": "Thanks for calling.", "barge_in": false }

{ "action": "play", "url": "https://cdn.example.com/greeting.mp3" }

{
  "action": "player",
  "url": "https://cdn.example.org/lectures/24.mp3",
  "start_ms": 0,
  "controls": {
    "1": {"seek": -15},  "3": {"seek": 15},
    "4": {"seek": -60},  "6": {"seek": 60},
    "7": {"seek": -300}, "9": {"seek": 300},
    "2": {"pause_toggle": true},
    "8": {"return": "bookmark"},
    "0": {"return": "previous"}, "#": {"return": "next"}, "*": {"return": "menu"},
    "5": {"menu": {
      "prompts": [{"action": "play", "url": "https://cdn.example.org/prompts/options.mp3"}],
      "timeout": 3,
      "options": {
        "1": {"menu": {"timeout": 3, "options": {
               "1": {"volume": -2}, "2": {"volume_reset": true}, "3": {"volume": 2}}}},
        "2": {"return": "liked"}, "3": {"return": "playlists"},
        "5": {"return": "next_date"}, "6": {"return": "skip_10"},
        "7": {"speed": 0.5, "confirm": [{"action": "say", "text": "Half speed"}]},
        "8": {"speed": 1},
        "9": {"speed": 1.5, "confirm": [{"action": "say", "text": "One and a half speed"}]}
      }}}
  },
  "paused_controls": {
    "2": {"pause_toggle": true},
    "0": {"moh_toggle": true},
    "5": {"return": "length"}
  },
  "pause_timeout": 300,
  "action_url": "/ivr/player"
}

{
  "event": "player.completed",
  "player": {
    "reason": "key", "name": "bookmark", "digits": "8",
    "position_ms": 1383400, "duration_ms": 2895000,
    "speed": 1.5, "volume": 2, "paused": false,
    "listened_ms": 1102000
  }
}

{ "action": "gather", "num_digits": 4, "timeout": 8, "play_count": 2,
  "prompts": [
    { "action": "say", "text": "Enter your four digit code." }
  ] }

{ "action": "dial", "extension": "101",
  "ring": "both", "ringback": "moh",
  "escape_key": "*", "timeout": 25 }

{ "action": "redirect", "url": "/ivr/no-input" }

[ { "action": "say", "text": "Leave a message after the beep." },
  { "action": "record", "max_seconds": 120 } ]

{ "action": "pause", "seconds": 1.5 }

{ "action": "hangup", "reason": "menu complete" }

Execution rules

Events

Every request includes the call, a sequence number and a timestamp, plus a block with the details for that event.

Dial results

Every dial.completed carries one. Branch on it to send unanswered calls to voicemail or another number.

Signing

Each request is signed with your account secret using HMAC-SHA256 over the timestamp, a dot, and the raw body. Check it against the raw body, compare in constant time and reject old timestamps.

import crypto from "crypto";

// Verify a Voitex webhook request
function isFromVoitex(req, secret) {
  const ts  = req.headers["x-voitex-timestamp"];
  const sig = req.headers["x-voitex-signature"].replace("v1=", "");
  const expected = crypto
    .createHmac("sha256", secret)
    .update(ts + "." + req.rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

import hmac, hashlib

# Verify a Voitex webhook request
def is_from_voitex(headers, raw_body: bytes, secret: str) -> bool:
    ts  = headers["X-Voitex-Timestamp"]
    sig = headers["X-Voitex-Signature"].removeprefix("v1=")
    expected = hmac.new(secret.encode(), ts.encode() + b"." + raw_body,
                        hashlib.sha256).hexdigest()
    return hmac.compare_digest(sig, expected)

Timeouts & retries

Your server has 5 seconds to answer each request, and requests are not retried, because the caller is waiting. A timeout, an error or invalid JSON plays a short apology and ends the call, so return valid JSON even on your own errors.

Addressing

Larger sends are queued as a broadcast you can follow in the portal.

SMS

Up to 1,000 characters, from any of your SMS-enabled numbers. Add an attachment to send it as MMS.

{
  "type": "SMS",
  "cid": "2125550100",
  "to": "2125550187",
  "body": "See you tomorrow at 3 PM!"
}

{
  "type": "SMS",
  "cid": "2125550100",
  "label": "10,15",
  "phone_type": "M",
  "title": "Snow day",
  "body": "School is closed today. Stay safe and warm!",
  "to_be_sent": "2026-12-08 06:30:00"
}

Calls

Choose what happens when they answer with call_type.

{
  "type": "CALL",
  "cid": "2125550100",
  "to": "2125550187",
  "call_type": "stream",
  "recording": "closing_notice"
}

{
  "type": "CALL",
  "cid": "2125550100",
  "to": "2125550187",
  "call_type": "goto",
  "branch_number": "5",
  "route_number": "2125550100"
}

Response

Bad numbers are reported, never silently dropped.

{
  "status": "success",
  "request_id": "r_51c2e8",
  "group_id": "g_20931",
  "summary": {
    "type": "SMS",
    "valid_count": 1240,
    "invalid_count": 3,
    "recipient_estimate": 1240
  },
  "invalid": {
    "212555": "invalid_format"
  },
  "errors": [],
  "warnings": []
}

Contacts

Create, update, look up and delete contacts, with their phones, fields and labels. One endpoint: pick the operation with function. A contact can have several phones and labels, and is always found by any one of its phone numbers.

Create a contact

POST https://contacts.voitexapi.com/
Auth-Key: your_auth_key

function=create
phone=2125550187,2125550133
phone_type=M
first_name=Sarah
last_name=Klein
label=2

{
  "status": "success",
  "data": "Contact created"
}

Update a contact

phone finds the contact and must already be on it. Send only what you want to change; send a field empty to clear it. You can add one phone and remove one phone per request.

POST https://contacts.voitexapi.com/
Auth-Key: your_auth_key

function=update
phone=2125550187
email=sarah@example.com
field_a=1234
add_phone=2125550164
add_phone_type=M
add_label=3,7
remove_label=5

{
  "status": "success",
  "data": "Contact updated"
}

Look up a contact

POST https://contacts.voitexapi.com/
Auth-Key: your_auth_key

function=select
phone=2125550187

{
  "status": "success",
  "data": {
    "contact": {
      "first_name": "Sarah", "last_name": "Klein",
      "email": "sarah@example.com", "notes": "", "exp": null,
      "address": "", "city": "", "state": "", "zip": "",
      "field_a": "1234", "field_b": "", "field_j": ""
    },
    "phones": [
      { "phone": "2125550187", "type": "M" },
      { "phone": "2125550164", "type": "M" }
    ],
    "labels": [2, 3, 7]
  }
}

Delete a contact

Removes the whole contact. To remove just one number, use update with remove_phone.

POST https://contacts.voitexapi.com/
Auth-Key: your_auth_key

function=delete
phone=2125550187

{
  "status": "error",
  "errors": ["No contact found for phone: 2125550187"]
}

Voicemail

Pull new voicemails and download the audio into your CRM, ticketing or inbox. Both endpoints are GET with query parameters.

List voicemails

Returns messages oldest first, up to 100 at a time.

GET https://vm.voitexapi.com/messages/?limit=25&last_id=4180
Auth-Key: your_auth_key

{
  "status": "success",
  "data": {
    "voice_mails": [{
      "id": 4181,
      "vm_group_id": 3,
      "call_id": "AST10-1689867312.264",
      "file_name": "vm_4181_1754500991",
      "clid": "2125550142",
      "date": "2026-10-27 10:42:05"
    }],
    "last_id": 4181
  }
}

Store the last last_id you received and send it next time to fetch only new voicemails.

Download a voicemail

Returns the raw WAV audio (audio/x-wav), not JSON. If it is not found you get HTTP 404 with a JSON error.

GET https://vm.voitexapi.com/file/?vm_id=4181
Auth-Key: your_auth_key

Send SMS

A simple one-to-one text from one of your SMS-enabled numbers. For lists, labels, MMS or scheduling, use the Notify API.

POST https://sms.voitexapi.com/send/
Auth-Key: your_auth_key

from=2125550100
to=2125550187
body=Your appointment is confirmed.

{
  "status": "success",
  "data": {
    "from": "2125550100",
    "to": "2125550187",
    "body": "Your appointment is confirmed.",
    "did_type": "TN",
    "referenceID": "u7T0um"
  },
  "errors": []
}

did_type is TN for a local number or TF for toll-free.

Questions