Navbar
shell
  • Voice API Introduction
  • Authentication
  • Audio
  • Call Flows
  • Campaigns
  • Do-Not-Call
  • Statistics
  • Call Detail Records (CDRs)
  • Errors
  • Voice API Introduction

    Welcome to the Voxtelesys Voice REST API. This API offers an easy, secure solution to voice broadcasting. Voxtelesys offers fully integrated IVR, Do-Not-Call, Cell Number Identification, Call Detail Record retrieval, and campaign statistic reporting to help you setup and manage your voice campaigns.

    Base URL

    All URLs referenced in this document have the following base: https://servicelayer01.voxtelesys.net:3150/api/v1

    Authentication

    Request:

    curl --request GET \
      --url https://servicelayer01.voxtelesys.net:3150/api/v1/authorize/login \
      --header 'authorization: Basic ZGVtbzpwd2Q='
    

    Response: 200

    {
      "status": {
        "status": "Authorized",
        "token": "7bdf5350-5895-46ec-a25a-a531613c5046",
        "account_id": 190761,
        "account_name": "voxtelesys vts",
        "service_group_id": 70001
      },
      "services": [
        {
          "full_name": "Auto Dialer",
          "service_id": 7,
          "short_name": "Dialer"
        }
      ],
      "error": ""
    }
    

    Basic Authentication

    Tokens are assigned via the /authorize/login method. The login method utilizes HTTP basic authentication. Please signup for Voice services at Voxtelesys to receive a valid username and password.

    Login Request

    GET /authorize/login

    Header Type Required Description Example
    Authorization string true basic authentication Authentication: Basic dXNyOnB3ZA==

    Token Authentication

    All HTTP requests to the Voice API, with the exception of /authorize/login, are authenticated via HTTP token authentication. Once assigned the token is valid for 10 minutes, refreshing for an additional 10 minutes with subsequent successful requests. As a further layer of protection, the assigned token is only valid for the IP address from which the HTTP request was attempted. For applications making request to the Voice API via separate IP addresses, you must obtain unique tokens per application.

    Tokens are provided to the Voice API via HTTP headers:

    Authorization: Token token={TOKEN}

    Authorization: Token token=f2d1c9b6-1158-11e6-bb4e-26a732fd0877

    Audio

    The Voice API allows you to upload audio files, in WAV format. Once uploaded, you are able to play the audio file during a broadcast campaign. Alternatively, the voice API can download an audio file from a specified URL for use in broadcast campaigns. Please refer to the playback and playback_and_collect_input action for more details.

    Retrieve list of metadata

    Request:

    curl --request GET \
      --url https://servicelayer01.voxtelesys.net:3150/api/v1/audio \
      --header 'authorization: Token token=ef1eaf7e-a280-4d5c-9a03-d9b13133c686'
    

    Response: 200

    {
      "page": 1,
      "page_size": 25,
      "page_count": 1,
      "count": 2,
      "results": [
        {
          "id": 1,
          "name": "test_file_1.wav",
          "description": "Test File #1"
        },
        {
          "id": 2,
          "name": "test_file_2.wav",
          "description": null
        }
      ]
    }
    

    This endpoint retrieves a list of metadata for uploaded audio files.

    HTTP Request

    GET /audio

    Query Parameter Type Required Description Example
    page integer false page number starting from 1; default = 1 1
    page_size integer false number of messages to retrieve per page; default = 25 50
    Header Type Required Description Example
    Authorization string true token authentication Authentication: Token token=6804452b-ad70-425c-bf39-ab26fa6
    SUB-ACCOUNT-ID integer false ID of sub account SUB-ACCOUNT-ID: 1000

    Retrieve specific metadata

    Request:

    curl --request GET \
      --url https://servicelayer01.voxtelesys.net:3150/api/v1/audio/1 \
      --header 'authorization: Token token=ef1eaf7e-a280-4d5c-9a03-d9b13133c686'
    

    Response: 200

    {
        "id": 1,
        "name": "test_file_1.wav",
        "description": "Test File #1"
    }
    

    This endpoint retrieves metadata for a specific audio file.

    HTTP Request

    GET /audio/{id}

    Header Type Required Description Example
    Authorization string true token authentication Authentication: Token token=6804452b-ad70-425c-bf39-ab26fa6
    SUB-ACCOUNT-ID integer false ID of sub account SUB-ACCOUNT-ID: 1000

    Upload an audio file

    Request:

    curl --request POST \
      --url https://servicelayer01.voxtelesys.net:3150/api/v1/audio \
      --header 'authorization: Token token=a307f6de-9eb4-4fe5-9502-7fb5cd9d3f14' \
      --header 'content-type: application/json' \
      --data '{
        "name": "foo_bar.wav",
        "description": "Test audio file #1."
        "audio_base64": "iVBORw0KGgoAAA... rest of base64 text"
      }'
    

    Response: 200

    {
      "id": 51,
      "name": "foo_bar.wav",
      "description": "Test audio file #1."
    }
    

    This endpoint uploads an audio file. The audio file must be of WAV format.

    There are two data forms that the WAV file may be uploaded in:

    1. Base64: To upload in this form, convert the WAV file to a base64 encoded string and assign to the audio_base64 JSON parameter. Content-Type header must be: application/json. One drawback to this approach is that base64 encoding adds ~33% to the file size.
    2. Binary: To upload in this form, simply send the WAV file as is. Content-Type header must be: audio/wav.

    HTTP Request

    POST /audio

    Header Type Required Description Example
    Authorization string true token authentication Authentication: Token token=6804452b-ad70-425c-bf39-ab26fa6
    SUB-ACCOUNT-ID integer false ID of sub account SUB-ACCOUNT-ID: 1000
    Content-Type string true must be: application/json, audio/wav Content-Type: application/json
    Body Param Type Required Description Example
    name string true name of audio file foo_bar.wav
    description string false description of audio file sample description
    audio_base64 string true Base64 encoded audio file iVBORw0KGgoAAA...

    Download an audio file

    Request:

    curl --request GET \
      --url https://servicelayer01.voxtelesys.net:3150/api/v1/audio/50/download \
      --header 'authorization: Token token=ef1eaf7e-a280-4d5c-9a03-d9b13133c686'
    

    Response: 200

    {
      "id": 50,
      "name": "test_menu.wav",
      "description": null,
      "audio_base64": "iVBORw0KGgoAAA... rest of base64 text"
    }
    

    This endpoint downloads the specified audio file.

    HTTP Request

    GET /audio/{id}/download

    URL Parameter Type Required Description Example
    id integer true ID of audio file 51

    Delete an audio file

    Request:

    curl --request DELETE \
      --url https://servicelayer01.voxtelesys.net:3150/api/v1/audio/50 \
      --header 'authorization: Token token=ef1eaf7e-a280-4d5c-9a03-d9b13133c686'
    

    Response: 204

    This endpoint deletes the specified audio file.

    HTTP Request

    DELETE /audio/{id}

    URL Parameter Type Required Description Example
    id integer true ID of audio file 51
    Header Type Required Description Example
    Authorization string true token authentication Authentication: Token token=6804452b-ad70-425c-bf39-ab26fa6
    SUB-ACCOUNT-ID integer false ID of sub account SUB-ACCOUNT-ID: 1000

    Call Flows

    Call flows are a crucial component of the Voice API. They define the actions and structures to execute on each call of a campaign. Call flows can be designed as simple or complex as required. Futhermore, the generated CDRs allows the user to see the real-time action execution sequence.

    List call flows

    Request:

    curl --request GET \
      --url https://servicelayer01.voxtelesys.net:3150/api/v1/call_flows \
      --header 'authorization: Token token=606d490b-af1d-476a-a98c-676723b461fc'
    

    Response:

    {
      "page": 1,
      "page_size": 25,
      "page_count": 1,
      "count": 1
      "results": [
        {
          "id": 22,
          "name": "test_scenario_01",
          "description": null,
          "script": [
            {
              "say": {
                "text": "Hello. This is a simple voice broadcast, hope you enjoyed it!"
              }
            }
          ],
          "created_time": "2018-07-18T16:17:44Z",
          "modified_time": "2018-09-12T19:45:59Z"
        }
      ]
    }
    

    This endpoint retrieves a list of call flows.

    HTTP Request

    GET /call_flows

    Header Type Required Description Example
    Authorization string true token authentication Authentication: Token token=6804452b-ad70-425c-bf39-ab26fa6
    SUB-ACCOUNT-ID integer false ID of sub account SUB-ACCOUNT-ID: 1000

    Retrieve call flow

    Request:

    curl --request GET \
      --url https://servicelayer01.voxtelesys.net:3150/api/v1/call_flows/22 \
      --header 'authorization: Token token=606d490b-af1d-476a-a98c-676723b461fc'
    

    Response:

    {
      "id": 22,
      "name": "test_scenario_01",
      "description": null,
      "script": [
        {
          "say": {
            "text": "Hello. This is a simple voice broadcast, hope you enjoyed it!"
          }
        }
      ],
      "created_time": "2018-07-18T16:17:44Z",
      "modified_time": "2018-09-12T19:45:59Z"
    }
    

    This endpoint retrieves a specific call flow.

    HTTP Request

    GET /call_flows/{id}

    Header Type Required Description Example
    Authorization string true token authentication Authentication: Token token=6804452b-ad70-425c-bf39-ab26fa6
    SUB-ACCOUNT-ID integer false ID of sub account SUB-ACCOUNT-ID: 1000
    URL Parameter Type Required Description Example
    id integer true ID of call flow 41

    Create call flow

    Request:

    curl --request POST \
      --url https://servicelayer01.voxtelesys.net:3150/api/v1/call_flows \
      --header 'authorization: Token token=606d490b-af1d-476a-a98c-676723b461fc'
      --header 'content-type: application/json' \
      --data '{
        "name": "test_scenario_01",
        "script": [
          {
            "say": {
              "text": "Hello. This is a simple voice broadcast!"
            }
          }
        ]
      }'
    

    Response:

    {
      "id": 34,
      "name": "test_scenario_01",
      "description": null,
      "script": [
        {
          "say": {
            "text": "Hello. This is a simple voice broadcast!"
          }
        }
      ],
      "created_time": "2018-09-17T14:16:34Z",
      "modified_time": null
    }
    

    This endpoint creates a call flow.

    HTTP Request

    POST /call_flows

    Header Type Required Description Example
    Authorization string true token authentication Authentication: Token token=6804452b-ad70-425c-bf39-ab26fa6
    SUB-ACCOUNT-ID integer false ID of sub account SUB-ACCOUNT-ID: 1000
    Body Param Type Required Description Example
    name string false name of call flow foo_bar
    description string false description of call flow sample description
    script object true actions and structures to execute during call see sample request

    Update call flow

    Request:

    curl --request PUT \
      --url https://servicelayer01.voxtelesys.net:3150/api/v1/call_flows/22 \
      --header 'authorization: Token token=606d490b-af1d-476a-a98c-676723b461fc' \
      --header 'content-type: application/json' \
      --data '{
        "name": "test_scenario_01",
        "script": [
          {
            "say": {
              "text": "Hello. This is a simple voice broadcast. Press one if you enjoyed this message."
            }
          },
          {
            "collect_input": {
              "var": "${var01}"
            }
          },
          {
            "if": "${var01}==1",
            "then": [
              {
                "say": {
                  "text": "We are glad that you liked our sample broadcast!"
                }
              }
            ]
          }
        ]
      }'
    

    Response: 204

    This endpoint updates a specified call flow. Please refer to the valid list of actions or structures that may be utilized to update the respective call flow.

    HTTP Request

    PUT /call_flows/{id}

    Header Type Required Description Example
    Authorization string true token authentication Authentication: Token token=6804452b-ad70-425c-bf39-ab26fa6
    SUB-ACCOUNT-ID integer false ID of sub account SUB-ACCOUNT-ID: 1000
    URL Parameter Type Required Description Example
    id integer true ID of call flow 41
    Body Param Type Required Description Example
    name string false name of call flow foo_bar
    description string false description of call flow sample description
    script object true actions and structures to execute during call see sample request

    Delete call flow

    Request:

    curl --request DELETE \
      --url https://servicelayer01.voxtelesys.net:3150/api/v1/call_flows/22 \
      --header 'authorization: Token token=606d490b-af1d-476a-a98c-676723b461fc'
    

    Response: 204

    This endpoint deletes a specific call flow.

    HTTP Request

    DELETE /call_flows/{id}

    Header Type Required Description Example
    Authorization string true token authentication Authentication: Token token=6804452b-ad70-425c-bf39-ab26fa6
    SUB-ACCOUNT-ID integer false ID of sub account SUB-ACCOUNT-ID: 1000
    URL Parameter Type Required Description Example
    id integer true ID of call flow 41

    Actions

    The following actions can be used in a call flow.

    Processing of actions and structures is continued even after a call is hungup. However, only the send_sms and http_request actions will be executed if the call has been hungup. All other actions are skipped if the call is hungup. Refer to the set and unset actions to logically check if specific points in the call flow were reached while the call was answered before executing the send_sms or http_request action, if required.

    When there are no more actions / structures to execute the call is hungup. Therefore, a hangup action is not provided.



    set

    Example:

    {
      "set": {
        "var": "${flag01}"
      }
    }
    

    The "set" action assigns the specified variable the value of 1.

    Property Type Default Description
    var string required name of variable to set



    unset

    Example:

    {
      "unset": {
        "var": "${flag01}"
      }
    }
    

    The "unset" action assigns the specified variable the value of nil.

    Property Type Default Description
    var string required name of variable to unset



    pause

    Example:

    {
      "pause": {
        "duration": 500
      }
    }
    

    The "pause" action suspends execution of call flow for specified duration.

    Property Type Default Description
    duration integer required length of pause (msec)



    say

    Example:

    {
      "say": {
        "text": "Hello! This is a sample text-to-speech message. Goodbye!"
      }
    }
    

    The "say" action synthesizes and plays text-to-speech.

    Property Type Default Description
    text string required text to be TTS synthesized



    playback

    Example:

    {
      "playback": {
        "from_file": 21
      }
    }
    

    The "playback" action plays an audio file from either a URL or uploaded file. If the from_url field is provided, then the file will be downloaded from the provided URL when a campaign is created. The URL must return the file in WAV format, with a Content-Type of audio/wav or application/octet-stream. If the from_file field is provided, then the specified file will be played. Refer to the /broadcast_audio method to see how to upload an audio file.

    Property Type Default Description
    from_url string null url to download audio file from
    from_file integer null ID of audio file



    collect_input

    Example:

    {
      "collect_input": {
        "var": "${user_pin}",
        "options": {
          "max_digits": 4,
          "timeout": 5,
          "terminator": "#"
        }
      }
    }
    

    The "collect_input" action collects input DTMF and assigns it to the variable provided.

    The following variable names are reserved:

    Property Type Default Description
    var string required variable to store input
    options.max_digits integer 15 maximum number of digits to collect
    options.timeout integer 3 maximum time (sec) to wait for input
    options.terminator string # digit(s) to terminate input



    playback_and_collect_input

    Example:

    {
      "playback_and_collect_input": {
        "var": "${extension}",
        "from_file": 30,
        "options": {
          "min_digits": 3,
          "max_digits": 4,
          "timeout": 5,
          "terminator": "#",
          "max_attempts": 3,
          "invalid_playback_file": 31
        }
      }
    }
    

    The "playback_and_collect_input" action plays a file and collects input DTMF. This action is a combination of the playback and collect_input actions. That is, input DTMF is collected while the specified audio file is being played. Once collected, the input DTMF is validated against min_digits and max_digits. If the DTMF is invalid, then the specified invalid audio file is played and the playback_and_collect_input action is executed again if max_attempts has not been met.

    Property Type Default Description
    var string required variable to store input
    from_url string null url to download audio file from
    from_file integer null ID of uploaded audio file
    options.min_digits integer 1 minimum number of digits to collect
    options.max_digits integer 15 maximum number of digits to collect
    options.timeout integer 3 maximum time (sec) to wait for input
    options.terminator string # digit(s) to terminate input
    options.max_attempts integer 1 maximum number of times to collect digits
    options.invalid_playback_file integer null ID of audio file to play for invalid input
    options.invalid_playback_url string null url of audio file to play for invalid input



    say_and_collect_input

    Example:

    {
      "say_and_collect_input": {
        "var": "${extension}",
        "text": "Hello and welcome to the main menu. For support please press 1, otherwise stay on the line to leave a recording.",
        "options": {
          "min_digits": 3,
          "max_digits": 4,
          "timeout": 5,
          "terminator": "#",
          "max_attempts": 3,
          "invalid_playback_file": 31
        }
      }
    }
    

    The "say_and_collect_input" action plays a Text-To-Speech audio stream and collects input DTMF. This action is a combination of the say and collect_input actions. That is, input DTMF is collected while the specified TTS stream is being played. Once collected, the input DTMF is validated against min_digits and max_digits. If the DTMF is invalid, then the specified invalid audio file is played and the say_and_collect_input action is executed again if max_attempts has not been met.

    Property Type Default Description
    var string required variable to store input
    text string required text to be TTS synthesized
    options.min_digits integer 1 minimum number of digits to collect
    options.max_digits integer 15 maximum number of digits to collect
    options.timeout integer 3 maximum time (sec) to wait for input
    options.terminator string # digit(s) to terminate input
    options.max_attempts integer 1 maximum number of times to collect digits
    options.invalid_playback_file integer null ID of audio file to play for invalid input
    options.invalid_playback_url string null url of audio file to play for invalid input



    transfer

    Example:

    {
      "transfer": {
        "to": "1701000000",
        "options": {
          "cid": "14024034435"
        }
      }
    }
    

    The "transfer" action connects the current call with the provided number. This action is a blocking action, meaning that the call flow execution is suspended until either party ends the call. As a result, send_sms and http_request are the only valid actions after a transfer.

    Property Type Default Description
    to string required number to transfer call to
    options.cid string null caller ID number for transfer



    send_sms

    Example:

    {
      "send_sms": {
        "to": "1701000000",
        "from": "17019999999",
        "body": "This is an example text message sent in-call!"
      }
    }
    

    The "send_sms" action sends an SMS message to the provided recipient. To signup for SMS messaging please contact Voxtelesys.

    Property Type Default Description
    to string required number to send SMS to
    from string required number SMS is sent from
    body string required message to send



    record

    Example:

    {
      "record": {
        "options": {
          "beep": true,
          "max_duration": 30,
          "terminator": "#",
          "silence_duration": 3,
          "tag": "recording1"
        }
      }
    }
    

    The "record" action records a segment of the call. By specifying the options.tag field, the recording can be played via the playback_recording method later on in the call. Recordings are accessible via the Voxtelesys Portal once completed.

    Property Type Default Description
    options.beep boolean false play tone before recording
    options.max_duration integer 120 maximum duration (sec) of recording
    options.silence_duration integer 5 duration of silence (sec) before ending recording
    options.terminator string "#" digit(s) to end recording
    options.tag string null identifier for recording



    playback_recording

    Example:

    {
      "playback_recording": {
        "options": {
          "tag": "recording1"
        }
      }
    }
    

    The "playback_recording" action plays a recording from the current call. To use this action, the record action must first be called. If the options.tag field is provided, then the recording with the corresponding tag will be played. If not provided, then the last recording will play.

    Property Type Default Description
    options.tag string null identifier for recording



    http_request

    Example:

    {
      "http_request": {
        "url": "https://www.fakeurl.com/ap1/v1/test_end_point",
        "method": "post",
        "options": {
          "headers": {
            "Content-Type": "application/json",
            "Header1": "val1"
          }
          "body": {
            "key1": "val1",
            "key2": "va12"
          }
        }
      }
    }
    

    The "http_request" action sends an HTTP request to the provided endpoint (URL). The supported HTTP methods include: GET, POST, PUT, and DELETE. Custom headers and a custom body is supported via the options.headers and options.body objects.

    Property Type Default Description
    url string required url to send HTTP request
    method string required valid HTTP method: get,post,put,delete
    options.headers object null HTTP request headers
    options.body object null HTTP request body

    Structures

    The following structures can be used in a call flow:

    In each structure, the following comparison operators can be utilized in the structure's expression component. Only one comparison is valid per expression (i.e. and, or operators are not supported at this time).

    Operator Description
    == equal
    != not equal
    <= less than or equal
    >= greater than or equal
    < less than
    > greater than



    if_then

    Example:

    {
      "if": "${var01}==1",
      "then": [
        {
          "say": {
            "text": "You entered one!"
          }
        }
      ],
      "else": [
        {
          "say": {
            "text": "You did not enter one!"
          }
        }
      ]
    }
    

    The "if_then" structure is a control flow statement that evaluates the if expression, then executes the then array of actions if the expression evaluates to true or executes the else array of actions if the expression evaluates to false. Only one of the two action objects (if,then) is required.

    Property Type Default Description
    if string null expression to evaluate
    then object null array of actions to execute if expression is true
    else object null array of actions to execute if expression is false





    switch_case

    Example:

    {
      "switch": "${var01}",
      "case": [
        {
          "1": [
            {
              "say": {
                "text": "You pressed one!"
              }
            }
          ],
          "2": [
            {
              "say": {
                "text": "You pressed two!"
              }
            }
          ]
        }
      ],
      "default": [
        {
          "say": {
            "text": "You did not press one or two!"
          }
        }
      ]
    }
    

    The "switch_case" structure is a control flow statement that evaluates multiple case expressions, then executes the corresponding array of actions or executes the default array of actions if no expressions evaluate to true. The default action is an optional parameter.

    Property Type Default Description
    switch string null name of variable to evaluate
    case object null array of hashes, mapping case values to an array of actions
    default object null array of actions to execute if no matching cases















    while_do

    Example:

    {
      "while": "${var01}==1",
      "do": [
        {
          "say": {
            "text": "You are in a while_do loop!"
          }
        }
      ],
      "max_loop": 3
    }
    

    The "while_do" structure is a control flow statement that executes an array of actions only if the provided while expression evaluates to true, and then repeatedly executes the array of actions until the while expression evaluates to false. To prevent infinite loops, the max_loops parameter is provided.

    Property Type Default Description
    while string null expression to evaluate
    do object null array of actions to execute if expression is true
    max_loops integer 5 maximum number of iterations



    repeat_until

    Example:

    {
      "repeat": [
        {
          "say": {
            "text": "You are in a repeat_until loop!"
          }
        }
      ],
      "until": "${var01}==1",
      "max_loop": 3
    }
    

    The "repeat_until" structure is a control flow structure that executes an array of actions and then repeatedly executes the array of actions until the until expression evaluates to true. To prevent infinite loops, the max_loops parameter is provided.

    Property Type Default Description
    repeat object null array of actions to execute
    until string null expression to evaluate
    max_loops integer 5 maximum number of iterations

    Campaigns

    The Voice API offers the ability to easily broadcast audio files to bulk dialing lists. Voxtelesys has fully integrated DNC services that can scrub every number on the submitted list at both the national and local levels. In addition, Voxtelesys offers a fully integrated CNI service that can scrub the submitted list for cellular devices.

    The Voice API also offers campaign management, allowing you to schedule, pause, re-start, and cancel campaigns.

    List campaigns

    Request:

    curl --request GET \
      --url https://servicelayer01.voxtelesys.net:3150/api/v1/campaigns \
      --header 'authorization: Token token=606d490b-af1d-476a-a98c-676723b461fc'
    

    Response:

    {
      "page": 1,
      "page_size": 25,
      "page_count": 1,
      "count": 1,
      "results": [
        {
          "id": "mZnVvdfAJrhd5hzr",
          "to": [
            "14024034435"
          ],
          "cid": "14024439999",
          "cnam": "Voxtelesys",
          "send_at": "2019-03-05T17:19:35Z",
          "expire_at": "2019-03-08T17:19:35Z",
          "modified_at": "2019-03-05T17:19:35Z",
          "outbound_trunk_group_id": 90761,
          "redial_attempts": 1,
          "redial_interval": 5,
          "call_flow_id": 3,
          "cni": true,
          "dnc": true,
          "status": "completed"
        }
      ]
    }
    

    This endpoint retrieves a list of campaigns with respective metadata.

    HTTP Request

    GET /campaigns

    Header Type Required Description Example
    Authorization string true token authentication Authentication: Token token=6804452b-ad70-425c-bf39-ab26fa6
    SUB-ACCOUNT-ID integer false ID of sub account SUB-ACCOUNT-ID: 1000

    Retrieve a campaign

    Request:

    curl --request GET \
      --url https://servicelayer01.voxtelesys.net:3150/api/v1/campaigns/mZnVvdfAJrhd5hzr \
      --header 'authorization: Token token=606d490b-af1d-476a-a98c-676723b461fc'
    

    Response:

    {
      "id": "mZnVvdfAJrhd5hzr",
      "to": [
        "14024034435"
      ],
      "cid": "14024439999",
      "cnam": "Voxtelesys",
      "send_at": "2019-03-05T17:19:35Z",
      "expire_at": "2019-03-08T17:19:35Z",
      "modified_at": "2019-03-05T17:19:35Z",
      "outbound_trunk_group_id": 90761,
      "redial_attempts": 1,
      "redial_interval": 5,
      "call_flow_id": 3,
      "cni": true,
      "dnc": true,
      "status": "completed"
    }
    

    This endpoint retrieves a specific campaign.

    HTTP Request

    GET /campaigns

    Header Type Required Description Example
    Authorization string true token authentication Authentication: Token token=6804452b-ad70-425c-bf39-ab26fa6
    SUB-ACCOUNT-ID integer false ID of sub account SUB-ACCOUNT-ID: 1000

    Create a campaign

    Request:

    curl --request POST \
      --url https://servicelayer01.voxtelesys.net:3150/api/v1/campaigns \
      --header 'authorization: Token token=4331860e-40bd-4f1f-bdb6-6e22b7c0ffc1' \
      --header 'content-type: application/json' \
      --data '{
        "to": ["14022770288"],
        "cid": "14024034435",
        "cnam": "Voxtelesys",
        "outbound_trunk_group_id": 90761,
        "call_flow_id": 3,
        "cni": false,
        "dnc": false,
        "redial_attempts": 1,
        "redial_interval": 5
      }'
    

    Response: 200

    {
      "id": "e2zYZh9hogSSuev7",
      "to": [
        "14022771111"
      ],
      "cid": "14024034435",
      "cnam": "Voxtelesys",
      "send_at": "2019-04-02T16:20:49Z",
      "expire_at": "2019-04-05T16:20:49Z",
      "modified_at": "2019-04-02T16:20:49Z",
      "outbound_trunk_group_id": 90761,
      "redial_attempts": 1,
      "redial_interval": 5,
      "call_flow_id": 3,
      "cni": false,
      "dnc": false,
      "status": "pre-processing"
    }
    

    This endpoint creates a broadcast campaign. Within this method, you are able to provide an entire dialing list, specify the call flow that you wish to broadcast, and schedule the campaign to start and / or expire at specified dates. Additional features include DNC, CNI list scrubbing, and redialing of calls resulting with a "busy" or "canceled" status. Please refer to the Update Campaign method to see how to start, pause, or cancel campaigns.

    HTTP Request

    POST /campaigns

    Header Type Required Description Example
    Authorization string true token authentication Authentication: Token token=6804452b-ad70-425c-bf39-ab26fa6
    SUB-ACCOUNT-ID integer false ID of sub account SUB-ACCOUNT-ID: 1000
    Content-Type string true must be application/json Content-Type: application/json
    Body Param Type Required Description Example
    to array true array of valid numbers to dial ["14022770000", ... ]
    cid string true caller ID number 14024034435
    outbound_trunk_group_id integer true ID of outbound trunk group 90761
    call_flow_id integer true ID of call flow 22
    cnam string true caller ID name; limit 15 characters Voxtelesys
    send_at string false date to start campaign; must be in ISO-8601 date format; default to start immediately 2018-01-01 8:00:00 -0600
    expire_at string false date to expire campaign; must be in ISO-8601 date format; default to 3 days from start_date 2018-01-01 16:00:00 -0600
    redial_attempts integer false number of times to redial calls resulting in a "busy" or "canceled" status 2
    redial_interval integer false duration (min) between redial attempts 30
    cni boolean false if true, scrubs Cellular numbers from list true
    dnc boolean false if true, scrubs list against national, local DNC lists true

    Update a campaign

    Request:

    curl --request PUT \
      --url https://servicelayer01.voxtelesys.net:3150/api/v1/campaigns/28482954-78ad-406d-83ef-46663ae936fb \
      --header 'authorization: Token token=4331860e-40bd-4f1f-bdb6-6e22b7c0ffc1' \
      --header 'content-type: application/json' \
      --data '{
        "status": "pause"
      }'
    

    Response: 204

    This endpoint allows you to start, pause, or cancel the specified campaign.

    HTTP Request

    PUT /campaigns/{id}

    Header Type Required Description Example
    Authorization string true token authentication Authentication: Token token=6804452b-ad70-425c-bf39-ab26fa6
    SUB-ACCOUNT-ID integer false ID of sub account SUB-ACCOUNT-ID: 1000
    Content-Type string true must be application/json Content-Type: application/json
    Body Param Type Required Description Example
    status string true must be start, pause, or cancel; if pause dialing will stop until a start status is received; cancel to stop dialing and cancel campaign start

    Do-Not-Call

    Voxtelesys offers full Do-Not-Call (DNC) list integration, at both the national and customer (local) level. When a voice campaign is submitted with DNC requested, phone numbers are scrubbed at the national and local level before dialing. Local lists can be populated manually (POST /dnc), or populated automatically via the http_request action.

    Retrieve DNC List

    Request:

    curl --request GET \
      --url https://servicelayer01.voxtelesys.net:3150/api/v1/dnc \
      --header 'authorization: Token token=176a78b0-8e81-4e56-9e3f-da67d17915bb' \
      --header 'content-type: application/json'
    

    Response: 200

    {
      "customer_lists": [
        {
          "id": 27,
          "account_id": 190761,
          "subaccount": null,
          "ndc": "14024034435",
          "created_at": "2016-11-09T18:17:48.000Z"
        },
        {
          "id": 28,
          "account_id": 190761,
          "subaccount": null,
          "ndc": "14022770000",
          "created_at": "2016-11-09T18:17:48.000Z"
        }
      ]
    }
    

    This endpoint retrieves the local DNC list associated with the account. Please note that only the local DNC list will be retrieved, not the National DNC list.

    HTTP Request

    GET /dnc

    Header Type Required Description Example
    Authorization string true token authentication Authentication: Token token=6804452b-ad70-425c-bf39-ab26fa6
    SUB-ACCOUNT-ID integer false ID of sub account SUB-ACCOUNT-ID: 1000

    Create DNC Entry

    Request:

    curl --request POST \
      --url https://servicelayer01.voxtelesys.net:3150/api/v1/dnc \
      --header 'authorization: Token token=2f831c8b-64d9-4d09-9985-fcc54d30e7c4' \
      --header 'content-type: application/json' \
      --data '{
        "ndc": "14024431550"
      }'
    

    Response:

    {
      "dnc_customer_list": {
        "id": 41,
        "account_id": 190761,
        "subaccount": null,
        "ndc": "14024034435",
        "created_at": "2016-11-09T18:58:54.000Z"
      }
    }
    

    This endpoint creates a new DNC entry for the provided ndc. Please note that the entry is only created in the local DNC list, not the National DNC list.

    HTTP Request

    POST /dnc

    Header Type Required Description Example
    Authorization string true token authentication Authentication: Token token=6804452b-ad70-425c-bf39-ab26fa6
    SUB-ACCOUNT-ID integer false ID of sub account SUB-ACCOUNT-ID: 1000
    Content-Type string true must be application/json Content-Type: application/json
    Body Param Type Required Description Example
    ndc integer true valid phone number 14024034435

    Delete DNC Entry

    Request:

    curl --request DELETE \
      --url https://servicelayer01.voxtelesys.net:3150/api/v1/dnc/41 \
      --header 'authorization: Token token=2f831c8b-64d9-4d09-9985-fcc54d30e7c4' \
      --header 'content-type: application/json'
    

    Response: 200

    This endpoint deletes a DNC entry. Please note that the entry is only deleted from the local DNC list, not the National DNC list.

    HTTP Request

    DELETE /dnc/{id}

    URL Parameter Type Required Description Example
    id integer true ID associated with DNC record 41
    Header Type Required Description Example
    Authorization string true token authentication Authentication: Token token=6804452b-ad70-425c-bf39-ab26fa6
    SUB-ACCOUNT-ID integer false ID of sub account SUB-ACCOUNT-ID: 1000

    Statistics

    Summary

    Request:

    curl --request GET \
      --url 'https://servicelayer01.voxtelesys.net:3150/api/v1/campaigns/0RQOVKkU25kRGS63/stats?type=summary' \
      --header 'authorization: Token token=606d490b-af1d-476a-a98c-676723b461fc'
    

    Response:

    {
      "campaign_id": "0RQOVKkU25kRGS63",
      "campaign_status": "in-progress",
      "count": 23,
      "results": [
        {
          "status": "queued",
          "count": 5
        },
        {
          "status": "failed",
          "count": 2
        },
          {
          "status": "active",
          "count": 1
        },
        {
          "status": "busy",
          "count": 2
        },
        {
          "status": "answered",
          "count": 13
        }
      ]
    }
    

    This endpoint retrieves campaign results, categorized by status. Call categories are defined below:

    HTTP Request

    GET /campaigns/{id}/stats?type=summary

    URL Parameter Type Required Description Example
    id string true ID of campaign 0RQOVKkU25kRGS63
    Header Type Required Description Example
    Authorization string true token authentication Authentication: Token token=6804452b-ad70-425c-bf39-ab26fa6
    SUB-ACCOUNT-ID integer false ID of sub account SUB-ACCOUNT-ID: 1000

    Detailed

    Request:

    curl --request GET \
      --url 'https://servicelayer01.voxtelesys.net:3150/api/v1/campaigns/0RQOVKkU25kRGS63/stats?type=detailed' \
      --header 'authorization: Token token=606d490b-af1d-476a-a98c-676723b461fc'
    

    Response:

    {
      "campaign_id": "0RQOVKkU25kRGS63",
      "campaign_status": "in-progress",
      "count": 23,
      "results": [
        {
          "status": "queued",
          "count": 5,
          "to": [
            "14024449955",
            "14024449956",
            "14024449957",
            "14024449958",
            "14024449959",
          ]
        },
        {
          "status": "failed",
          "count": 2,
          "to": [
            "14024441540",
            "14024441495"
          ]
        },
          {
          "status": "active",
          "count": 1,
          "to": [
            "14024441599"
          ]
        },
        {
          "status": "busy",
          "count": 2,
          "to": [
            "14024441549",
            "14024441545"
          ]
        },
        {
          "status": "answered",
          "count": 13,
          "to": [
            "14024441542",
            "14024441536",
            "14024441535",
            "14024431649",
            "14024432066",
            "14024431725",
            "14024438840",
            "14024432832",
            "14024434037",
            "14024434943",
            "14024440126",
            "14024433579",
            "14024432434"
          ]
        }
      ],
      "error": ""
    }
    

    This endpoint retrieves campaign results, categorized by status. Call categories are defined below:

    HTTP Request

    GET /campaigns/{id}/stats?type=detailed

    URL Parameter Type Required Description Example
    id string true ID of campaign 0RQOVKkU25kRGS63
    Header Type Required Description Example
    Authorization string true token authentication Authentication: Token token=6804452b-ad70-425c-bf39-ab26fa6
    SUB-ACCOUNT-ID integer false ID of sub account SUB-ACCOUNT-ID: 1000

    Performance

    Request:

    curl --request GET \
      --url 'https://servicelayer01.voxtelesys.net:3150/api/v1/campaigns/0RQOVKkZZZZRGS63/stats?type=performance' \
      --header 'authorization: Token token=606d490b-af1d-476a-a98c-676723b461fc'
    

    Response:

    {
      "campaign_id": "0RQOVKkZZZZRGS63",
      "campaign_status": "in-progress",
      "count": 1098,
      "results": {
        "duration": 1278,
        "aloc": 55.6,
        "asr": 99.5,
        "under_6_pct": 1.6,
        "canceled_pct": 9.1
      }
    }
    

    This endpoint shows performance statistics for the specified campaign. Definitions are provided below:

    HTTP Request

    GET /campaigns/{id}/stats?type=performance

    URL Parameter Type Required Description Example
    id string true ID of campaign 0RQOVKkZZZZRGS63
    Header Type Required Description Example
    Authorization string true token authentication Authentication: Token token=6804452b-ad70-425c-bf39-ab26fa6
    SUB-ACCOUNT-ID integer false ID of sub account SUB-ACCOUNT-ID: 1000

    Call Detail Records (CDRs)

    Retrieve list of CDRs

    Request:

    curl --request GET \
      --url 'https://servicelayer01.voxtelesys.net:3150/api/v1/cdrs' \
      --header 'authorization: Token token=606d490b-af1d-476a-a98c-676723b461fc'
    

    Response:

    {
      "page": 1,
      "page_size": 30,
      "page_count": 1,
      "count": 3,
      "results": [
        {
          "id": "5b997a322141b2687df06697",
          "to": "14024441548",
          "status": "answered",
          "modified_at": "2018-09-12T20:48:25Z",
          "campaign_id": "5ea2b099-7b7a-49c5-a95e-82ea61c8f804",
          "call_history": [
            {
              "create_time": "2018-09-12T20:48:06Z",
              "answer_time": "2018-09-12T20:48:06Z",
              "hangup_time": "2018-09-12T20:48:25Z",
              "hangup_cause": "Normal Clearing",
              "duration": 3.11,
              "actions": [
                {
                  "say": {
                    "text": "Hello. This is a simple voice broadcast!"
                  }
                }
              ]
            }
          ]
        },
        {
          "id": "5b997a322141b2687df06696",
          "to": "14024441547",
          "status": "busy",
          "modified_at": "2018-09-12T20:48:06Z",
          "campaign_id": "5ea2b099-7b7a-49c5-a95e-82ea61c8f804",
          "call_history": [
            {
              "create_time": "2018-09-12T20:48:06Z",
              "hangup_time": "2018-09-12T20:48:06Z",
              "hangup_cause": "Busy Here",
              "hangup_cause_sip": 486
            }
          ]
        },
        {
          "id": "5b997a322141b2687df06689",
          "to": "14024441534",
          "status": "failed",
          "modified_at": "2018-09-12T20:48:05Z",
          "campaign_id": "5ea2b099-7b7a-49c5-a95e-82ea61c8f804",
          "call_history": [
            {
              "create_time": "2018-09-12T20:48:05Z",
              "hangup_time": "2018-09-12T20:48:05Z",
              "hangup_cause": "Not Found",
              "hangup_cause_sip": 404
            }
          ]
        }
      ]
    }
    

    This endpoint returns call detail records (CDRs). CDRs returned from this method are for statistical use only. Billable timestamps and durations may vary slightly.

    HTTP Request

    GET /statistics/cdrs

    Query Parameter Type Required Description Example
    campaign_id string false ID associated with campaign 0RQOVKkZZZZRGS63
    page integer false page number starting from 1; default = 1 1
    page_size integer false number of messages to retrieve per page; default = 30 50
    status string false retrieve CDRs with this status; see list of statuses answered
    start_date string false retrieve CDRs at or after this date time; must be ISO-8601 format 2018-03-01 08:00 -0600
    end_date string false retrieve CDRs at or before this date time; must be ISO-8601 format 2018-03-28 08:00 -0600
    Header Type Required Description Example
    Authorization string true token authentication Authentication: Token token=6804452b-ad70-425c-bf39-ab26fa6
    SUB-ACCOUNT-ID integer false ID of sub account SUB-ACCOUNT-ID: 1000

    Errors

    The Dialer REST API uses the following HTTP error codes:

    Code Description
    401 Unauthorized -- The provided token, request IP, and/or account are not valid. Use the /authorize/login to obtain a valid token.
    404 Not Found -- The request URL and/or HTTP method is not valid.
    422 Unprocessable Entity -- The request data and/or parameters are not valid.
    500 Internal Server Error -- An error occurred within the server. Please contact Voxtelesys with the provided error_id to resolve this error.