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.

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:

What you send back (Response)

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

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:

Response Parameters

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

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:

Response Parameters

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

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:

Response Parameters

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

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:

Response Parameters

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

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)
• field_a    , field_b    , field_c    , field_d    , field_e    , field_f    
• 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.