API Docs

Streamlining Communication with Voitex API Integration

Voitex's host of APIs facilitates smooth data exchange, improving communication processes, operational efficiency, and user experience.

API Branch

Client-Side APIs

Upload Recording
TTS
Notification Call
Send SMS
Contacts
Notify

What is the API Branch?

The API Branch lets your phone system talk to your own server in the middle of a live call.

When a caller reaches a Trigger branch, we send a POST request to your API endpoint with all the important call details (who’s calling, what they pressed so far, any payments, variables, etc).

Your server decides what should happen next and sends back instructions like:

What to say or play (TTS or audio files)
Which options the caller can press
Which branch to go to next
What variables to store for later in the call

Think of it as:

“Let my own system make call flow decisions in real time.”

Why it’s powerful (Key Benefits)

1. Real-time, data-driven call flows

Because we hit your API during the call, you can:

Look up the caller in your CRM or database
Check account status, balance, open tickets, etc.
Decide how to route the caller based on live data

Example:

If the caller has an unpaid invoice, route them to billing; if they’re VIP, skip queues and send them to priority support.

2. Personalized caller experience

You can use the request data plus your own logic to customize:

What the caller hears (“Hi John, your order #1234 is out for delivery.”)
Which options they see (hide irrelevant menus)
What happens if they’ve already done something earlier in the call (e.g., already paid)

This makes your IVR feel smart and tailored, instead of generic.

3. Deep integration with your own systems

Because it’s just an HTTP request, you can integrate with:

CRMs
Billing systems
Custom internal tools
Any app that can handle an API call

No need to rebuild logic inside the IVR — you keep your rules where they already live.

What we send you (Request)

When the caller hits an API Branch with function “Trigger”, we send a request body that includes:

The request body contains the following parameters:

Parameter	Description
`call_id`	Unique ID for this call. All API calls during that call share this ID.
`cid`	The number the caller is calling from.
`cnam`	The caller's caller ID name.
`contact_info`	If this caller’s phone number is registered in your contacts, any details associated with the specified contact will be included here.
`date_time`	Current date and time.
`did`	The hotline number the caller called.
`branch_data`	An array detailing each branch the caller navigated through during the phone call, along with the inputs pressed at each step. This data can be reset in the middle of a call by sending the caller to a branch with the function ‘Content’ and setting the dropdown to ‘Clear Data’.)
`payment_info`	An array of payment information, including the amount and last four digits of the credit card, if the caller made a payment during the phone call.
`variables`	An array of variables set during the phone call, including those set in 'Trigger' or 'Contact Data' branches.

What you send back (Response)

Your API responds with simple JSON telling the IVR what to do next. You can include:

Parameter	Description
`goto`	Which branch number to send the caller to next. If you don’t send `goto` , and no `play/inputs` are provided, we fall back to the current Trigger’s “No Route Found” setting. If you do send play/inputs, `goto` is usually used on each input option instead.
`play`	What the caller should hear before going anywhere else. An array of audio files and/or TTS phrases Plays immediately, then the call continues (possibly with `inputs` active at the same time) Example behavior: Play: “Your order is on the way. Press 1 to talk to support, or 2 to hear this again.”
`inputs`	What the caller can press while the `play` audio is playing, and where each choice should go. Each entry typically looks like: The key the caller can press (e.g., `"1"` , `"2"` , `""` ) The branch* to route them to for that key Special case: An input of `%` means: “Send the caller to this branch no matter what they press.” This lets you allow any input, or use it as a catch-all.
`variables`	Variables you want to store and reuse later in the call. These can be used in other branches later on, for example: Save an album ID, then use it in an “Album Collection” branch to play that album Save a customer ID, order number, language preference, etc., and reuse it anywhere you need during the call

Request Code Sample

{
   "call_id":"AST10-1689867312.264",
   "cid":"8459511000",
   "cnam":"VOITEX",
   "contact_info":"null",
   "date_time":"2023-07-20 11:35:35",
   "did":"8459511110",
   "branch_data":[
      {"branch":"0","input":"1"},
      {"branch":"1000","input":"17"}
   ],
   "payment_info":[{
      "last_four":"4444",
      "expiration":"0126",
      "cvv":987,
      "zip":"10950",
      "phone":"8451239876",
      "amount":"57",
      "transaction_id":"875891"
   }],
   "variables":[{
      "caller_pin ":"123",
      "var_2":"var_val"
   }]
}

Response Code Sample

{ 
   "goto":"150", 
   "play":[ 
      { 
         "type":"file", 
         "album":"10", 
         "sort":"25" 
      }, 
      { 
         "type":"tts", 
         "text":"This is a reply TTS recording from the API."
      } 
   ], 
   "inputs":{ 
      "1":"3", 
      "4":"2", 
      "6":"105"
   }, 
   "variables":{ 
      "album_num":"13", 
      "var_2":"var_val" 
   } 
}

Client-Side APIs

With our versatile API functionalities, seamlessly interact with our system and optimize your workflow. From uploading recordings and generating TTS files to triggering notification calls and sending SMS messages, our APIs empower you to automate processes, enhance communication, and streamline operations effortlessly.

Authentication

To use this API, you need an Auth-Key, which we provide once the account is opened. You

need to include the Auth-Key in the headers of every request, as shown below:

headers: {
       "Auth-Key": "your_auth_key"
}

Explore our range of API options below:

Upload Recording API

Overview

This API enables you to upload recordings to specific albums, organizing them into different categories.

Authentication

See detail above.

Endpoint

POST https://recording.voitexapi.com/upload/

Request Parameters

The request body could include the following parameters:

Parameter	Description	Required
`album_number`	The album number to which the recording should be added to. To view the list of albums and their numbers, visit the user portal.	Yes
`sort_number`	The unique number ID assigned to this recording. This ID enables callers to select a specific recording within a particular category when accessing recordings over the phone. By entering the associated number ID, callers can listen to their desired recording. If not specified, the next sort number available will be assigned automatically.	No
`upload_file`	The actual file (in wav or mp3 formats) that contains the recording.	Yes
`display_name`	The name used to label the recording on the portal for easy identification and management of the recording.	No
`override`	If set to `yes` , deletes any existing recording with this `sort_number` before upload.	No

Response Parameters

The Voitex API will return a JSON object with the following fields:

Parameter	Description
`status`	The status of the request, as follows: "success" if the request was successful. "error" if there was an error.
`data`	The backend recording ID that we assigned to the recording.
`errors`	An array of error messages, if applicable. This parameter will be empty if the request was successful, or contain one or more error messages if there was an error.

Request Code Sample

POST https://recording.voitexapi.com/upload/

headers: {
      "Auth-Key": "1234567890abcdef"
}
form-data: {
     "album_number": 1,
     "upload_file": "example.wav",
     "sort_number": 5,
     "display_name": "Example Recording" 
}

Response Code Sample

{
      "data": "918357",
      "status": "success",
      "errors": [] 

}

Create TTS

Overview

This API allows you to create TTS (Text-To-Speech) recordings and save them in a Library album.

Authentication

See detail above.

Endpoint

POST https://recording.voitexapi.com/upload/

Request Parameters

The request body could include the following parameters:

Parameter	Description	Required
`album_number`	The album number to which the recording should be added to. To view the list of albums and their numbers, visit the user portal.	Yes
`type`	Set to `tts` to specify that text-to-speech conversion needs to take place.	Yes
`text`	The text that needs to be converted to audio.	Yes
`sort_number`	The unique number ID assigned to this recording. This ID enables callers to select a specific recording within a particular category when accessing recordings over the phone. By entering the associated number ID, callers can listen to their desired recording. If not specified, the next sort number available will be assigned automatically.	No
`override`	If set to `yes` , deletes any existing recording with this `sort_number` before upload.	No

Response Parameters

The Voitex API will return a JSON object with the following fields:

Parameter	Description
`status`	The status of the request, as follows: "success" if the request was successful. "error" if there was an error.
`data`	The backend recording ID that we assigned to the recording.
`errors`	An array of error messages, if applicable. This parameter will be empty if the request was successful, or contain one or more error messages if there was an error.

Request Code Sample

POST https://recording.voitexapi.com/upload/

headers: {
      "auth_key": "1234567890abcdef"
}
form-data: {
     "album_number ": "1",
     "sort_number": "15",
     "type": "tts",
     "text": "This is a test recording created by the TTS API.",
}

Response Code Sample

{
      "status": "success",
      "data": "915863",
      "errors": []  
}

Notification Call

Overview

This API allows you to initiate notification phone calls from your DID number to any designated phone number.

Authentication

See detail above.

Endpoint

POST https://notify.voitexapi.com/

Request Parameters

The request body could include the following parameters:

Parameter	Description	Required
`cid`	The hotline number to send the call from.	Yes
`to`	The phone number to send the call to.	Yes
`type`	Set this field to ‘goto’ if you want to direct the call receiver to an IVR branch. (Coming soon) Type ‘stream’ to stream a single file.	Yes
`route_number`	The hotline DID to which to route the call receiver. This field is required when ‘type’ is set to ‘goto.'	No
`branch_number`	The branch to route the call receiver to. This field is required when ‘type’ is set to ‘goto.’	No
`sfile_id`	The ID of the file to play from your library. This field is required when ‘type’ is set to ‘stream.' (*Coming soon*)	No

Response Parameters

The Voitex API will return a JSON object with the following fields:

Parameter	Description
`status`	The status of the request, as follows: 'success' if the request was successful. 'error' if there was an error.
`reference_id`	Unique identifier to easily reference this request at a later time.
`errors`	An array of error messages, if applicable. This parameter will be empty if the request was successful, or contain one or more error messages if there was an error.

Request Code Sample

POST https://notify.voitexapi.com/

headers: {
      "Auth-Key": "1234567890abcdef"
}
form-data: {
     "cid":"8459511000",
     "to": "8455009999",
     "type": "goto",
     "route_number": "8459511000",
     "branch_number ": "8459511000"
  }

Response Code Sample

{
      "status": "success",
      "reference_id": "Sz1gt0IqgVV7HHs",
      "errors": [] 
}

Send SMS

Overview

This API allows you to send text messages from your SMS-enabled DID.

Authentication

See detail above.

Endpoint

POST https://sms.voitexapi.com/send/

Request Parameters

The request body includes the following parameters:

Parameter	Description	Required
`from`	The DID (phone number) on your account from which to send the SMS.	Yes
`to`	The number to send the SMS to.	Yes
`body`	The actual message to send.	Yes

Response Parameters

The Voitex API will return a JSON object with the following fields:

Parameter	Description
`status`	The status of the request, as follows: 'success' if the request was successful. 'error' if there was an error.
`data`	The data you sent in the API request, along with the DID type (TN – telephone number or TF – toll-free) and a referenceID.
`errors`	An array of error messages, if applicable. This parameter will be empty if the request was successful, or contain one or more error messages if there was an error.

Request Code Sample

POST https://sms.voitexapi.com/send/

headers: {
      "Auth-Key": "1234567890abcdef"
}
form-data: {
     "from ": "8459511000 ",
     "to": "8451234567",
     "body": "This is a test message body"
}

Response Code Sample

{
      "status": "success",
      "data": "{
             "to": "8451234567",
             "from ": "8459511000 ",
             "body": "This is a test message body",
             "did_type ": "TN ",
             "from ": "u7T0um "
      }",
      "errors": []
}

Contacts API

This API allows you to create, update, and delete Voitex contacts. Contacts are stored per user and can include multiple phone numbers and multiple labels.

Base URL

https://contacts.voitexapi.com/

Method

POST

Headers

Auth-Key: YOUR_API_KEY
Content-Type: application/x-www-form-urlencoded

Common Response Format

Success

{  "status": "success",  "data": "..." }

Error

{  "status": "error",  "errors": ["message 1", "message 2"] }

Create Contact

Creates a brand-new contact.

If any phone in the request already exists for this user, the request fails.

Body Parameters

function (required): create
phone (required):

One phone number, or multiple phones comma-separated.

Example: 7325550184 or 7325550184,6465557729
phone_type (optional): H (Home) or M (Mobile).

If omitted, defaults to H .

Note: when sending multiple phones, the same type is applied to all of them.
first_name (optional)
last_name (optional)
label (optional): label number to attach contact to

Example Request (bulk key:value)

function:create phone:7325550184 phone_type:H first_name:John last_name:Doe label:2

Success Response

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

Error Response (examples)

{  "status": "error",  "errors": ["contact already exists with phone(s): 7325550184"] }

Update Contact

Updates an existing contact.

The contact is located by any phone number already in that contact.

All operations apply to one contact per request.

Body Parameters

function (required): update
phone (required):

Locator phone — must already exist on the contact.

A) Update contact fields

Include any field you want to change:

first_name
last_name
email
exp (expiration date)
notes
field_a , field_b , field_c , field_d , field_e , field_f , field_g , field_h ,field_i ,field_j
plus any additional enabled custom fields on your account

Clear a field: send it with an empty value.

B) Update phone type (one phone per request)

phone_type : updates only the locator phone in phone= .
Allowed values: H or M .

Invalid values are ignored.

C) Add phone

add_phone
add_phone_type (optional): H or M

If missing or invalid, it defaults to H .

Rules

A phone number can belong to only one contact.
If add_phone belongs to another contact → request fails.
If add_phone already exists on this contact → it is not duplicated (its type may be updated if needed).

D) Remove phone (not last)

remove_phone

Rules

You may remove a phone only if at least one phone will remain.
Attempting to remove the last phone returns an error and does not remove it.

E) Add labels (one or many)

add_label : label number or comma-separated list

Example: 2 or 2,3,7

Rules

Labels must be referenced by label number.
If any label number is invalid or doesn’t exist → request fails.

F) Remove labels ( one or many)

remove_label : label number or comma-separated list

Example: 3 or 2,7

Note: removing a label only removes membership. Labels themselves are not deleted.

Example Requests

1) Update fields

function:update phone:7325550184 first_name:John last_name:Doe email:john.doe@example.com field_a:1234 exp:2026-02-01

2) Update locator phone type

function:update phone:7325550184 phone_type:M

3) Add a phone (defaults to H if type omitted/invalid)

function:update phone:7325550184 add_phone:6465557729

4) Add a phone with explicit type

function:update phone:7325550184 add_phone:6465557729 add_phone_type:M

5) Remove a phone (not last)

function:update phone:7325550184 remove_phone:6465557729

6) Add / remove multiple labels

function:update phone:7325550184 add_label:2,3,7 remove_label:5

Success Response

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

Error Response (examples)

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

Delete Contact

Deletes the entire contact. This permanently removes all phones and label memberships. To remove only a phone number, use update .

Labels are not deleted — only the mappings to this contact are removed.

Body Parameters

function (required): delete
phone (required): any phone on the contact

Example Request (bulk key:value)

function:delete phone:7325550184

Success Response

{  "status": "success",  "data": "Contact deleted successfully" }

Error Response (example)

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

Important Notes

One contact per request: update/delete always apply to the contact located by phone= .
Phone uniqueness: a phone number can exist under only one contact.
Supported phone types: only H (Home) and M (Mobile).

Invalid types are ignored; when adding a phone without a valid type, it defaults to H .
Adding/removing phones: update allows adding one phone and removing one phone per request.
Labels: multiple labels may be added or removed per request using comma-separated values.
Last phone protection: update cannot remove the final phone on a contact. Use delete to remove the contact entirely.

Select Contact

Retrieve a contact’s details using any phone number associated with the contact.

The response includes:

Contact fields
All phone numbers on the contact
All label numbers assigned to the contact

Body Parameters

Field	Required	Description
`function`	Yes	Must be `select`
`phone`	Yes	Any phone number associated with the contact

Example Request

function:select phone:7325550184

Success Response

{  "status": "success",  "data": {    "contact": {      "first_name": "John",      "last_name": "Doe",      "email": "",      "notes": "",      "exp": null,      "address": "",      "city": "",      "state": "",      "zip": "",      "field_a": "",      "field_b": "",      "field_c": "",      "field_d": "",      "field_e": "",      "field_f": "",      "field_g": "",      "field_h": "",      "field_i": "",      "field_j": ""    },    "phones": [      { "phone": "7325550184", "type": "H" },      { "phone": "6465557729", "type": "M" }    ],    "labels": [2, 3, 7]  } }

Error Responses

No phone provided

{  "status": "error",  "errors": ["No valid phone number provided"] }

Contact not found

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

Notes

The phone number used in phone may be any number on the contact.
All phone numbers associated with the contact are returned.
Labels are returned as a list of label numbers.

Notify API

Overview

This API allows you to send SMS messages and initiate notification calls from your DID to one or more recipients — individually, as an explicit phone list, or as a group broadcast via contact labels.

Authentication

See detail above.

Endpoint

POST https://notify.voitexapi.com/notify/

Request Parameters

The request body includes the following parameters.

Common Parameters

Parameter	Description	Required
type	The notification type. Set to `SMS` to send a text message, or `CALL` to initiate a phone call.	Yes
cid	The DID (phone number) on your account to send from. Also accepts `from` .	Yes
to	Single recipient phone number. Provide this OR `phones` OR `label` — never more than one.	One of three required
phones	Comma-separated list of phone numbers. 1–19 numbers are sent individually; 20+ are queued as a group broadcast.	One of three required
label	Comma-separated label numbers from your contact lists. Always sent as a group broadcast.	One of three required
phone_type	Phone types to include when using label mode: `H` (home), `M` (mobile), or `H,M` for both. Default: `H,M` .	No
title	A label for this broadcast. Default: IVR Notification.	No
to_be_sent	Schedule for a future date/time. Format: `YYYY-MM-DD HH:MM:SS` . Defaults to now if omitted.	No
dnc	Do-not-call list handling flag.	No
confirm	Confirmation flag.	No

SMS Parameters

These fields apply only when type is SMS .

Parameter	Description	Required
body	The message text to send. Maximum 1000 characters. Also accepts `message` .	Yes
attachments	File upload for MMS. Requires `form-data` with `type=File` .	No

CALL Parameters

These fields apply only when type is CALL .

Parameter	Description	Required
call_type	The call behavior. Set to `stream` to play a recording, or `goto` to transfer to an IVR box.	Yes
recording	Recording filename to play (without prefix). Required when `call_type = stream` .	Yes (stream)
sfile_id	Library file ID. Alternative to `recording` for stream calls.	No
branch_number	The IVR box number to route the call to. Required when `call_type = goto` .	Yes (goto)
route_number	DID used to bridge the call. Required when `call_type = goto` .	Yes (goto)
greeting	Optional JSON string for greeting (goto only).	No
variables	Optional JSON string for variables (goto only).	No

Response Parameters

The Voitex API returns a JSON object with the following fields:

Parameter	Description
status	Request status: `success` , `partial_success` , `failure` , or `error` .
request_id	Unique identifier for this API request.
batch_id	Returned for single recipient sends (`to` or 1–19 phones).
group_id	Returned for group broadcasts (20+ phones or label).
summary	Object containing route, type, mode, valid count, invalid count, and recipient estimate.
invalid	Object listing rejected phone numbers and reasons (if any).
errors	Array of error messages (empty if successful).
warnings	Non-fatal notices (if applicable).

Request Code Samples

Send SMS to a single number

POST https://notify.voitexapi.com/notify/

Headers:

{
  "Auth-Key": "1234567890abcdef"
}

Form Data:

{
  "type": "SMS",
  "cid": "8459511000",
  "to": "8451234567",
  "body": "This is a test message"
}

Send SMS to multiple numbers

POST https://notify.voitexapi.com/notify/

Form Data:

{
  "type": "SMS",
  "cid": "8459511000",
  "phones": "8451234567,8459998888,8453331111",
  "body": "This is a group message"
}

Send SMS to a contact label

POST https://notify.voitexapi.com/notify/

Form Data:

{
  "type": "SMS",
  "cid": "8459511000",
  "label": "10,15",
  "phone_type": "H,M",
  "body": "This is a label broadcast"
}

Notification call — play a recording

POST https://notify.voitexapi.com/notify/

Form Data:

{
  "type": "CALL",
  "cid": "8459511000",
  "to": "8451234567",
  "call_type": "stream",
  "recording": "my_recording_filename"
}

Notification call — transfer to IVR box

POST https://notify.voitexapi.com/notify/

Form Data:

{
  "type": "CALL",
  "cid": "8459511000",
  "to": "8451234567",
  "call_type": "goto",
  "branch_number": "5",
  "route_number": "8459511000"
}

Scheduled broadcast

POST https://notify.voitexapi.com/notify/

Form Data:

{
  "type": "SMS",
  "cid": "8459511000",
  "phones": "8451234567,8459998888",
  "body": "This is a scheduled message",
  "to_be_sent": "2026-07-01 09:00:00"
}

Response Code Samples

Success — single send

{
  "request_id": "req_0a1b2c3d4e",
  "status": "success",
  "batch_id": "1_S_8451234567_8459511000_2606241530_042",
  "summary": {
    "route": "single",
    "type": "SMS",
    "mode": "single",
    "valid_count": null,
    "invalid_count": 0,
    "recipient_estimate": 1
  }
}

Success — group broadcast

{
  "request_id": "req_0a1b2c3d4e",
  "status": "success",
  "group_id": "G2606241530042",
  "summary": {
    "route": "group",
    "type": "SMS",
    "mode": "phones",
    "valid_count": 25,
    "invalid_count": 0,
    "recipient_estimate": 25
  }
}

Partial success — some invalid numbers

{
  "request_id": "req_0a1b2c3d4e",
  "status": "partial_success",
  "batch_id": "1_S_8451234567_8459511000_2606241530_042",
  "summary": {
    "route": "single",
    "type": "SMS",
    "mode": "phones",
    "valid_count": 1,
    "invalid_count": 2,
    "recipient_estimate": 1
  },
  "invalid": {
    "123": "invalid_format",
    "5551234567": "unallocated_nanp"
  }
}

Error

{
  "request_id": "req_0a1b2c3d4e",
  "status": "error",
  "errors": ["call_type must be stream or goto"]
}