API Docs

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

• Voicemail

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)
• 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

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

SMS Parameters

These fields apply only when type  is SMS .

CALL Parameters

These fields apply only when type  is CALL .

Response Parameters

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

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"]
}

Voicemail API

Overview

This API allows you to retrieve voicemail messages left on your account. Use List Voicemails to fetch message records, then Get Voicemail Audio to download the recording for any message.

Both endpoints use GET  with query string parameters.

Authentication

See detail above.

List Voicemails

Overview

Returns voicemail messages on your account, oldest first, with cursor-based pagination.

Endpoint

GET https://vm.voitexapi.com/messages/

Request Parameters

The request could include the following parameters:

Response Parameters

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

Each voicemail object contains:

Request Code Sample

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

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

Response Code Sample

{
      "data": {
            "voice_mails": [
                  {
                        "id": 4181,
                        "vm_group_id": 3,
                        "call_id": "AST10-1689867312.264",
                        "file_name": "vm_4181_1754500991",
                        "clid": 8451234567,
                        "date": "2026-08-05 14:23:11"
                  }
            ],
            "last_id": 4181
      },
      "status": "success"
}

Get Voicemail Audio

Overview

Downloads the audio recording for a single voicemail as a WAV file.

Endpoint

GET https://vm.voitexapi.com/file/

Request Parameters

Response Parameters

On success this endpoint returns the raw WAV audio file, not JSON, with Content-Type: audio/x-wav . On failure it returns HTTP 404 with a JSON body containing status  and errors . Check the status code before treating the response body as audio.

Request Code Sample

GET https://vm.voitexapi.com/file/?vm_id=4181

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

Response Code Sample

HTTP/1.1 200 OK
Content-Type: audio/x-wav
Content-Length: 184364

<binary WAV data>

Error response:

{
      "status": "error",
      "errors": ["file not found"]
}