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 (IVR)

API Branch (SMS)

Client-Side APIs

• Recordings

• Send SMS

• Contacts

• Notify

• Voicemail

IVR API Branch

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

SMS API Branch

What is the SMS API Branch?

The SMS API Branch lets your text flow talk to your own server in real time.

When someone texts your SMS-enabled number and lands on this branch, we send a POST request to your endpoint with the message details (who texted, what they wrote, any attachments). Your server decides what the reply should be and sends it back — and we deliver it to the sender.

Think of it as:

"Let my own system read and answer my incoming texts."

This is the SMS-side equivalent of the API Branch used in phone routes. The difference: the phone API Branch fires during a live call and carries call data, while the SMS API Branch fires when a text comes in and carries the message.

Why it's useful

Answer texts with live data. Look up the sender in your CRM, check an order status or account balance, and reply with the real answer — not a canned response.

Build smarter auto-replies. Instead of matching fixed keywords, your server can interpret whatever the contact wrote and respond accordingly.

Keep your logic where it already lives. It's just an HTTP request, so you can connect your CRM, billing system, ticketing tool, or any internal app without rebuilding those rules inside your SMS route.

Route incoming texts into your own system. Every message that hits this branch reaches your server, so you can log it, ticket it, or forward it wherever you need.

Before you start

• Your number must be SMS-enabled. Reach out to support@voitex.com to turn it on.
• You'll need a server endpoint that can accept a POST request and return a response.

Setting it up

1. In the SMS Branch module, click the purple + button.
2. Give the branch a title.
3. Set the function to API.
4. Click Save, then fill in the fields below.

A note on the "If No Route Found" options:

• Respond — send a predefined reply to the sender.
• Goto — send the contact to another SMS branch.
• Respond & Goto — do both: reply, then move them along.
• Respond & Land — reply, and set the selected branch as the new landing branch for this number. The contact continues from there the next time they text in.

What we send you (the request)

We POST the following to your Path URL:

Sample request

{
   "from":"8451239876",
   "to":"8459511000",
   "body":"What's my balance?",
   "cnam":"JOHN SMITH",
   "contact_info":"null",
   "attachments":[]
}

What you send back (the response)

Your server replies with:

Sample response

{
   "reply":"Hi John, your current balance is $42.50.",
   "attachments":[]
}

Example workflow

A customer texts your number asking about their order:

1. The text lands on your API branch.
2. We POST the message to your endpoint, including the sender's number and contact record.
3. Your server looks up the customer's most recent order.
4. Your server responds with reply  : "Order #1234 shipped yesterday and arrives Thursday."
5. We text that reply back to the customer.
6. The contact then moves to whichever branch you selected in Select Goto Branch.

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:

Recordings API

Overview

This API allows you to manage the recordings stored in your Library albums — uploading audio files, generating recordings from text, listing what is on your account, and downloading the audio.

Authentication

See detail above.

Endpoints

Upload Recording

Overview

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

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.

TTS recordings are created through the same endpoint used to upload audio files, with type  set to tts  .

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

List Recordings

Overview

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

Endpoint

GET https://recording.voitexapi.com/list/

Request Parameters

The request could include the following parameters:

Response Parameters

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

Each recording object contains:

Request Code Sample

GET https://recording.voitexapi.com/list/?limit=25&album_number=1

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

Response Code Sample

{
      "data": {
            "recordings": [
                  {
                        "id": 918357,
                        "album_number": 1,
                        "album_name": "Example Album",
                        "sort_number": 5,
                        "display_name": "Example Recording",
                        "saved_datetime": "2026-08-05 14:23:11",
                        "file_size": 352.2305,
                        "duration": "00:00:22",
                        "format": "wav",
                        "verify": "Y",
                        "in_trash": false
                  }
            ],
            "last_id": 918357
      },
      "status": "success",
      "errors": []
}

Paging Through Results

Omit last_id  on your first request. Each response returns a last_id  — pass it back on the next request to fetch the following page. When recordings  comes back empty, you have reached the end.

Because results are ordered by ID, recordings added while you are paging appear on a later page rather than shifting the ones you have already read.

Get Recording Audio

Overview

Downloads the audio for a single recording.

Endpoint

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

Request Parameters

Response Parameters

On success this endpoint returns the raw audio file, not JSON. The Content-Type  reflects the format the recording is stored in. Check the format  field in the List Recordings response if you need to know that before downloading.

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://recording.voitexapi.com/file/?recording_id=918357

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

Response Code Sample

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

<binary WAV data>

Error response:

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

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