NAV
cURL

Introduction

Voxology’s Programmable Voice and Messaging API enables you to architect and embed intelligent communications into your application. The service allows you to programmatically make and receive phone calls, create call flows, modify live calls, record calls, manage phone numbers, and send and receive SMS.

Voxology API

Tools Include

Postman Collection

To help our development community, we have created a Postman collection which can be used to test the various API methods.

If you are not familiar with Postman, visit Postman to learn more. In short, it provides a robust interface for running, testing, documenting, and sharing APIs.

Click the link below to view and download our collection!

Open in Postman

The collection comes with the Voxology REST API environment. Be sure to update the X-API-KEY and BASIC_AUTH values after you complete your sign up.

Overview

Call Flow Loop

Example Response

{
  "actions": [
    {
      "type": "SAY",
      "params": {
        "text": "Hello, Jill",
        "loop": 1
      }
    },
    {
      "type": "CONFERENCE",
      "params": {
        "name": "test-conf"
      }
    },
    {
      "type": "SAY",
      "params": {
        "text": "You have left the conference. Please rate your experience from 1 to 5."
      }
    },
    {
      "name": "rating",
      "type": "COLLECT",
      "params": {
        "num_digits": 1,
        "finish_on_key": "pound",
        "timeout": 3000
      }
    },
    {
      "type": "SAY",
      "params": {
        "text": "Thank you and good bye."
      }
    }
  ]
}

Voxology’s Call Flow Loop allows you to control phone calls using our set of Call Flow Actions. When a call is initiated or received, Voxology will make a request to the URL that you designate to fetch instructions from your server. Your response will determine what to do next with the call.

Multi-Action Processing

Responses can be as simple as a single action.

Example: SAY “Hello, Jill”.

Or it can be an array of actions that lead the caller through a much more complicated call flow.

Example: SAY “Hello, Jill”, put the caller in a CONFERENCE, wait until the caller leaves the conference (press #), SAY a question, COLLECT a key press, and SAY goodbye, HANGUP.

This combined with our other tools like session data, conditionals, and variables may come as good news to those who have found themselves in ‘callback hell’ while using other services.

Phone Number Configuration

After purchasing and assigning one or more phone numbers to CallFlows via the REST API, you must configure the callback settings for the phone number(s) via Update Call Flow Configuration. Once configured, your server will get callback requests to control calls.

How it Works

To learn more about our call flow loop, visit our How It Works pages:

Action Types

All actions have type, params, name and comments properties and can be passed in an array.

Property Description Type Required
type Accepts: COLLECT, CONFERENCE, DETECT, DIAL, FOREACH, GOTO, HANGUP, IF, LABEL, PAUSE, PLAY, QUEUE, RECORD, RECORDMESSAGE, REDIRECT, REJECT, SAY, SESSIONDATA, SMS, STREAM ,STOP, TRANSFER and WEBHOOK. string Yes
params The parameters for the action type. See below for each type. object No
name A name to give the action. string Conditional
comments An optional string of comments to document the action. string No

Supported Actions By Service

Certain action types are not supported in all Voxology services. See the table below for which actions are available for Programmable Voice and Programmable Messaging.

Action Description Programmable Voice Programmable Messaging
COLLECT Collect key presses or speech from the caller. Supported Not Supported
CONFFERENCE Place a caller into a conference. Supported Not Supported
DETECT Detect whether the call was picked up by a live person or voicemail box. Supported Not Supported
DIAL Initiate an outbound call to another party. Supported Supported
FOREACH Loop through an array, object or a list of Actions. Supported Supported
GOTO Jumps the call flow to a specified LABEL Action. Supported Supported
HANGUP Hang up a call. Supported Not Supported
IF Basic if-then-else conditional. Supported Supported
LABEL Sets the entry point for a GOTO Action. Supported Supported
PAUSE Wait to process more actions. Supported Supported
PLAY Play an audio file (or DTMF) to the caller. Supported Not Supported
QUEUE Add a caller to a queue. Supported Not Supported
RECORD Record the call. Supported Not Supported
RECORDMESSAGE Create a voicemail system. Supported Not Supported
REDIRECT Direct the call to another call flow script. Supported Not Supported
REJECT Deny the call from being connected. Supported Not Supported
SAY Read text to the caller. Supported Not Supported
SESSIONDATA Insert session_data into the call. Supported Supported
SMS Send caller a text message. Supported Supported
STOP Stop executing actions. Supported Not Supported
STREAM Stream call audio via WebSocket Messages. Supported Not Supported
TRANSCRIBE Use Speech-To-Text to Transcribe a live phone call. Supported Not Supported
TRANSFER Connect to another caller. Supported Not Supported
WEBHOOK Trigger a webhook to a designated URL. Supported Supported

Callback Request // Voice

When a phone call is received or initiated, Voxology will send a request to the URL that you designate in your callback configuration. The contents will include the information that we know about the phone call.

The request payload to your callback URL will be a JSON object by default. By setting the Content-Type in the callback configuration, you can choose to receive JSON, XML, url-encoded form data, or a URL with a query string.

Example Request // Call

{
  "service": "programmable_voice",
  "type": "end_call",
  "initiated_by": "pstn",
  "is_webhook": "false",
  "app_id": "29a471cc-4ada-4249-a7a5-5046464f9887",
  "subaccount_id": 0,
  "call_id": "12345@678",
  "parent_call_id": "12345@677",
  "external_id": "external_id_1234",
  "external_group_id": "group_id_1234",
  "start_time": "2016-09-20T21:32:28.471Z",
  "direction": "inbound",
  "duration": 9763,
  "status": "completed",
  "detection": "live_person",
  "caller_no": "+19495551212",
  "caller_no_latitude": "33.68248676492388",
  "caller_no_longitude": "-117.7953997688318",
  "caller_no_postal_code ": "92604",
  "caller_no_city": "Irvine",
  "caller_no_rate_center ": "IRVINE",
  "caller_no_lata": "730",
  "caller_no_region": "CA",
  "caller_no_country": "US",
  "caller_no_timezone": "America/Los_Angeles",
  "api_no": "+17145551212",
  "api_no_latitude": "33.83425593643128",
  "api_no_longitude": "-117.9138737441611",
  "api_no_postal_code": "92805",
  "api_no_city": "Anaheim",
  "api_no_lata": "730",
  "api_no_rate_center": "ANAHEIM",
  "api_no_region": "CA",
  "api_no_country": "US",
  "api_no_timezone": "America/Los_Angeles",
  "key_presses": [
    {
      "name": "collectName",
      "digits": "78",
      "history": ["12", "23", "45", "56", "78"]
    }
  ],
  "extension_dialed": null,
  "recordings": [{ "name": "recordingName", "id": "ABC123" }],
  "streams": [{
      "id": 775958172,
      "tracks": [{
          "name": "caller",
          "status": "stopped",
          "duration": 12482
      }]
  }],
  "last_queue_poll_connect_call": null,
  "custom_data": null,
  "session_data": null,
  "end_time": "2016-09-20T21:32:38.144Z",
  "sip_domain": "1234-56789.accounts.sip.voxolo.gy",
  "sip_forwarded_for": "192.168.1.1",
  "speech": [
    {
      "name":"collectName",
      "text":"detected speech",
      "confidence_score":"0.91"
    }
  ],
  "stir_shaken_status":"TN-Validation-Passed-A",
  "transfer":[
    {
      "call_id": "54321@123",
      "no": "+15551234567",
      "status": "completed",
      "start_time": "2016-09-20T21:32:28.471Z",
      "end_time": "2016-09-20T21:33:38.144Z"
    }
  ]
}

Request

Property Description Type When
service The Voxology service that is initiating the callback request. Options: programmable_voice string all
type Options: init_call, live_call, end_call, failed_call. string all
initiated_by Indicates the origin of the call. Possible values include api for outbound Make Call requests, sip_user and sip for inbound calls from SIP Users and SIP Interface, pstn for basic inbound calls, dial and transfer for outbound DIAL and TRANSFER action calls. string all
app_id The application ID for this request. string all
subaccount_id The Sub Account ID for this request. integer all
call_id The ID of the call. string all
parent_call_id When using the DIAL action, this is the call_id of the originating call. The value is null if there is no originating call. string live_call, end_call
external_id A user-defined ID for the call. string all
external_group_id A user-defined ID for a group of calls. string all
caller_no The phone number of the connected (or far end) call (E.164 format: +17145551212). string all
caller_no_latitude The latitude of the connected call’s phone number. Possibly null. string all
caller_no_longitude The longitude of the connected call’s phone number. Possibly null. string all
caller_no_postal_code The postal code (zip) of the connected call’s phone number. Possibly null. string all
caller_no_city The city of the connected call’s phone number. Possibly null. string all
caller_no_rate_center The rate center of the connected call’s phone number, if applicable. Possibly null. string all
caller_no_lata The lata of the connected call’s phone number, if applicable. Possibly null. string all
caller_no_region The two-character region (state) code of the connected call’s phone number. Possibly null. string all
caller_no_country The two-character country code of the connected call’s phone number. Possibly null. string all
caller_no_timezone The time zone of the connected call’s phone number (America/Los_Angeles). Possibly null. Click here for list of time zones. string all
api_no The phone number provisioned to the API (E.164 format: +17145551212). string all
api_no_latitude The latitude of the API phone number. Possibly null. string all
api_no_longitude The longitude of the API phone number. Possibly null. string all
api_no_postal_code The postal code (zip) of the API phone number. Possibly null. string all
api_no_city The city of the API phone number. Possibly null. string all
api_no_rate_center The rate center of the API phone number, if applicable. Possibly null. string all
api_no_lata The lata of the API phone number, if applicable. Possibly null. string all
api_no_region The two-character region (state) code of the API phone number. Possibly null. string all
api_no_country The two-character country code of the API phone number. Possibly null. string all
api_no_timezone The time zone of the API phone number (America/Los_Angeles). Possibly null. Click here for list of time zones. string all
start_time The time the call started. date init_call, live_call, end_call, webhook
end_time The time the call ended. date end_call
connect_time_sec The length of the call in seconds from time of connect. The value is in-progress on live_call callbacks and is final on end_call callbacks. Also used for billing purposes. integer live_call, end_call
direction Specifies the direction of the call: inbound or outbound string all
duration The length of the call in milliseconds. long all
status The current call state and progress. Codes: live-queued, live-ringing, live-in-progress, completed, busy, canceled, failed, no-answer. See the Call Status table for details on call status. string all
detection The likely “caller” on the far end. Codes: fax, live_person, voicemail, unknown. string all
key_presses[i] The keys pressed during the current CallFlow. array (object) live_call, end_call
key_presses[i].name The name of the COLLECT action that recorded these digits. Query string in a GET request converts to “key_presses.{name}={digits}”. string live_call, end_call
key_presses[i].digits The last group of digits pressed during the COLLECT. string live_call, end_call
key_presses[i].history The previous group or groups of digits pressed during the COLLECT action. This array is not returned in a callback query string. It is only returned in a callback POST body. array live_call, end_call
extension_dialed If an extension was dialed from a COLLECT action, the most recent extension dialed is stored here. array live_call, end_call
recordings[i] The recordings started with RECORD and/or saved with RECORDMESSAGE during the current CallFlow. array (object) live_call, end_call
recordings[i].name The name of the RECORD or RECORDMESSAGE action. Query string converts to “recordings.{name}={digits}”. string live_call, end_call
recordings[i].id The IDs of recordings from RECORD and RECORDMESSAGE. string live_call, end_call
streams[i] The media streams started with STREAM during the current CallFlow. array (object) live_call, end_call
streams[i].name The name of the STREAM action. Query string converts to “streams={streamObj}”. string live_call, end_call
streams[i].id The IDs of streams from STREAM. string live_call, end_call
streams[i].tracks[i].name The name of the track: caller. string live_call, end_call
streams[i].tracks[i].status The status of the track: active, paused, stopped. string live_call, end_call
streams[i].tracks[i].duration The length of the track in milliseconds. integer live_call, end_call
streams[i].stream_data The object containing data to be returned with the stream. object live_call, end_call
speech[i] The object containing data on the detected speech from a COLLECT action. object live_call, end_call
speech[i].name The name of the COLLECT action speech was detected for. string live_call, end_call
speech[i].text The detected speech from the COLLECT action. string live_call, end_call
speech[i].confidence_score A score from 0-1 indicating the estimated accuracy of the detected speech. This is assigned by the Google Speech API. float live_call, end_call
transfer[i] The object containing data on the second leg of a transferred call. array (object) live_call, end_call, webhook
transfer[i].call_id The ID of the call for the transfer leg. string live_call, end_call, webhook
transfer[i].no The number the call was transferred to. string live_call, end_call, webhook
transfer[i].status The current call state and progress of the transfer leg. Uses the same call status codes as all Voxology calls. See the Call Status table for details on call status string live_call, end_call, webhook
transfer[i].start_time The time the transfer leg started. date live_call, end_call, webhook
transfer[i].end_time The time the transfer leg ended. date live_call, end_call, webhook
stir_shaken_status A status indicating the STIR/SHAKEN attestation level assigned to the call; includes number validation on inbound calls. See the STIR SHAKEN Status table for details. string all
last_queue_poll_connect_call The last call bridged to this call via a QUEUE poll_connect. object live_call, end_call
last_queue_poll_connect_call.id The bridged call’s ID. string live_call, end_call
last_queue_poll_connect_call.no The bridged call’s phone number. string live_call, end_call
custom_data The custom data set in the callback configuration. object all
session_data The session_data set in the /Dials/Connect request and/or the DIAL and SESSIONDATA actions. object all
event_name The event_name set in the WEBHOOK action. If not a webhook request, this property is omitted. string webhook
webhook_data The webhook_data set in the WEBHOOK action. If not a webhook request, this property is omitted. object webhook
is_webhook The bool set to true if the callback response is coming from a WEBHOOK action, false otherwise boolean all
sip_domain The SIP domain assigned to the application or sub-account. string all
sip_forwarded_for The origin IP address of the SIP request. string all
error_code An error code for any error that occurred while making or receiving a phone call. See Call Flow Loop errors for details. integer all
error An descriptive error message about any error that occurred while making or receiving a phone call. See Call Flow Loop errors for details. string all

Callback Request // Message

When an inbound message is received, Voxology will send a callback request to the URL designated in the callback configuration of the phone number that received the message. The contents will include the information that Voxology knows about that message.

When an outbound message is sent using the Send Message Method, and a status_webhookis provided in the request, Voxology will send status update webhooks to the status_webhook.url endpoint.

The request payload to your callback URL will be a JSON object by default. By setting the Content-Type in the callback configuration, you can choose to receive JSON, XML, url-encoded form data, or a URL with a query string.

Example Request // Inbound SMS Callback

{
  "service": "programmable_messaging",
  "type": "sms",
  "app_id": "aaaa-bbbb-cccc-dddd-eeee",
  "subaccount_id": 0,
  "api_no": "+17145551212",
  "caller_no": "+19495551212",
  "error": null,
  "error_code": null,
  "api_no_region": "FL",
  "api_no_country": "US",
  "api_no_timezone": "America/New_York",
  "api_no_postal_code": "33444",
  "api_no_city": "Delray Beach",
  "api_no_latitude": "26.46081644913084",
  "api_no_longitude": "-80.07187504809512",
  "api_no_lata": "460",
  "api_no_rate_center": "DELRAY BEACH",
  "caller_no_region": "FL",
  "caller_no_country": "US",
  "caller_no_timezone": "America/New_York",
  "caller_no_postal_code": "33444",
  "caller_no_city": "Delray Beach",
  "caller_no_latitude": "26.46081644913084",
  "caller_no_longitude": "-80.07187504809512",
  "caller_no_lata": "460",
  "caller_no_rate_center": "DELRAY BEACH",
  "direction": "inbound",
  "custom_data": null,
  "session_data": {},
  "message_id": "SMI:2d784af7-1410-41bd-9e89-f978082506c3",
  "external_group_id": null,
  "external_id": null,
  "created_on": "2019-03-04T18:12:18.914Z",
  "num_parts": null,
  "uri": "/v1/Messages/SMI:2d784af7-1410-41bd-9e89-f978082506c3",
  "text_message": "inbound SMS message",
  "status": "received"
}

Example Request // Inbound MMS Callback

{
  "service": "programmable_messaging",
  "type": "mms",
  "app_id": "aaaa-bbbb-cccc-dddd-eeee",
  "subaccount_id": 0,
  "api_no": "+17145551212",
  "caller_no": "+19495551212",
  "group_nos": ["+19495551212", "+19495551213", "+19495551214"],
  "error": null,
  "error_code": null,
  "api_no_region": "FL",
  "api_no_country": "US",
  "api_no_timezone": "America/New_York",
  "api_no_postal_code": "33444",
  "api_no_city": "Delray Beach",
  "api_no_latitude": "26.46081644913084",
  "api_no_longitude": "-80.07187504809512",
  "api_no_lata": "460",
  "api_no_rate_center": "DELRAY BEACH",
  "caller_no_region": "FL",
  "caller_no_country": "US",
  "caller_no_timezone": "America/New_York",
  "caller_no_postal_code": "33444",
  "caller_no_city": "Delray Beach",
  "caller_no_latitude": "26.46081644913084",
  "caller_no_longitude": "-80.07187504809512",
  "caller_no_lata": "460",
  "caller_no_rate_center": "DELRAY BEACH",
  "direction": "inbound",
  "custom_data": null,
  "session_data": {},
  "message_id": "SMI:2d784af7-1410-41bd-9e89-f978082506c3",
  "external_group_id": null,
  "external_id": null,
  "created_on": "2019-03-04T18:12:18.914Z",
  "num_parts": null,
  "uri": "/v1/Messages/SMI:2d784af7-1410-41bd-9e89-f978082506c3",
  "text_message": "inbound MMS message",
  "status": "received",
  "media_urls": [
    {
      "url": "https://exampleMediaURL.com/1",
      "content_type": "application/smil"
    },
    {
      "url": "https://exampleMediaURL.com/2",
      "content_type": "image/jpeg"
    }
  ]
}

Request

Property Description Type When
service The name of the service. Returns: programmable_messaging. string all
type The type of message. Returns: sms, mms string all
app_id The Application ID for this request. string all
subaccount_id The Sub Account ID for this request. integer all
api_no The Voxology phone number (near end) that is provisioned to the API (E.164 format: +17145551212). string all
api_no_latitude The latitude of the Voxology phone number (near end). Possibly null. string inbound
api_no_longitude The longitude of the Voxology phone number (near end). Possibly null. string inbound
api_no_postal_code The postal code (zip) of the Voxology phone number (near end). Possibly null. string inbound
api_no_city The city of the Voxology phone number (near end). Possibly null. string inbound
api_no_rate_center The rate center of the Voxology phone number (near end), if applicable. Possibly null. string inbound
api_no_lata The lata of the Voxology phone number (near end), if applicable. Possibly null. string inbound
api_no_region The two-character region (state) code of the Voxology phone number (near end). Possibly null. string inbound
api_no_country The two-character country code of the Voxology phone number (near end). Possibly null. string inbound
api_no_timezone The time zone of the Voxology phone number (near end) (America/Los_Angeles). Possibly null. Click here for list of time zones. string all
caller_no The user’s phone number (far end) that interacted with the API (E.164 format: +19495551212). string all
caller_no_latitude The latitude of the user’s phone number (far end). Possibly null. string inbound
caller_no_longitude The longitude of the user’s phone number (far end). Possibly null. string inbound
caller_no_postal_code The postal code (zip) of the user’s phone number (far end). Possibly null. string inbound
caller_no_city The city of the user’s phone number (far end). Possibly null. string inbound
caller_no_rate_center The rate center of the user’s phone number (far end), if applicable. Possibly null. string inbound
caller_no_lata The lata of the user’s phone number (far end), if applicable. Possibly null. string inbound
caller_no_region The two-character region (state) code of the user’s phone number (far end). Possibly null. string inbound
caller_no_country The two-character country code of the user’s phone number (far end). Possibly null. string inbound
caller_no_timezone The time zone of the user’s phone number (far end) (America/Los_Angeles). Possibly null. Click here for list of time zones. string inbound
error_code The error code, if any, associated with your message. If your message status is failed or undelivered, the error_code can give you more information about the failure. The value will be null if the message was delivered successfully. integer all
error The human readable description of the error_code above. string all
direction Specifies the direction of the message: inbound or outbound string all
custom_data The custom data set in the callback configuration. object inbound
created_on The date/time the message was received (inbound). ISO Date inbound
updated_on The date/time this message resource was last updated. ISO Date outbound
message_id The unique message ID of the message. string all
external_group_id A queryable name for a group of messages. string outbound
external_id A queryable name for the messages. string outbound
num_parts The number of parts that make up the message. If the message body is too large to be sent as a single SMS message, it will be segmented and charged accordingly. Inbound messages of over 160 characters will be reassembled when the message is received. integer all
uri The URI for this resource, relative to https://api.voxolo.gy. string all
text_message The text body of the message. Up to 1600 characters. string inbound
status The status of the message. Returns: accepted, queued, sending, sent, failed, delivered, undelivered, receiving, or received. string all
media_urls An array of URLs pointing to the media included in an MMS message. array inbound mms
media_urls[i].url The URL pointed to the provided media. string inbound mms
media_urls[i].content_type The file type of the provided media. string inbound mms

Example Request // Outbound Message Status Webhook

{
  "service": "programmable_messaging",
  "type": "sms",
  "app_id": "aaaa-bbbb-cccc-dddd-eeee",
  "subaccount_id": 0,
  "api_no": "+19495551212",
  "caller_no": "+17145551212",
  "direction": "outbound",
  "message_id": "SMO:cb3c8770-c321-4004-b60c-b6db9cdd6ad6",
  "updated_on": "2019-03-04T18:12:18.075Z",
  "uri": "/v1/Messages/SMO:cb3c8770-c321-4004-b60c-b6db9cdd6ad6",
  "external_group_id": "group_id",
  "external_id": "extern_id",
  "num_parts": 1,
  "error": null,
  "error_code": null,
  "status": "queued"
}

Callback Response

To control the call, Voxology expects a response with one or more Call Flow Actions.

The response to control the call can be in JSON or CCML. Set the Content-Type header to application/json or application/xml respectively.

Any non-2xx HTTP status code will trigger a request to the callback_failover endpoint. If there is no callback_failover endpoint, the call will terminate. In addition, a 204 status code will also terminate the call as it would indicate an empty message body.

A soft callback response limit of 31.415 kb. Exceeding this limit will generate a warning in the logs, but it won’t stop the calls. A hard callback response limit of 81 kb. Exceeding this limit will throw an error.

The JSON response we measure is the Minimized Size - the size of your JSON response with all whitespace characters removed. Please note that you don’t have to send us the JSON in this form, it is just how we measure it.

Response

Parameter Description Type Required
actions An array of Action objects, executed in the order given. string Yes
name An optional name to help identify the response. Example: MainMenu. string No
comments Optional comments to help document this response. string No

Example Response

{
  "actions": [
    {
      "type": "SAY",
      "params": {
        "text": "Hello, ${sessionData.firstName}. Welcome to our conference.",
        "loop": 1
      }
    },
    {
      "type": "CONFERENCE",
      "params": {
        "name": "myConference"
      }
    },
    {
      "type": "SAY",
      "params": {
        "text": "You have left the conference. This call lasted ${callTime} milliseconds."
      }
    }
  ]
}

Error Handling

Call failures during the call flow loop can happen for a variety of reasons including, but not limited to, your balance dropping to $0, an invalid JSON response to our callback requests, a non-2XX status from your callback url, etc.

When an error occurs during the call flow loop, you will see error details in both the end_call Callback Requests and in the Call Logs. In addition, if a failure happens during the call, the caller will hear a generic audio error on the phone that generally includes a specific error code.

In the Error section below you can see the list of Call Flow Loop errors, including the error code, what the caller hears on the phone, and what the issue might be.

View the list of Call Flow Loop errors.

REST API

The Voxology REST API enables you to initiate, modify, and query meta data on phone calls. It also allows you to manage your account, applications, sub accounts, phone numbers, recordings, and callback configurations.

Base URL

All URLs referenced in the documentation have the same base API endpoint, which is served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported.

HTTPS API Endpoint

https://api.voxolo.gy/v1

Should you require cross-origin resource sharing (CORS) support, we have you covered.

HTTPS API Endpoint // CORS

https://api.voxolo.gy/CORS/v1

Authentication

The Voxology API is authenticated using either Basic Authentication or an API Key. For Account-level requests, use Basic Authentication. For Application-level requests, pass the API Key in a X-API-Key header. Each API method will specify which type of authentication is required.

As a general rule of thumb, Application-level API methods are used for everything related to managing phone numbers, voice, and sms, whereas Account-level requests are used for billing and payments.

Basic Authentication credentials can be found in the Developer Portal on the “Manage Account” page under the "API Credentials (Basic Auth)” tab, which you can find by clicking on the top right hand profile icon.

The API Key (X-API-Key) can be found in the Developer Portal under the “Application” -> “Application Details” page under the “API Credentials (API Key)” tab.

Application Sub Accounts

Application Sub Accounts are a way to isolate usage of the api within a single application, including phone numbers, calls, sms, conferences, queues, logs and recordings. Think of them as child-applications under the main application. For example, if your application services multiple users, you might want to give each user its own Sub Account, thereby isolating their usage from your other users. This isolation extends to call behavior, reporting and API methods.

Example Request // Phone Numbers

GET /SubAccounts/{id}/PhoneNumbers

To use a Sub Account, simply prepend a regular API method with /SubAccounts/{id}.

Application Sub Accounts have the expected CRUDing methods.

Example Request // Make Call

POST /SubAccounts/{id}/Dials/Connect

Pagination

Voxology’s API supports pagination and provides a request query to control how pagination will respond to specific methods.

Request Query

Name Description Type Required
page The page number to return. Zero-based index. Defaults to 0 integer No
page_size The number of results per page. Defaults to 25 integer No

Response

Parameter Description Type
pagination Information about the request pagination. object
pagination.current_page The page returned. integer
pagination.total_pages The number of pages available. integer
pagination.total_items The total number of items available. integer
pagination.items_per_page The maximum number of items allowed per response. integer

Example Response

{
  "subaccounts": [
    {
      "id": 0,
      "name": "My First Sub Account"
    }
  ],
  "pagination": {
    "current_page": 0,
    "total_pages": 1,
    "total_items": 1,
    "items_per_page": 10
  }
}

Request

Voxology’s API is organized around REST principles, accepts JSON, and supports the following HTTP Verbs:

To see a list of all supported methods, click here.

Response

All responses will return JSON.

Any 2xx status codes are considered a success.

A table with response codes is included in the documentation with each REST method.

Error Handling

Any non-2xx HTTP status code is considered a request failure.

4xx errors are caused by the developer (for example, “401 Unauthorized” and “404 Not Found”).

5xx errors are caused by exceptions within the Voxology platform. These errors are not caused by the developer and should be reported to Voxology, if possible. It is likely a systematic error that will need to be fixed.

Response

Property Description Type
ref_id A unique identifier for the error. string
status The HTTP status code of the error. integer
code A more detailed error code, often prepended with the status code. For example, 401005. Note: These codes are subject to revision until v1. integer
message A human readable message about the error. string
help Any information that may help resolve this error. string
user_message A diplomatic message that can be shown to the end user. string

Example Response:

{
  "ref_id": "f3749fj290djk29fj239dji9j",
  "status": 400,
  "code": 401005,
  "message": "authentication is possible but has failed ",
  "help": "The request must include the header named X-API-Key.",
  "user_message": "A 3rd-party service could not understand your
  request. This could be due to submitting invalid data."
}

All API Actions and Methods will inform the developer of success or failure. A full accounting of all error messages may be found in the Errors section of this reference. Also, all Actions and Methods have a Response Codes table which provides a list of specific error messages for that Action or Method.

Media Stream

Voxology’s Media Stream service enables you to stream real-time audio from phone calls to a user-defined endpoint via a WebSocket. Media Stream is supported on phone calls placed or received on Voxology’s platform on both the Programmable Voice API and SIP Trunks.

WebSocket Messages

When you designate a stream.url in the STREAM Call Flow Action or on a SIP Trunk, Voxology will send a series of WebSocket Messages to the specified URL. The contents will include five different types of messages, which include media chunks and other information that is known about the phone call. The request payload to your stream URL will be a JSON object and the media will be Base64 (base_64) encoded. In addition to receiving the audio from the call, the WebSocket Messages will include phone numbers, call direction, call IDs, and the controls to stop/resume the stream.

Message Types

Type Description When Frequency
init_stream The first message sent when a WebSocket stream is initiated. This message describes which tracks will be included in the subsequent messages and includes other information about the phone call. WebSocket opens Once per streamed call
start_track This message is sent after the init_stream and includes specifics about the media type and format. Each track that is streamed will have its own start_track message. Each track begins Once per streamed track, multiple tracks may be streamed simultaneously per call
live_track This message includes the raw audio data from the track, delivered in chunks. While each track is live Multiple per track, based on length of call and chunk size
stop_track This message is sent once a track has stopped. Each track stops Once per streamed track, multiple tracks may be streamed simultaneously per call
end_stream This message is sent once the stream is closed and all tracks from the call have concluded. WebSocket closes Once per streamed call

Stream Messages

Voxology will send both an init_stream and end_stream WebSocket message for each call that is streamed. Stream messages include information about the phone call as well as which tracks will be streamed.

Property Description Type When
service The Voxology service that is initiating the stream request. Options: programmable_voice, sip_trunking string init_stream, end_stream
type Options: init_stream and end_stream. string init_stream, end_stream
app_id The Application ID from which the stream was initiated. string init_stream, end_stream
subaccount_id The Sub Account ID from which the stream was initiated. integer init_stream, end_stream
call_id The ID of the call from where the stream is coming. string init_stream, end_stream
direction Specifies the direction of the call: inbound or outbound string init_stream, end_stream
stream_id The ID of the stream. string init_stream, end_stream
stream_sequence_number The first message from the stream begins with 1 and increments with each subsequent message. integer init_stream, end_stream
stream_name The name of the STREAM action that initiated the stream. Query string converts to “streams.{name}={???}”. string init_stream, end_stream
stream_data The stream_data is set in the STREAM action. object init_stream, end_stream
tracks[i] An array of objects containing the tracks that are being streamed. array init_stream, end_stream
tracks[i].name The name of the track being streamed from the call. Returns: caller (far end on API), transfer (transfer leg on API), near (on SIP Trunk), far (on SIP Trunk) string init_stream, end_stream
tracks[i].start_time The date/time the track was initiated. ISO Date end_stream
tracks[i].end_time The date/time the track ended. ISO Date end_stream
tracks[i].duration The length of the track in milliseconds. long end_stream
error_code The error code, if any, associated with the stream. The error_code can give you more information about a failure. The value will be null if the stream was successful. integer end_stream
error The human readable description of the error_code above. string end_stream

Track Messages

Voxology will send a start_track, stop_track, and multiple live_track WebSocket Messages for each track that is specified to be streamed per call. Track messages include the media, media format, and some basic information about the call.

Property Description Type When
type Options: start_track, live_track, or stop_track string start_track, live_track, stop_track
call_id The ID of the call from where the stream is coming. string start_track, live_track, stop_track
stream_id The ID of the stream. string start_track, live_track, stop_track
name The name of the track being streamed from the call. Returns: caller (far end on API), transfer (transfer leg on API), near (on SIP Trunk), far (on SIP Trunk) string start_track, live_track, stop_track
track_sequence_number The first message from this track will begin with ‘1’ and increment with each subsequent message. integer start_track, live_track, stop_track
api_no The Voxology phone number (near end) that is provisioned to the API (E.164 format: +17145551212). string start_track, stop_track
caller_no The user’s phone number (far end) that interacted with the API (E.164 format: +19495551212). string start_track, stop_track
media_format An object containing information about the media format. object start_track
media_format.type The type of encoding: base_64. string start_track
media_format.sample_rate The sample rate in hertz of the media. Defaults to: 8000 integer start_track
media_format.chunk_size The duration of media delivered in each live_track audio message. integer start_track
start_time The date/time the track was initiated. ISO Date start_track, stop_track
end_time The date/time the track ended. ISO Date stop_track
duration The length of the track in milliseconds. long stop_track
media Base64 encoded raw audio. string live_track

Statuses

Call Status

Calls placed or received on the Voxology platform are assigned a status which describes the current state of the call. Call statuses can be in an ‘In Progress’ or 'Final’ state, and they can be found in the Callback Requests, Call Logs, and Live Call responses.

Status Description State
live-queued Call instance was created and waiting to be dialed. In Progress
live-ringing Call has been dialed and is currently ringing. In Progress
live-in-progress Call has been connected and is currently in progress. In Progress
completed Call was connected and has now ended. Final
no-answer Call was attempted but the timeout value elapsed prior to connect, or the far end did not connect after ringing. Final
busy Call was attempted and received a busy signal. Final
canceled Call was attempted and hung up on while queued or ringing. Final
failed Call was attempted but never connected due to a failure at the PSTN. Final
restricted Call was not attempted because of a restriction setting. Final
error Call was not attempted because of a user or system error. Final
unknown Call status is unknown. Final

Message Status

Messages sent or received via the Voxology platform are assigned a status which describes the current state of the message. Message statuses can be in an 'In Progress’ or 'Final’ state, and they can be found in the Inbound Message Callback Requests, Outbound Message Status Webhook, and Message Logs responses.

Status Description Direction State
accepted Message request was received by Voxology, a message instance was created, and is being queued. Outbound In Progress
queued Message has been queued and is waiting to be sent. Outbound In Progress
sending Message has left the queue and is in the process of being sent. Outbound In Progress
sent Message was sent and accepted by an upstream carrier. Outbound Final or In Progress
delivered Message was sent, accepted by an upstream carrier, and also received a delivery confirmation from a carrier. Note: not every successful message delivery will receive a delivery confirmation. Therefore sent can be the final status on a message that was delivered successfully. Outbound Final
undelivered Message was sent, but it could not be delivered. This can be returned in cases where the number can not receive SMS, such as a landline. This comes from the upstream carrier. Outbound Final
failed Message could not be sent. This can occur because the account is out of funds, the account has been suspended, duplicate messages are being sent to the same number, and more. This status comes from our platform and the account is not charged for failed messages. Outbound Final
opt-out Message could not be sent. The far end number (caller_no) has previously replied ‘STOP’ to a message from a phone number on your Application (Parent) or Sub Account (Child). The far end number can choose to resume communications by replying ‘START’, which will remove their number from the opt-out list. This status comes from our platform, and the account is not charged for messages with the status opt-out. Outbound Final
received Message was received by Voxology and delivered to your phone number. If you have set a Call Flow configuration (either default or on the phone number) a callback of type sms will be sent to your callback.url with this status. Inbound Final

Phone Number Status

Phone Numbers that are provisioned on the Voxology platform are assigned a status which describes the current state of the phone number. Phone Number statuses can be in an 'In Progress’, 'Resting’ or 'Final’ state, and they can be found in various responses to Phone Number Requests.

Status Description State
reserving Provision Phone Number request was received by Voxology, the phone number object was created, and is being reserved. In Progress
reserved Phone Number has been reserved and is waiting to be routed. In Progress
reserved_routing_error Phone Number reached an error state during the process of being routed and has been temporarily reserved. Contact support to fix. Resting
routing Provision Phone Number request was received by Voxology, the phone number object was created, and is being routed. In Progress
routed Phone Number has been provisioned, routed, and is ready for use. Resting
released Phone Number has been released and is no longer under the control of the user. Final
paused Phone Number has been temporarily paused. Contact support to fix. Resting
error Provision Phone Number request was received, but an error occurred during the provisioning process, and the number may no longer be available for provisioning. Final

STIR SHAKEN Status

STIR/SHAKEN, or SHAKEN/STIR, is a technology framework designed to reduce fraudulent robocalls and illegal phone number spoofing. Calls are examined by the caller’s service provider to determine ownership of the calling number and the attestation, or trust level, of the caller. This information is stored in an “Identity” header on the call which can be verified by the receiving provider to ensure authenticity.

The stir_shaken_status on inbound calls to Voxology contains both the verification of the Identiy header as well the attestation of the caller. On outbound calls, the stir_shaken_status contains only the attestation. For more information on STIR/SHAKEN, please see What Is STIR/SHAKEN

Status Description Direction
A The customer is known by Voxology and the calling number has been verified. Outbound
B The customer is known by Voxology however the calling number has not been verified. Outbound
C The customer is not known by Voxology and the calling number is unverified. Outbound
TN-Validation-Passed-A Voxology verified the Identity header of the caller and the call was assigned attestation level A by the originating service provider. Inbound
TN-Validation-Failed-A Voxology was unable to verify the Identity header of the caller and the call was assigned attestation level A by the originating service provider. Inbound
TN-Validation-Passed-B Voxology verified the Identity header of the caller and the call was assigned attestation level B by the originating service provider. Inbound
TN-Validation-Failed-B Voxology was unable to verify the Identity header of the caller and the call was assigned attestation level B by the originating service provider. Inbound
TN-Validation-Passed-C Voxology verified the Identity header of the caller and the call was assigned attestation level C by the originating service provider. Inbound
TN-Validation-Failed-C Voxology was unable to verify the Identity header of the caller and the call was assigned attestation level C by the originating service provider. Inbound

Session Data

In order to customize your call flows, it is possible to assign unique session data for each call. This data will be returned with the Call Flow Callback Request for the lifetime of the call in the session_data property as a JSON object.

Tools

You can freely read and write to the session_data property through the following ways:

Example Callback Response // Call Flow using Session Data

{
  "actions": [
    {
      "type": "SAY",
      "params": {
        "text": "This is ${sessionData.doctor} office calling to confirm your appointment on ${sessionData.day}, ${sessionData.month}, ${sessionData.date} at ${sessionData.time}."
      }
    }
  ]
}

Cut Back On Callbacks

You may leverage session_data as a User-Defined Variable while building your call flows using our JSON Actions. This coupled with our conditional actions (IF, GOTO, LABEL) enable you to move much of your conditional logic into Voxology to cut down on chatter between our server and your server which increases reliability and speed, and cuts down on the code you have to maintain in handling callbacks requests.

Transcription

Voxology’s Transcription service enables you to transcribe audio from phone calls using speech-to-text technology. Transcription is only supported on phone calls placed or received in the Programmable Voice API; adding transcription to Voxology’s SIP Trunks is on the product roadmap.

Transcript Webhooks

When using transcription, Voxology will deliver the call transcript, and other information about the call, in the body of a webhook sent to a predefined URL. Every transcribed call receives the complete transcript in a single webhook when either the call ends or transcription is stopped, but customers also have the option to receive live results in a series of webhooks during the call.

Webhook Types

Type Description Frequency
live_transcript These webhooks contain live results of a transcribed call and are sent after each spoken utterance, defined by a pause in speech audio. Multiple per call
end_transcript This webhook contains the complete transcript of a call and is sent only after the call ends or transcription is stopped. Once per call

Request

Property Description Type When
service The Voxology service that placed or received the call being transcribed. Values can be programmable_voice or sip_trunking. string live_transcript, end_transcript
type Options: live_transcript and end_transcript. string live_transcript, end_transcript
app_id The Application ID from which the call was placed or received. string live_transcript, end_transcript
subaccount_id The Subaccount ID from which the call was placed or received. integer live_transcript, end_transcript
start_time The start time of transcription in UTC. date live_transcript, end_transcript
end_time The end time of transcription in UTC. date end_transcript
call_id The unique Voxology call ID of the call being transcribed. string live_transcript, end_transcript
api_no The provisioned (or near end) phone number connected to the call. string live_transcript, end_transcript
caller_no The phone number of the connected (or far end) call. string live_transcript, end_transcript
direction Specifies the direction of the call: inbound or outbound. string live_transcript, end_transcript
transcribe_name The user-defined name of the TRANSCRIBE action that initiated transcription. string live_transcript, end_transcript
transcript[i] An array of transcript objects containing the transcription results. array live_transcript, end_transcript
transcript[i].track_name The name of the call track that was transcribed. Returns: caller (far end) or transfer (transfer leg). string live_transcript, end_transcript
transcript[i].sequence_number The transcription result sequence number, can be used to order transcript results chronologically. integer live_transcript, end_transcript
transcript[i].text The speech audio that was transcribed on the call. string live_transcript, end_transcript
transcript[i].confidence_score A score from 0.0 (lowest) to 1.0 (highest) estimating the accuracy of the transcript. float live_transcript, end_transcript
transcript[i].timestamp The elapsed time, in milliseconds, from the start of the call to the time the transcription result was received. ISO Date live_transcript, end_transcript

Actions

COLLECT

Record Key Presses and Speech from Callers.

A loop can contain one or more COLLECT actions. The results will be returned in the callback and identified by the COLLECT action’s name.

The COLLECT object also accepts an actions array (optional). This array accepts PLAY, SAY, and PAUSE actions. These “child actions” will play before a COLLECT and cancel all on the first key press, letting the COLLECT action record the key without waiting.

The digits pressed and speech detected in the COLLECT action will be returned in the callback request.

Note: To collect speech from the caller you need to add your Google Speech-to-Text credentials in the Voxology Portal.

Request

View standard request details HERE

Response

Parameter Description Default Type Required
finish_on_key The key to press to end the timeout when key presses are less than num_digits. Accepts: off, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, #, *. # string No
finish_on_extension If set to true, the COLLECT action will detect when the key presses match an existing Extension on your Voxology application and leave the COLLECT action. false boolean No
num_digits The maximum number of key presses to record before leaving the COLLECT action. 1 integer No
timeout How long in milliseconds to wait for the next key press. 5000 integer No
input The type of caller input to collect. Accepts: key_presses, speech, key_presses_and_speech. key_presses string No
hints A list of possible keywords expected in the caller’s response to assist in accurate speech detection. [] string[] No
language The language for speech detection. Accepts: en-US, fr-FR, de-DE, es-ES. en-US string No
profanity_filter Removes profanity from the speech_to_text array returned in the callback request. Accepts: enabled, disabled. disabled string No

Example Response // Key Presses

{
  "actions": [
    {
      "name": "rating",
      "type": "COLLECT",
      "actions": [
        {
          "type": "SAY",
          "params": {
            "text": "Press 1 for yes. Press 2 for no."
          }
        }
      ],
      "params": {
        "finish_on_key": "#",
        "num_digits": 1,
        "timeout": 5000
      },
      "comments": "Rating of the user experience."
    }
  ]
}

Example Response // Speech

{
  "actions": [
    {
      "name": "rating",
      "type": "COLLECT",
      "actions": [
        {
          "type": "SAY",
          "params": {
            "text": "Say yes or no."
          }
        }
      ],
      "params": {
        "input": "speech",
        "hints": [
          "yes",
          "no"
        ],
        "language": "en-US"
      }
    }
  ]
}

Example Response // Advanced

{
  "actions": [
    {
      "$nextUrl": "'operator.json'"
    },
    {
      "type": "LABEL",
      "name": "PROMPT_MENU_CHOICE"
    },
    {
      "type": "COLLECT",
      "actions": [
        {
          "type": "SAY",
          "params": {
            "text": "Press 1 or say Sales for Sales.  Press 2 or say Service for Customer Service."
          }
        }
      ],
      "params": {
        "num_digits": 1,
        "input": "key_presses_and_speech",
        "hints": [
          "sales",
          "service"
        ],
        "language": "en-US"
      }
    },
    {
      "type": "IF",
      "condition": "! $keyPresses && ! $speechToText && $collectAttempt < 3",
      "then": [
        {
          "type": "GOTO",
          "params": {
            "label": "PROMPT_MENU_CHOICE"
          }
        }
      ]
    },
    {
      "type": "IF",
      "condition": "$keyPresses=='1' || ($speechToText == 'sales' && $speechConfidenceScore >= 0.9)",
      "then": [
        {
          "$nextUrl": "'sales.json'"
        }
      ]
    },
    {
      "type": "IF",
      "condition": "$keyPresses=='2' || ($speechToText == 'service' && $speechConfidenceScore >= 0.9)",
      "then": [
        {
          "$nextUrl": "'service.json'"
        }
      ]
    },
    {
      "type": "REDIRECT",
      "params": {
        "url": "${nextUrl}"
      }
    }
  ]
}

CONFERENCE

Initiates a conference event.

Placing a caller into a conference with a new name will initiate a new conference. Subsequent callers can join the same conference using the same conference name. The CONFERENCE action supports a variety of parameters and events that can be set on a per caller basis and may also be modified via REST methods found here.

Request

View standard request details HERE.

Response

Parameter Description Default Type Required
name A unique name to identify the conference. Using the same name will put callers into the same conference. Accepts: alpha-numeric, underscores, and dashes. string* Yes
hold_audio The url of the audio file to play when a participant is on hold. If omitted, our default hold music will play. Supports MP3, WAV, and M4A. WAV will often perform better. string No
auto_hold If true, the conference will automatically play hold music if only one call is in the room. false boolean No
join_muted Indicates whether the participant joins the conference muted or not. false boolean No
max_participants At the moment of joining, if the number of conference participants exceeds this amount, the joiner will be blocked. Participants who attempt to exceed the limit can be handled with an error handler. Infinity** integer No
announce_on_join Causes a beep to play to the conference when a participant joins and leaves. Accepts: beep or null. null string No
mute_on_key Which key combination will let the caller mute himself. Accepts: #, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, *, or off to disable this feature. off string No
unmute_on_key Which key combination will let the caller unmute himself. Accepts: #, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, *, or off to disable this feature. off string No
exit_on_key Which key combination will let the caller exit the conference. Accepts: #, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, *, or off to disable this feature. off string No
hold_on_join If true, participants will enter the Conference on hold until a participant joins with start_on_join. false boolean No
start_on_join If true, the Conference will start and remove everybody from hold. Used with hold_on_join. true boolean No
end_on_exit If true, the Conference will immediately end when this participant leaves. All other participants will resume the call flow. false boolean No
hold_on_exit If true, when this participant leaves the Conference, all other participants will be put on hold. false boolean No
send_dtmf If true, dtmf (digit presses) entered by the participant will be passed into the Conference. However it will only be received by other participants who have receive_dtmf set to true. false boolean No
receive_dtmf If true, participant will receive dtmf (digit presses) that are passed into the Conference by other participants. However they will only receive dtmf from participants who have send_dtmf set to true. false boolean No

Example Response

{
  "actions": [
    {
      "type": "CONFERENCE",
      "params": {
        "name": "my-conference",
        "max_participants": 10,
        "mute_on_key": "1",
        "unmute_on_key": "3",
        "exit_on_key": "#0"
      },
      "events": {
        "on_enter": [
          {
            "type": "SAY",
            "params": {
              "text": "You are now joining the conference."
            }
          },
          {
            "type": "WEBHOOK",
            "params": {
              "event_name": "onEnterConference"
            }
          }
        ],
        "on_enter_error_max_participants": [
          {
            "type": "SAY",
            "params": {
              "text": "I'm sorry. The conference is full."
            }
          }
        ]
      }
    }
  ]
}

Note: To hear another call’s early media, you must have the CONFERENCE action as the first action. It also cannot have any on_enter event handlers. Conferences can trigger events when a participant joins or a join attempt fails. Attempts can fail, for example, if the max participants limit is reached. Event handlers are a list of actions that execute when specified events are triggered.

Events

Event Description
on_enter_started This handler will run when a Conference is in progress. By default, Conferences are created in progress. hold_on_join will cause a Conference to wait for specified participants before starting.
on_enter_waiting This handler will run when a caller enters a conference that is still on hold.
on_enter This is a catch-all handler. These actions will always execute last.
on_enter_error_max_participants This handler will run when a participant attempts to join a Conference that is at its max_participants limit.
on_enter_error_ended This handler will run when a participant attempts to join a Conference that has ended.
on_enter_error This handler will always run on any error condition.
on_enter_alone This handler will run when a caller enters a conference and is the only conference participant.

DETECT

Detects whether a live person or voicemail system answers the outbound call.

If the callee is a voicemail service, the action will wait to execute the on_voicemail event after the beep.

Request

View standard request details HERE

Response

Parameter Description Default Type Required
trigger_live_in_ms Change the default wait time after the call connects to detect live person or voicemail before playing the live person event by default. 3000 integer No

Example Response

{
  "type": "DETECT",
  "params": {
    "trigger_live_in_ms": 3000
  },
  "events": {
    "on_live_person": [
      {
        "type": "SAY",
        "params": {
          "text": "Welcome to the call. You will be joined to the conference shortly."
        }
      }
    ],
    "on_voicemail": [
      {
        "type": "SAY",
        "params": {
          "text": "Sorry we missed you. We will try to call you at a later time."
        }
      }
    ]
  }
}

Detect Events

Event Description Required
on_live_person This event accepts an array of Call Flow Actions (PLAY, SAY, COLLECT, ETC.) that are triggered when a live person is detected on the call, or after the trigger_live_in_ms value is reached.

Please note that DETECT continues to analyze the call after this event is triggered, and it and may later determine that the call was indeed answered by a voicemail system, in which case it will trigger the on_voicemail event.		 Yes
on_voicemail This event accepts an array of Call Flow Actions (PLAY, SAY, HANGUP, etc.) that are triggered when a voicemail system is detected as answering the call and then indicates that it is ready to record a voice message (for example, after the ‘beep’). Yes
on_voicemail_early This event accepts an array of Call Flow Actions (SMS, HANGUP, etc.) that fire as soon as a voicemail system is detected as answering the call. It does not attempt to wait to leave a voice message. No

DIAL

Initiates a new, independent phone call (not connected to the current call). This is equivalent to the Dials/Connect REST request.

While this action initiates a new phone call during the middle of another live call, it does not connect the two calls together; rather, it dials the specified no and, upon answer, routes the call to the given CallFlow config, based on the caller_id_no or override_callback_config.

DIAL is useful in call flows where you are dropping two or more callers into a conference, but you want to retain control over all legs of the call, like click to call, shark tank, etc.

You will receive a failed_call callback to your originating callflow endpoint if the DIAL action attempts to dial a bad or misformatted number, or if your DIAL action times out.

If you are trying to connect two callers, and you do not need to retain control over the second leg of the call, you can use the TRANSFER action.

Note: To initiate a phone call via our REST API, see Make Call.

Request

View standard request details HERE

Response

Parameter Description Default Type Required
no The phone number or SIP destination to call. Phone numbers are in E.164 format (example: +19495551212). SIP destinations are formatted as abc123@sip.mypbx.com. string* Yes
caller_id_no The phone number that will appear as the Caller ID. Phone numbers are in E.164 format (example: +19495551212). This phone number should have been previously provisioned and assigned to CallFlows and configured with a CallFlow Callback. Defaults to the inbound number (api_no in your callback). string* No
user_sip_headers The key/value pair(s) in this object will be flattened and converted to User-to-User and X-... SIP headers to be included when dialing to a SIP address. This allows you to pass along custom data on dial. The key(s) must be: User-to-User OR must start with an X-. string No
detection How to identify a connection. Accepts: preconnect, full, none. string No
override_callback_config The phone number that is associated with the override configuration. Phone numbers are in E.164 format (example: +19495551212). If set, this number will be used to load a Callback Config, ignoring caller_id_no. This is useful when making an outbound call from a Caller ID or not setting up Callback Configs for every Inbound Number. string* No
inbound_api The inbound API to route the call to. Currently only uses CallFlows. CallFlows string No
max_call_time The maximum length of the call in seconds. Valid: 60 to 172800. 86400 integer No
timeout The maximum time to wait during ringing in seconds. Valid: 20 to 240. 50 integer No
session_data This object will be included in the CallFlows callback, allowing custom data to be passed on dial. object,string* No

Example Responses

{
  "actions": [
    {
      "type": "DIAL",
      "params": {
        "no": "+19495551111"
      }
    },
    {
      "type": "DIAL",
      "params": {
        "no": "abc123@sip.mypbx.com",
        "user_sip_headers": {
          "User-to-User": "hi",
          "x-name": "${sessionData.name}",
          "x-call-id": "${callId}",
          "x-string": "hello world"
        },
        "caller_id_no": "+17145552222",
        "detection": "preconnect",
        "inbound_api": "CallFlows"
      },
      "session_data": {
        "name": "Bob",
        "age": 21
      }
    },
    {
      "type": "DIAL",
      "params": {
        "no": "+19495551111",
        "caller_id_no": "+17145552222"
      },
      "session_data": "$sessionData"
    },
    {
      "type": "DIAL",
      "params": {
        "no": "+19495551111",
        "caller_id_no": "+17145552222"
      },
      "events": {
        "on_error": [
          {
            "type": "SAY",
            "params": {
              "text": "This call could not be dialed."
            }
          }
        ]
      }
    }
  ]
}

Events

Event Description
on_error If this DIAL action fails for any reason, this event will fire and execute any actions therein. The reason for the error can be found in the Call Logs.

FOREACH

The FOREACH Action is a convenient way to loop through an array or object without having to worry about counting the number of elements.

The FOREACH Action loops through a provided list of Actions once for each element in the data structure, automatically exiting when the elements are all exhausted. This list of Actions has access to each value, key and index of the current element.

Request

View standard request details HERE

Response

Parameter Description Default Type Required
params.iterator The variable with the assigned array or object, string Yes
params.valueVar The variable to assign the iterator’s next value. $val string No
params.keyVar The variable to assign the next object key or array index. $key string No
params.indexVar The variable to assign the next array index or “loop counter”. $index string No
then The list of actions to run on each element. Action[] Yes

Example Response

{
  "actions": [
    {
      "$myPetsArray": "['Whiskers', 'Spot', 'Bubbles']"
    },
    {
      "type": "FOREACH",
      "params": {
        "iterator": "$myPetsArray"
      },
      "then": [
        {
          "type": "SAY",
          "params": {
            "text": "The index ${index} has a value of ${val}."
          }
        }
      ]
    },
    {
      "$myPetsObj": "{cat: 'Whiskers', dog: 'Spot', fish: 'Bubbles'}"
    },
    {
      "type": "FOREACH",
      "params": {
        "iterator": "$myPetsObj",
        "valueVar": "$v",
        "keyVar": "$k"
      },
      "then": [
        {
          "type": "SAY",
          "params": {
            "text": "The key ${k} has a value of ${v}."
          }
        }
      ]
    },
    {
      "$phoneNos": "['+17145551212', '+13105551212', '+19495551212']"
    },
    {
      "type": "FOREACH",
      "params": {
        "iterator": "$phoneNos"
      },
      "then": [
        {
          "type": "DIAL",
          "params": {
            "no": "${val}"
          }
        }
      ]
    }
  ]
}

GOTO

Jump to a LABEL.

The GOTO action jumps the call flow to the specified LABEL. Warning: The call flow will fail if the specified LABEL does not exist within the same callback response.

Request

View standard request details HERE

Response

Parameter Description Default Type Required
label Accepts: alphanumeric characters, dashes, and underscores. string* Yes

Example Response

{
  "actions": [
    {
      "type": "GOTO",
      "params": {
        "label": "goto_here"
      }
    }
  ]
}

HANGUP

Ends the call.

This action immediately ends the call and stops all action flow execution.

Request

View standard request details HERE

Response

See Example Body

Example Response

{
  "actions": [
    {
      "type": "HANGUP"
    }
  ]
}

IF

Basic if-then-else conditional.

The variables within the scope of the condition are basically the callback Native Constants and User Defined Variables prefixed with a $ symbol (yeah, like PHP). The condition is evaluated as JavaScript, with all of its truthy goodness. All actions are supported in the then parameter.

Response

Parameter Description Default Type Required
condition The JS statement to evaluate for truthfulness. string Yes
then The list of actions to execute if the condition is TRUE. array Yes
orElse Optionally, the list of actions to execute if the condition is FALSE. array No

Example Response

{
  "actions": [
    {
      "type": "IF",
      "condition": "$keyPresses == '1' && $sessionData.gender == 'male' || $sessionData.age > 21",
      "then": [
        {
          "type": "SAY",
          "params": {
            "text": "You pressed 1, dude. Or you are over 21."
          }
        }
      ],
      "orElse": [
        {
          "type": "SAY",
          "params": {
            "text": "You did not press 1 and are not a male or are not over 21."
          }
        }
      ]
    }
  ]
}

LABEL

Target of GOTO.

The LABEL action sets the entry point for a GOTO action. Invoking a GOTO on a label will immediately jump the call flow to the LABEL.

Request

View standard request details HERE

Response

Parameter Description Default Type Required
name The name of the LABEL used by a GOTO action. Accepts: alphanumeric, dashes and underscores. string Yes

Example Response

{
  "actions": [
    {
      "type": "LABEL",
      "name": "goto_here"
    }
  ]
}

PAUSE

Pauses the call.

Pauses the call for the specified number of seconds, then resumes with the next Action.

Request

View standard request details HERE

Response

Parameter Description Default Type Required
seconds The number of seconds to pause. 5 integer No

Example Response

{
  "actions": [
    {
      "type": "PAUSE",
      "params": {
        "seconds": 10
      }
    }
  ]
}

PLAY

Plays an audio file or DTMF.

Audio files supported are MP3, WAV, and M4A. WAV will often perform better.

DTMF will play an out-of-band tone.

Request

View standard request details HERE

Response

Parameter Description Default Type Required
url The url of the audio file. string* Yes*
stop_on_key Determines whether a key press stops the playback. false boolean No
dtmf The DTMF tones to play. Accepts: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, #, *. Use a dash - to extend the delay between DTMF tones. Example: 12-3--4---5. string* Yes*
dtmf_delay The delay between DTMF tones in milliseconds (for DTMF only). 250 integer No
dtmf_dash_delay The delay represented by each dash - in milliseconds (for DTMF only). 250 integer No
repeat How many times to repeat the audio or DTMF. 1 integer No

Example Response // Audio

{
  "type": "PLAY",
  "params": {
    "url": "https://s3.amazonaws.com/com.voxology.music/classical/BusyStrings.mp3",
    "repeat": 1
  }
}

Example Response // DTMF

{
  "type": "PLAY",
  "params": {
    "dtmf": "1 2 3 - 4 -- 5 --- 6"
  }
}

QUEUE

Controls Call Queues.

Place or remove callers from a specific queue and handle queue events.

Request

View standard request details HERE

Response

Parameter Description Default Type Required
name A unique name to identify the queue. Using the same name will put callers into the same queue. Accepts: alpha-numeric, underscores, and dashes. string* Yes
event Accepts: offer, poll, poll_connect, remove.

offer puts this call into a queue.
poll releases the next queued call from a queue (and has a limited use case as an Action).
poll_connect takes the next call from the queue and bridges it to this call.
remove takes this call (regardless of position) from the queue.		 offer string No
async If true, this action will not block and the call flow will continue executing actions and/or callbacks. Be careful as async may cause hard to reason behaviors. Only offer can be asynchronous. false boolean No
max_calls At the moment of offering, if the number of queued calls exceeds this amount, the offer will error. Calls that attempt to exceed the limit can be handled with an error handler. infinity* integer No

Example Response // Simple

{
  "actions": [
    {
      "type": "QUEUE",
      "params": {
        "name": "high-priority"
      }
    }
  ]
}

Note: When a call is polled/removed from a blocking queue, it continues down the call flow. If using poll_connect, you will likely want to block when the polled call exits the queue. Use a PAUSE or COLLECT action.

Queues can trigger events when a offer attempt succeeds or fails. Attempts can fail, for example, if the max calls limit is reached. Event handlers are a list of actions that execute when specified events are triggered.

Queue Events

Event Description
on_enter This handler will run when an offer is accepted.
on_enter_error_max_calls This handler will run when a queue is at its max_calls limit.
on_enter_error This handler will always run on any error condition, including a poll_connect failure.

Example Response // Advance

{
  "actions": [
    {
      "type": "QUEUE",
      "params": {
        "name": "low-priority",
        "event": "offer",
        "max_calls": 10
      },
      "events": {
        "on_enter": [
          {
            "type": "SAY",
            "params": {
              "text": "You are now entering the queue."
            }
          }
        ],
        "on_enter_error_max_calls": [
          {
            "type": "SAY",
            "params": {
              "text": "I'm sorry. The queue is full."
            }
          }
        ]
      }
    }
  ]
}

RECORD

Control call recording.

This action allows the developer to start, stop, pause and resume recordings. It will initiate the call recording type. Saved recordings will be available via the REST API.

Request

View standard request details HERE

Response

Parameter Description Default Type Required
action The recording action to perform. Accepts: start, stop, pause, resume. start string No
tracks[] The tracks to record. Accepts: caller (far end), transfer (near end) caller array No
group A name that is queryable in the recordings lookup resource. api_no string No

Example Response

{
  "actions": [
    {
      "type": "RECORD",
      "params": {
        "group": "support_technical",
        "action": "start",
        "tracks": ["caller"]
      }
    }
  ]
}

RECORDMESSAGE

This action allows the developer to implement a voicemail-type system, where a caller can leave a message, play it back, and decide to save or discard the message. It will initiate the voicemail recording type. Saved recordings will be available via the REST API.

Note: These recordings will be saved by 1) a RECORDMESSAGE with save, or 2) by ending the call before a RECORDMESSAGE with discard.

Request

View standard request details HERE

Response

Parameter Description Default Type Required
action The recording action to perform. Accepts: start, play, discard, save. start string No
finish_on_key The key to press to end the recording. Accepts: any, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, #, *. any string No
group A name that is queryable in the recordings lookup resource. api_no string No
max_recording_time The maximum length of a recording in seconds. Valid: 1 to 3600. 30 integer No
timeout The maximum amount of silence before a recording is stopped in seconds. Valid: 1 to 60. 5 integer No
notify_on_save An object containing optional information regarding sending notifications when a voicemail is saved. object No
notify_on_save.email An object containing optional notification information regarding email. object No
notify_on_save.email.from The email address to send from (hidden from users). no-reply@voxolo.gy string No
notify_on_save.email.to The email address to send the voicemail recording notification to. string No
notify_on_save.email.cc CC email addresses to include on the voicemail recording email notifications. string No
notify_on_save.email.bc BCC email addresses to include on the voicemail recording email notifications. string No
notify_on_save.email.subject The subject of the email notification. New Voicemail From: [caller_no_formatted] string No
notify_on_save.email.message The message in the body of the email notification. You have a new voicemail message. From: [caller_no_formatted] To: [api_no_formatted] Date: [Weekday], [Month] [Day], [Year] at [Time 00:00:00 AM/PM] Length: [duration in 00:00] [voicemail recording attachment] string No

Example Response

{
  "actions": [
    {
      "type": "RECORDMESSAGE",
      "params": {
        "group": "support_technical",
        "action": "start",
        "notify_on_save": {
          "email": {
            "to": "voice@mail.com"
          }
        }
      }
    }
  ]
}

RecordMessage Events

Event Description
on_save This handler will run when successfully saving a recording with action:"save". Useful for firing off WEBHOOKs.
on_error This handler will run if any action fails.

REDIRECT

Changes the callback URL, etc.

The REDIRECT action changes the url, method, headers and/or content_type of all subsequent callbacks.

Request

View standard request details HERE

Response

Parameter Description Default Type Required
url The new url to send all subsequent callbacks to. This parameter supports relative URLs. The benefit of relative URLs is that actions with REDIRECTs may be assigned to many domains or subdirectories without changing any code. string* Yes
method The new method to send all subsequent callbacks as. Accepts: POST, PUT, GET. Inherited string* No
headers The new headers to send with all subsequent callbacks. Accepts an associative array of header names and values. Inherited object No
content_type The format of the payload posted to the endpoint. Accepts: application/json, application/xml, application/x-www-form-urlencoded. Inherited string* No

Example Response

{
  "actions": [
    {
      "type": "REDIRECT",
      "params": {
        "url": "https://your-domain.com/path/to/here",
        "method": "GET"
      }
    }
  ]
}

Example Response // Relative URL


"https://domain.com/path/to/actions/file.json"

{
  "actions": [
    {
      "type": "REDIRECT",
      "params": {
        "url": "other_file.json"
      }
    }
  ]
}

"Resolves to https://domain.com/path/to/actions/other_file.json"

Example Response // Relative URL


"https://domain.com/path/to/actions/file.json"

{
  "actions": [
    {
      "type": "REDIRECT",
      "params": {
        "url": "../../other_file.json"
      }
    }
  ]
}

"Resolves to https://domain.com/path/other_file.json"

REDIRECTEXTENSION

Changes the callback configuration to that of a specified extension. If the given extension does not have an assigned callback configuration, it defaults to the Default Extension Configuration. LIkewise, if a Default Extension Configuration doesn’t exit, it will use the standard Default Configuration on the application/subaccount.

The REDIRECTEXTENSION action changes the url, method, headers and/or content_type of all subsequent callbacks for the current call. When the call ends, the callback configuration reverts to that asssigned to the phone number or the default for application/subaccount as applicable.

Request

View standard request details HERE

Response

Parameter Description Default Type Required
extension An existing Extension whose callback configuration you’d like to redirect subsequent callbacks to. string* Yes

Example Response

{
  "actions": [
    {
      "type": "REDIRECTEXTENSION",
      "params": {
        "extension": "1234"
      },
      "on_error": [
        {
            "type": "SAY",
            "params": {
                "text": "It appears the extension you dialed does not exist, please try again."
            }
        }
      ]
    }
  ]
}

Events

Event Description
on_error If this REDIRECTEXTENSION action fails for any reason, such as a non-existent extension, this event will fire and execute any actions therein.

REJECT

Does not answer the call.

This action refuses to answer the call. Depending on the reason given, a busy-signal or not-in-service message will be played. If REJECT is the first action in the callflow, any inbound call will be rejected with a connect time of 0.

Request

View standard request details HERE

Response

Parameter Description Default Type Required
reason Accepts: busy and disconnected. busy string No

Example Response

{
  "actions": [
    {
      "type": "REJECT",
      "params": {
        "reason": "busy"
      }
    }
  ]
}

SAY

Convert text to speech (TTS).

The SAY action converts text to speech that is read to the caller.

Request

View standard request details HERE

Response

Parameter Description Default Type Required
text The text to convert. string* Yes
stop_on_key Determines whether a key press stops the playback. false boolean No
repeat The number of times to play the speech. 1 integer No
voice Accepts: Kate and Kevin (Voxology native voices), Watson (requires an IBM Watson Account) Kate string No
language Accepts: english (Kate and Kevin) AND englishUS, englishGB, french, german, italian, japanese, portuguese, spanish (IBM Watson) english string No
gender Accepts: female, male female string No

Example Response

{
  "actions": [
    {
      "type": "SAY",
      "params": {
        "text": "Hello, world.",
        "repeat": 2,
        "voice": "Kate",
        "language": "english",
        "gender": "female"
      }
    }
  ]
}

SESSIONDATA

Sets a call’s session data.

Sets a call’s session_data property.

To learn more about session data, click here.

Request

View standard request details HERE

Response

Name Description Type
session_data The session data value can be any valid JSON object. object

Example Response

{
  "actions": [
    {
      "type": "SESSIONDATA",
      "session_data": {
        "name": "Bob",
        "age": 21
      }
    }
  ]
}

SMS

Sends an SMS message.

This action sends an SMS message.

Response

Parameter Description Default Type Required
message The text message to send. string* Yes
no The phone number to send the message to. Defaults to caller’s number. caller_no string* No
caller_id_no The phone number the message is sent from. Defaults to the current inbound number. api_no string* No
group_nos A list of destination numbers where the message will be sent. Use this parameter in place of no to send a Group MMS message to multiple recipients. array No
media_urls An array of URLs pointing to the media to include in an MMS message. The URLs must be publically accessible or the message will not send. array No
external_id A queryable name for the messages. string No
external_group_id A queryable name for a group of messages. string No
status_webhook An object containing information on the status webhook. object No
status_webhook.url The endpoint to which the status webhooks will be sent. Click here to see status webhooks. string No

Example Response

{
  "actions": [
    {
      "type": "SMS",
      "params": {
        "no": "+19495551111",
        "caller_id_no": "+17145552222",
        "message": "Hello, world!",
        "media_urls":[
         "https://yourPublicMediaURL.com"
        ],
        "external_id": "external ID",
        "external_group_id": "group ID",
        "status_webhook": {
          "url": "yourWebhookURL.com"
        }
      }
    }
  ]
}

STOP

Stops Running Actions.

This action stops other actions that are currently running on a call, like playing audio.

Request

View standard request details HERE

Response

Parameter Description Default Type Required
actions A comma-separated list of actions. Accepts: AUDIO. AUDIO string No

Example Response

{
  "actions": [
    {
      "type": "STOP",
      "params": {
        "actions": "AUDIO"
      }
    }
  ]
}

STREAM

Initiate a Media Stream during a live phone call.

This action allows the developer to start, stop, pause and resume media stream. Once the STREAM is initiated, audio will be streamed to the designated uri via a series of WebSocket Messages. Click here to see WebSocket Message details.

Request

View standard request details HERE

Response

Parameter Description Default Type Required
action The stream action to perform. Accepts: start, stop, pause, resume. start string No
tracks[] The tracks to stream. Accepts: caller (far end), transfer (near end). [“caller”] array No
url The url where the WebSocket connection will be initiated and audio will start streaming. string Yes
media_type Accepts: base_64. base_64 string No
stream_data The object containing data to be returned with the stream. {} object or string No

Example Response

{
  "actions": [
    {
      "name": "your_stream_name",
      "type": "STREAM",
      "params": {
        "url": "ws://yourwebsocketservice.com",
        "action": "start",
        "tracks": [
          "caller"
        ],
        "stream_data": {
          "name": "Bob",
          "age": 21
        }
      }
    },
    {
      "type": "PAUSE",
      "params": {
        "seconds": 10
      }
    },
    {
      "type": "STREAM",
      "params": {
        "action": "stop",
        "tracks": [
          "caller"
        ]
      }
    },
    {
      "type": "HANGUP"
    }
  ]
}

TRANSCRIBE

Use Speech-To-Text to Transcribe a live phone call.

This action allows the developer to start and stop call transcription. By default, the complete transcript of the call will be delivered to the url defined in the api_no callback configuration. Developers must provide both the end_transcript_webhook and the end_transcript_webhook_failover urls to override this default setting. If a live_transcript_webhook url is provided, each transcribed utterance is returned live. Click here to see transcript webhhook details.

The webhook URL can be either an HTTP endpoint or, if your application is setup with an AWS integration, an AWS Simple Notification Service ARN.

Note: To use the TRANSCRIBE action add your Google Speech-to-Text credentials in the Voxology Portal.

Request

View standard request details HERE

Response

Parameter Description Default Type Required
action The transcribe action to perform. Accepts: start, stop, pause, resume. start string No
language Language being used on the call in BCP 47 format. Accepts en-US, fr-FR, de-DE, es-ES. en-US string No
hints A list of possible keywords expected on the call to assist in accurate transcription. [] array No
tracks The tracks, or legs, of the call to transcribe. Accepts caller (far end) transfer (B-leg of a call-transfer). [“caller”] array No
live_transcript_webhook Defines where and how live_transcript webhooks are sent. If not set, no live_transcript webhooks will be sent. {} object No
live_transcript_webhook.url The endpoint where live_transcript webhooks are sent. string No
live_transcript_webhook.method The request method. Accepts GET and POST. POST string No
live_transcript_webhook.content_type The format of the payload posted to the endpoint. Accepts: application/json, application/xml, application/x-www-form-urlencoded. application/json string No
end_transcript_webhook Defines where and how end_transcript webhooks are sent. {} object No
end_transcript_webhook.url The endpoint where end_transcript webhooks are sent. string No
end_transcript_webhook.method The request method. Accepts GET and POST. POST string No
end_transcript_webhook.content_type The format of the payload posted to the endpoint. Accepts: application/json, application/xml, application/x-www-form-urlencoded. application/json string No
end_transcript_webhook_failover Defines where to send end_transcript webhooks if first request to end_transcript_webhook.url fails. {} object No
end_transcript_webhook_failover.url The endpoint where end_transcript webhooks are sent if the first request fails. string No
end_transcript_webhook_failover.method The request method. Accepts GET and POST. POST string No
end_transcript_webhook_failover.content_type The format of the payload posted to the endpoint. Accepts: application/json, application/xml, application/x-www-form-urlencoded. application/json string No

Example Response

{
  "actions": [
    {
      "name": "transcript_name",
      "type": "TRANSCRIBE",
      "params": {
        "action": "start",
        "language": "en-US",
        "hints": ["expected", "keywords"],
        "tracks": ["caller"],
        "live_transcript_webhook": {
          "url": "https://your-live-transcript-endpoint.com",
          "method": "POST",
          "content_type": "application/json"
        },
        "end_transcript_webhook": {
          "url": "https://your-end-transcript-endpoint.com",
          "method": "POST",
          "content_type": "application/json"
        },
        "end_transcript_webhook_failover": {
          "url": "https://your-end-transcript-failover.com",
          "method": "POST",
          "content_type": "application/json"
        }
      }
    }
  ]
}

TRANSFER

Transfers the call.

This action transfers the caller from the current api_no to another phone number or SIP endpoint.

Request

View standard request details HERE

Response

Parameter Description Default Type Required
no The phone number or SIP destination to call. Phone numbers are in E.164 format (example: +19495551212). SIP destinations are formatted as abc123@sip.mypbx.com. string* Yes
caller_id_no The phone number that will appear as the Caller ID. Phone numbers are in E.164 format (example: +19495551212). Defaults to the number of the caller that dialed your inbound number (caller_id_noin your callbacks) caller_no string* No
event Accepts start or stop. The start event will connect two calls. The stop event will disconnect the transfer, hanging up on the other call. start string No
user_sip_headers The key/value pair(s) in this object will be flattened and converted to User-to-User and X-... SIP headers to be included when transferring to a SIP address. This allows you to pass along custom data on transfer. The key(s) must be: User-to-User OR must start with an X-. string No
async If true, this action will not block and the call flow will continue executing actions and/or callbacks. Be careful as async may cause hard to reason behaviors. false boolean No
max_call_time The maximum length of the call in seconds. Valid: 60 to 172800. 86400 integer No
timeout The maximum time to wait during ringing in seconds. Valid: 20 to 240. 50 integer No

Example Response // Phone Number

{
  "actions": [
    {
      "type": "TRANSFER",
      "params": {
        "no": "+19495551111",
        "caller_id_no": "+17145552222"
      }
    }
  ]
}

Example Response // SIP Address

{
  "actions": [
    {
      "type": "TRANSFER",
      "params": {
        "no": "abc123@sip.mypbx.com",
        "caller_id_no": "+17145552222",
        "user_sip_headers": {
          "User-to-User": "hi",
          "x-name": "${sessionData.name}",
          "x-call-id": "${callId}",
          "x-string": "hello world"
        }
      }
    }
  ]
}

Example Response // Async Transfer

{
  "actions": [
    {
      "type": "TRANSFER",
      "params": {
        "no": "+17145551212",
        "async": true
      }
    },
    {
      "type": "COLLECT",
      "params": {
        "num_digits": 1,
        "timeout": 3600000
      },
      "actions": [
        {
          "type": "SAY",
          "params": {
            "text": "Press any key to end the call."
          }
        }
      ]
    },
    {
      "type": "TRANSFER",
      "params": {
        "event": "stop"
      }
    }
  ]
}

WEBHOOK

HTTP Request.

This action allows HTTP requests from anywhere in the call flow. For example, add WEBHOOK to CONFERENCE or QUEUE event handlers to alert your service when a call enters a conference or queue.

You can use WEBHOOK to alert your service when a call exits a conference or queue by placing a WEBHOOK immediately after blocking CONFERENCE or QUEUE actions.

The default value “Inherited” means that the value will equal that of the last Call Flow Callback Request. The request timeout is 30 seconds.

Request

View standard request details HERE

Response

Parameter Description Default Type Required
event_name The name of the webhook event. This can be anything you like. Examples: onEnterConference, onLeaveQueue, onEnterQueueError. string Yes
webhook_data The object containing data to be returned in the webhook request. {} object or string* No
url The endpoint the webhook will call. Inherited string No
method The method of the request. Accepts: GET, POST, PUT. Inherited string No
content_type The format of the payload posted to the endpoint. Accepts: application/json, application/xml, application/x-www-form-urlencoded. Inherited string No
headers The headers to include in the request. Inherited key/value No
await_response If true, this action will block the call flow until either a response from the endpoint is received, or the timeout value is reached. await_response is enabled if an on_error event is set. false boolean No
timeout In seconds, the time for the webhook request to wait for a response before timing out. This value is only used if await_response is enabled. Once the timeout is reached, the on_error event is triggered. Allowed range: 1-30 30 integer No
await_response_hold_audio Accepts a URL of hosted audio. Only valid on blocking Webhooks (when await_response is set to true) Inherited string No

Example Response // Simple

{
  "actions": [
    {
      "type": "WEBHOOK",
      "params": {
        "event_name": "onEnterConference"
      }
    }
  ]
}

Example Response // Advanced // Object

{
  "actions": [
    {
      "type": "WEBHOOK",
      "params": {
        "event_name": "onEnterConference",
        "webhook_data": {
          "conferenceName": "my-conf"
        },
        "url": "https://mydomain.com/app/webhook",
        "method": "POST",
        "content_type": "application/json"
      },
      "events": {
        "on_error": [
          {
            "type": "SAY",
            "params": {
              "text": "A webhook error occurred."
            }
          },
          {
            "$webhookData": "{ foo: 'I got no foo' }"
          }
        ]
      }
    }
  ]
}

Events

Event Description
on_error This handler will run when a WEBHOOK response status is non-2xx. Forces the WEBHOOK to be non-asynchronous (blocking).

Example Response // Simple // String

{
  "actions": [
    {
      "type": "WEBHOOK",
      "params": {
        "event_name": "onEnterConference",
        "webhook_data": "$dataMap.webhookData"
      }
    }
  ]
}

Example Response // Advanced // String

{
  "actions": [
    {
      "type": "WEBHOOK",
      "params": {
        "event_name": "onEnterConference",
        "webhook_data": "$dataMap.webhookData",
        "url": "https://mydomain.com/app/webhook",
        "method": "POST",
        "content_type": "application/json"
      }
    }
  ]
}

Methods

Account

View Account Detail

Returns account owner’s information.

GET /Account

Authentication Type

Basic Authentication (Account-level)

Request

No Request Body

Example Request

curl -X GET \
  https://api.voxolo.gy/v1/Account \
  -H 'Authorization: Basic a1b2c3d4e5f6g7h8i9j0klnmopqrstuvwxyz' \
  -H 'Cache-Control: no-cache'

Response

Property Description Type
id Account ID string
email Account Owner’s Email string
firstname Account Owner’s First Name string
lastname Account Owner’s Last Name string
username Account Owner’s Username (will be email) string
status Returns: active or inactive string
max_apps The maximum number of Apps an account can create (includes deleted Apps) integer
max_subaccounts The maximum number of Sub Accounts per App (includes deleted Sub Accounts) integer
port_out_pin PIN number used when creating a port out request. The port out PIN on the Sub Account and Phone Number will be used over the Application’s Port out PIN, respectively. string

Example Response

{
  "id": "8c86b1f5-abcd-1234-efgh-h249d0e298",
  "email": "john.doe@company.com",
  "firstname": "John",
  "lastname": "Doe",
  "username": "john.doe@company.com",
  "status": "active",
  "max_apps": 15,
  "max_subaccounts_per_app": 20,
  "port_out_pin": "1234"
}

Response Codes

Status Description
200 Success returns account details
4xx & 5xx General Error Codes

Create Alert

Creates an email alert specifically for your account based upon balance thresholds. Used to warn recipient when specified account balance is getting low.

POST /Account/Alerts

Authentication Type

Basic Authentication (Account-level)

Request

Parameter Description Type Required
firstname The first name of the alert recipient. string (body) Yes
lastname The last name of the alert recipient. string (body) Yes
email The email address to send the alert to. string (body) Yes
phone_no The phone number of the alert recipient. As of now, not used. string (body) No
account_balance The configuration for the alerts. The properties minutes_before_zero and/or thresholds are required. object (body) Yes
account_balance.minutes_before_zero Trigger an alert the specified number of minutes before the account balance is estimated to hit $00.00. integer (body) No
account_balance.thresholds One to three dollar amounts of the account balance that will trigger an alert, separated by commas. array (body) No

Example Request

curl -X POST \
  https://api.voxolo.gy/v1/Account/Alerts \
  -H 'Authorization: Basic a1b2c3d4e5f6g7h8i9j0klnmopqrstuvwxyz' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
    "firstname": "John",
    "lastname": "Doe",
    "email": "john.doe@company.com",
    "phone_no": "714-555-1212",
    "account_balance": {
      "minutes_before_zero": 30,
      "thresholds": [10, 100, 1000]
    }
  }'

Response

No Response Body

Response Codes

Status Description
201 Success creates new alert
4xx & 5xx General Error Codes

List Alerts

Returns all alerts created for a specific account.

GET  /Account/Alerts

Authentication Type

Basic Authentication (Account-level)

Request

No Request Body

Example Request

curl -X GET \
  https://api.voxolo.gy/v1/Account/Alerts \
  -H 'Authorization: Basic a1b2c3d4e5f6g7h8i9j0klnmopqrstuvwxyz' \
  -H 'Cache-Control: no-cache'

Response

Property Description Type
alerts An array of Alerts array
alerts[i].id Alert ID string
alerts[i].firstname First Name of alert recipient string
alerts[i].lastname Last Name of alert recipient string
alerts[i].email Email of alert recipient (where alert will be sent) string
alerts[i].phone_no Phone number of alert recipient string
alerts[i].account_balance object
alerts[i].account_balance.minutes_before_zero Send an alert this many minutes before the account balance is estimated to reach zero. integer
alerts[i].account_balance.thresholds Send an alert when each of these thresholds are crossed. array

Example Response

{
  "alerts": [
    {
      "id": 8411,
      "firstname": "John",
      "lastname": "Doe",
      "email": "john.doe@company.com",
      "phone_no": "(949) 555-1212",
      "account_balance": {
        "minutes_before_zero": 30,
        "thresholds": [10, 100, 1000]
      }
    }
  ]
}

Response Codes

Status Description
200 Success returns an array of alerts.
4xx & 5xx General Error Codes

Delete Alert

Deletes an alert by ID. The ID is the only required parameter.

DELETE /Account/Alerts/{id}

Authentication Type

Basic Authentication (Account-level)

Request

Parameter Description Type Required
id ID of the alert. string (path) Yes

Example Request

curl -X DELETE \
  https://api.voxolo.gy/v1/Account/Alerts/alert-id \
  -H 'Authorization: Basic a1b2c3d4e5f6g7h8i9j0klnmopqrstuvwxyz' \
  -H 'Cache-Control: no-cache'

Response

No Response Body

Response Codes

Status Description
204 No content on success.
4xx & 5xx General Error Codes

Create End User Profile

Creates an End User Profile that will store the information of the end user associated with the account.

POST /Account/EndUserProfiles

Authentication Type

Basic Authentication (Account-level)

Request

Parameter Description Type Required
entity_name The legal name of the company or rganization. string (body) Yes
doing_business_as The DBA or brand name. string (body) No
tax_id Tax ID or EIN. string (body) No
tax_id_issuing_country The country code of tax ID or EIN issuing country. string (body) No
alternative_business_id_type The company’s alternative business type (DUNS, GIIN, LEI). string (body) No
alternative_business_id The alternative business ID number. string (body) No
address The company’s street name and number. string (body) No
city City. string (body) No
region State or region. string (body) No
country Country (ISO Alpha-2). string (body) Yes
website The website of the organization. string (body) No
stock_symbol If publicly traded company, the stock symbol. string (body) No
stock_exchange If publicly traded company, the stock exchange. string (body) No
naics The organization’s NAICS code. string (body) No
isicv4 If an international company, the ISIC code. string (body) No
description A description of the organization. string (body) No
isicv4 If an international company, the ISIC code. string (body) No

Example Request

curl -X POST \
  https://api.voxolo.gy/v1/Account/EndUserProfiles \
  -H 'Authorization: Basic a1b2c3d4e5f6g7h8i9j0klnmopqrstuvwxyz' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
        "entity_name": "My Company Name LLC",
        "doing_business_as": "Janes Company",
        "tax_id": "123-45-6789",
        "tax_id_issuing_country": "US",
        "alternative_business_id_type": "LEI",
        "alternative_business_id": "1234005ABC6DEF78GH91",
        "address": "4695 MacArthur Ct",
        "city": "Newport Beach",
        "region": "CA",
        "postal_code": "92660",
        "country": "US",
        "website": "www.JanesCo.org",
        "stock_symbol": "NOES",
        "stock_exchange": "NYSE",
        "naics": "62",
        "isicv4": "456",
        "description": "real estate agency"
    }
  }'

Response

Parameter Description Type
end_user_profile_id The ID of the created end user profile. string (body)
entity_name The legal name of the company or rganization. string (body)
doing_business_as The DBA or brand name. string (body)
tax_id Tax ID or EIN. string (body)
tax_id_issuing_country The country code of tax ID or EIN issuing country. string (body)
alternative_business_id_type The company’s alternative business type (DUNS, GIIN, LEI). string (body)
alternative_business_id The alternative business ID number. string (body)
address The company’s street name and number. string (body)
city City. string (body)
region State or region. string (body)
country Country (ISO Alpha-2). string (body)
website The website of the organization. string (body)
stock_symbol If publicly traded company, the stock symbol. string (body)
stock_exchange If publicly traded company, the stock exchange. string (body)
naics The organization’s NAICS code. string (body)
isicv4 If an international company, the ISIC code. string (body)
description A description of the organization. string (body)
isicv4 If an international company, the ISIC code. string (body)

Example Response

{
  "end_user_profile_id": "a1b23456-c7d8-9e10-1234-56f7a8b9101c",
  "entity_name": "My Company Name LLC",
  "doing_business_as": "Janes Company",
  "tax_id": "123-45-6789",
  "tax_id_issuing_country": "US",
  "alternative_business_id_type": "LEI",
  "alternative_business_id": "1234005ABC6DEF78GH91",
  "address": "4695 MacArthur Ct",
  "city": "Newport Beach",
  "region": "CA",
  "postal_code": "92660",
  "country": "US",
  "website": "www.JanesCo.org",
  "stock_symbol": "NOES",
  "stock_exchange": "NYSE",
  "naics": "62",
  "isicv4": "456",
  "description": "real estate agency"
}

Response Codes

Status Description
200 A successful response returns the end user profile object
4xx & 5xx General Error Codes

List End User Profiles

Returns all end user profiles created for a specific account.

GET  /Account/EndUserProfiles

Authentication Type

Basic Authentication (Account-level)

Request

No Request Body

Example Request

curl -X GET \
  https://api.voxolo.gy/v1/Account/EndUserProfiles \
  -H 'Authorization: Basic a1b2c3d4e5f6g7h8i9j0klnmopqrstuvwxyz' \
  -H 'Cache-Control: no-cache'

Response

Property Description Type
end_user_profiles An array of End User Profiles. array
end_user_profiles[i].end_user_profile_id End User Profile ID. string
end_user_profiles[i].entity_name Name of the the organization. string
end_user_profiles[i].description A description of the company. string

Example Response

{
  "end_user_profiles": [
    {
      "end_user_profile_id": "a0b93005-c9a3-4d96-8247-92f3f6b3592d",
      "entity_name": "My Company Name LLC",
      "description": "real estate agency"
    }
  ]
}

Response Codes

Status Description
200 Success returns an array of end user profiles.
4xx & 5xx General Error Codes

View End User Profile Detail

Returns the End User Profile detail for any individual profile based upon the End User profile ID.

GET /Account/EndUserProfiles/{id}

Authentication Type

Basic Authentication (Account-level)

Request

Parameter Description Type Required
id ID of the end user profile. integer (path) Yes

Example Request

curl -X GET \
  https://api.voxolo.gy/v1/Account/EndUserProfiles/a1b23456-c7d8-9e10-1234-56f7a8b9101c \
  -H 'Authorization: Basic a1b2c3d4e5f6g7h8i9j0klnmopqrstuvwxyz' \
  -H 'Cache-Control: no-cache'

Response

Parameter Description Type
end_user_profile_id The ID of the created end user profile. string (body)
entity_name The legal name of the company or rganization. string (body)
doing_business_as The DBA or brand name. string (body)
tax_id Tax ID or EIN. string (body)
tax_id_issuing_country The country code of tax ID or EIN issuing country. string (body)
alternative_business_id_type The company’s alternative business type (DUNS, GIIN, LEI). string (body)
alternative_business_id The alternative business ID number. string (body)
address The company’s street name and number. string (body)
city City. string (body)
region State or region. string (body)
country Country (ISO Alpha-2). string (body)
website The website of the organization. string (body)
stock_symbol If publicly traded company, the stock symbol. string (body)
stock_exchange If publicly traded company, the stock exchange. string (body)
naics The organization’s NAICS code. string (body)
isicv4 If an international company, the ISIC code. string (body)
description A description of the organization. string (body)
isicv4 If an international company, the ISIC code. string (body)

Example Response

{
  "end_user_profile_id": "a1b23456-c7d8-9e10-1234-56f7a8b9101c",
  "entity_name": "My Company Name LLC",
  "doing_business_as": "Janes Company",
  "tax_id": "123-45-6789",
  "tax_id_issuing_country": "US",
  "alternative_business_id_type": "LEI",
  "alternative_business_id": "1234005ABC6DEF78GH91",
  "address": "4695 MacArthur Ct",
  "city": "Newport Beach",
  "region": "CA",
  "postal_code": "92660",
  "country": "US",
  "website": "www.JanesCo.org",
  "stock_symbol": "NOES",
  "stock_exchange": "NYSE",
  "naics": "62",
  "isicv4": "456",
  "description": "real estate agency"
}

Response Codes

Status Description
200 A successful response returns the end user profile object
4xx & 5xx General Error Codes

Update End User Profile

Updates existing end user profile information.

PUT /Account/EndUserProfiles/{id}

Request

Parameter Description Type Required
end_user_profile_id ID of the end user profile. string (path) Yes
entity_name The legal name of the company or rganization. string (body) No
doing_business_as The DBA or brand name. string (body) No
tax_id Tax ID or EIN. string (body) No
tax_id_issuing_country The country code of tax ID or EIN issuing country. string (body) No
alternative_business_id_type The company’s alternative business type (DUNS, GIIN, LEI). string (body) No
alternative_business_id The alternative business ID number. string (body) No
address The company’s street name and number. string (body) No
city City. string (body) No
region State or region. string (body) No
country Country (ISO Alpha-2). string (body) No
website The website of the organization. string (body) No
stock_symbol If publicly traded company, the stock symbol. string (body) No
stock_exchange If publicly traded company, the stock exchange. string (body) No
naics The organization’s NAICS code. string (body) No
isicv4 If an international company, the ISIC code. string (body) No
description A description of the organization. string (body) No
isicv4 If an international company, the ISIC code. string (body) No

Example Request

curl -X PUT \
  https://api.voxolo.gy/v1/Account/EndUserProfiles/a1b23456-c7d8-9e10-1234-56f7a8b9101c \
  -H 'Authorization: Basic a1b2c3d4e5f6g7h8i9j0klnmopqrstuvwxyz' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
        "end_user_profile_id": "a1b23456-c7d8-9e10-1234-56f7a8b9101c",
        "entity_name": "My Company Name LLC",
        "doing_business_as": "Janes Realty",
        "tax_id": "123-45-6789",
        "tax_id_issuing_country": "US",
        "alternative_business_id_type": "LEI",
        "alternative_business_id": "1234005ABC6DEF78GH91",
        "address": "4695 MacArthur Ct",
        "city": "Newport Beach",
        "region": "CA",
        "postal_code": "92660",
        "country": "US",
        "website": "www.JanesCo.org",
        "stock_symbol": "NOES",
        "stock_exchange": "NYSE",
        "naics": "62",
        "isicv4": "456",
        "description": "real estate agency"
      }
  }'

Example Response

{
  "end_user_profile_id": "a1b23456-c7d8-9e10-1234-56f7a8b9101c",
  "entity_name": "My Company Name LLC",
  "doing_business_as": "Janes Realty",
  "tax_id": "123-45-6789",
  "tax_id_issuing_country": "US",
  "alternative_business_id_type": "LEI",
  "alternative_business_id": "1234005ABC6DEF78GH91",
  "address": "4695 MacArthur Ct",
  "city": "Newport Beach",
  "region": "CA",
  "postal_code": "92660",
  "country": "US",
  "website": "www.JanesCo.org",
  "stock_symbol": "NOES",
  "stock_exchange": "NYSE",
  "naics": "62",
  "isicv4": "456",
  "description": "real estate agency"
}

Response Codes

Status Description
200 The details of the updated end user profile
4xx & 5xx General Error Codes

Delete End User Profile

Deletes an end user profile by ID. The ID is the only required parameter.

DELETE /Account/EndUserProfiles/{id}

Authentication Type

Basic Authentication (Account-level)

Request

Parameter Description Type Required
id ID of the end user profile. string (path) Yes

Example Request

curl -X DELETE \
  https://api.voxolo.gy/v1/Account/EndUserProfiles/{id} \
  -H 'Authorization: Basic a1b2c3d4e5f6g7h8i9j0klnmopqrstuvwxyz' \
  -H 'Cache-Control: no-cache'

Response

No Response Body

Response Codes

Status Description
204 No content on success.
4xx & 5xx General Error Codes

View Balance

Returns the current account balance of the account. Services will stop when the balance equals $00.00. Use the Portal or Make Payment to add funds.

GET /Account/Billings/Balance

Authentication Type

Basic Authentication (Account-level)

Request

No Request Body

Example Request

curl -X GET \
  https://api.voxolo.gy/v1/Account/Billings/Balance \
  -H 'Authorization: Basic a1b2c3d4e5f6g7h8i9j0klnmopqrstuvwxyz' \
  -H 'Cache-Control: no-cache'

Response

Property Description Type
balance Current account balance in USD. integer

Example Response

{
  "balance": 100.0
}

Response Codes

Status Description
200 A successful request returns the balance.
4xx & 5xx General Error Codes

Make Payment

Make a credit card payment to increase your balance.

Payment methods (credit card, Paypal) can only be added in the Portal, but once you have added a payment method, you can make payments via this method

POST /Account/Payments

Authentication Type

Basic Authentication (Account-level)

Request

Parameter Description Type Required
amount The amount to be charged. integer (body) Yes
description Override the default description with this custom string. string (body) No
payment_method The payment method to be used. Omitting this property will charge the default payment method. object (body) No
payment_method.token If payment_method is included, this property is required. string (body) Yes
payment_method.method The method type, like ‘Credit Card’. Used to generate default description. string (body) No
payment_method.card_type The type of credit card. Visa, Master Card, American Express, etc. Used to generate default description. string (body) No
payment_method.last_four The last four digit of the credit card number. Used to generate default description. string (body) No

Example Request

curl -X POST \
  https://api.voxolo.gy/v1/Account/Payments \
  -H 'Authorization: Basic a1b2c3d4e5f6g7h8i9j0klnmopqrstuvwxyz' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 20,
    "payment_method": {
      "token": "6g6kpg",
      "method": "Credit Card",
      "card_type": "American Express",
      "last_four": "0005",
      "is_default": false,
      "created_on": "2016-03-16T10:09:00.000Z",
      "updated_on": "2016-03-16T12:49:00.000Z",
      "is_expired": false
    }
  }'

Response

Property Description Type
id Payment ID integer
transaction_id Transaction ID (from payment processor) integer
submitted_on Datetime of transaction. ISO Date string
amount Amount of payment. integer
description User-definable description of payment. string

Example Response

{
  "id": 123,
  "transaction_id": 12345,
  "submitted_on": "2016-09-07T17:27:23.486Z",
  "amount": 20.0,
  "description": "Payment via Dev Portal"
}

Response Codes

Status Description
200 Success returns a transaction object.
4xx & 5xx General Error Codes
4xx & 5xx Payment Error Codes

List Payment Methods

Returns the available payment methods assigned to an account.

GET /Account/Payments/Methods

Authentication Type

Basic Authentication (Account-level)

Request

No Request Body

Example Request

curl -X GET \
  https://api.voxolo.gy/v1/Account/Payments/Methods \
  -H 'Authorization: Basic a1b2c3d4e5f6g7h8i9j0klnmopqrstuvwxyz' \
  -H 'Cache-Control: no-cache'

Response

Property Description Type
payment_methods array
token Unique Method ID string
method Method type (Credit Card) string
card_type Type of card. string
last_four Last four digits of card number. string
is_default Is this the default payment method. boolean
created_on The datetime the method was added. ISO Date string
updated_on The datetime the method was last updated. ISO Date string
is_expired Is the method expired? boolean

Example Response

{
  "payment_methods": [
    {
      "token": "6g6kpg",
      "method": "Credit Card",
      "card_type": "American Express",
      "last_four": "0005",
      "is_default": false,
      "created_on": "2016-03-16T10:09:00.000Z",
      "updated_on": "2016-03-16T12:49:00.000Z",
      "is_expired": false
    },
    {
      "token": "5fvy2r",
      "method": "Credit Card",
      "card_type": "MasterCard",
      "last_four": "5100",
      "is_default": false,
      "created_on": "2016-03-16T09:53:00.000Z",
      "updated_on": "2016-03-16T09:53:00.000Z",
      "is_expired": false
    },
    {
      "token": "dtcsyg",
      "method": "Credit Card",
      "card_type": "Visa",
      "last_four": "1111",
      "created_on": "2016-03-15T13:27:00.000Z",
      "updated_on": "2016-03-15T13:28:00.000Z",
      "is_expired": false
    }
  ]
}

Response Codes

Status Description
200 A successful response return payment methods.
4xx & 5xx General Error Codes
4xx & 5xx Payment Error Codes

List Payment History

Returns payments history by date range.

GET /Account/Payments?{query_string}

Authentication Type

Basic Authentication (Account-level)

Request

Parameter Description Type Required
begin_date Set this parameter to the date/time to begin the query. ISO 8601 date format is required. string (query) No
end_date Set this parameter to the date/time to begin the query. ISO 8601 date format is required. string (query) No

Example Request

curl -X GET \
  'https://api.voxolo.gy/v1/Account/Payments?begin_date=2016-03-10&end_date=2016-03-16' \
  -H 'Authorization: Basic a1b2c3d4e5f6g7h8i9j0klnmopqrstuvwxyz' \
  -H 'Cache-Control: no-cache'

Response

Property Description Type
payments Array of payments array
payments[i].id Payment ID integer
payments[i].transaction_id Transaction ID (from payment processor) integer
payments[i].submitted_on Datetime of transaction. ISO Date string
payments[i].amount Amount of payment. integer
payments[i].description User-definable description of payment. string

Example Response

{
  "payments": [
    {
      "id": 1619,
      "submitted_on": "2016-03-15T21:27:11.000Z",
      "amount": 100,
      "description": "Credit Card American Express 0005 via api.voxolo.gy"
    },
    {
      "id": 1621,
      "submitted_on": "2016-03-15T21:28:04.000Z",
      "amount": 50,
      "description": "Default method via api.voxolo.gy"
    },
    {
      "id": 1627,
      "submitted_on": "2016-03-16T01:00:03.000Z",
      "amount": 20,
      "description": "Credit Card American Express 0005 via api.voxolo.gy"
    }
  ]
}

Response Codes

Status Description
200 Success returns an array of payments.
4xx & 5xx General Error Codes
4xx & 5xx Payment Error Codes

Application Sub Accounts

Create Sub Accounts

Creates a new Sub Account under the appropriate application based upon the API Key used to authenticate.

POST /SubAccounts

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
name The name of the Sub Account. string (body) Yes
port_out_pin PIN number used when creating a port out request. The port out PIN on the Sub Account is used over a PIN on the Application. If there is a port out PIN on the phone number, that PIN will be used over the Sub Account PIN. string No
service_address Object describing the service address (primary location where the service will be used) of the Sub Account. A Sub Account (child) will inherit the service address of the Application (parent) if there no service address is set on the Sub Account object No
service_address.address_1 Address line 1 (Street address/PO Box) string Conditional
service_address.address_2 Address line 2 (Suite/Unit/Apartment) string Conditional
service_address.city City/Town/Village/District string Conditional
service_address.region Region/State/Province string Conditional
service_address.postal_code The postal or zip code string Conditional
service_address.country The service address country code. The code country code must be given in ISO Alpha-2 format string Conditional
service_address.type_of_service The type of service address. Accepts: business or residence string Conditional

Example Request

curl -X POST \
  https://api.voxolo.gy/v1/SubAccounts \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "name": "My First Sub Account",
    "port_out_pin": "1234",
    "service_address": {
      "address_1": "4695 MacArthur Ct",
      "address_2": "",
      "city": "Newport Beach",
      "region": "CA",
      "postal_code": "92660",
      "country": "US",
      "type_of_service": "business"
    }
  }'

Response

Property Description Type
id The ID of the Sub Account integer
name The name string
created_on The date the subaccount was created. ISO date string
modified_on The date the subaccount was modified. (Replaced by updated_on, scheduled to be deprecated Jan 2021) ISO date string
updated_on The date the subaccount was last updated on. ISO date string
sip_domains The available SIP URI endpoints for this Sub Account object
sip_domains.callflows The unique SIP URI for CallFlows string
sip_domains.callflows_authentication An array of Sourve/Value pairs defining an access control list for the Callflows API. Default is null on create and can only be modified via the Update Sub Account method. array

Example Response

{
  "id": "0",
  "name": "My First Sub Account",
  "created_on": "2019-01-29T16:24:21-08:00",
  "modified_on": "2019-01-29T16:24:21-08:00",
  "updated_on": "2019-01-29T16:24:21-08:00",
  "port_out_pin": "1234",
  "service_address": {
    "address_1": "4695 MacArthur Ct",
    "address_2": "",
    "city": "Newport Beach",
    "region": "CA",
    "postal_code": "92660",
    "country": "US",
    "type_of_service": "business"
  },
  "sip_domains": {
    "callflows": "0000-0000.accounts.sip.voxolo.gy",
    "callflows_authentication": null, 
    "default_sip_authentication": null
  }
}

Response Codes

Status Description
201 Success returns a response
4xx & 5xx Sub Account Error Codes

List Sub Accounts

Returns a list of all Sub Accounts under your application.

GET /SubAccounts?{query_string}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
page The page number to return. Zero-based index. Defaults to 0 integer (query) No
page_size The number of subaccounts per page. Defaults to 25 integer (query) No
status Accepts: active or inactive. Default includes active. string (query) No

Example Request

curl -X GET \
  https://api.voxolo.gy/v1/SubAccounts&page=0&page_size=10 \
  -H 'Cache-Control: no-cache' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

Property Description Type
subaccounts List of Sub Accounts array
subaccounts[i].id The ID of the Sub Account. integer
subaccounts[i].name The name of the Sub Account. string
subaccounts[i].created_on The date the subaccount was created. ISO date string
subaccounts[i].modified_on The date the subaccount was modified. (Replaced by updated_on, scheduled to be deprecated Jan 2021) ISO date string
subaccounts[i].updated_on The date the subaccount was last updated on. ISO date string
subaccounts[i].notes Notes on the subaccount. Useful for differentiating subaccounts. string
subaccounts[i].status The current status of the subaccount. Includes: active or inactive. string

Example Response

{
  "subaccounts": [
    {
      "id": 0,
      "name": "My First Sub Account",
      "created_on": "2018-04-16T13:43:32-07:00",
      "modified_on": "2019-01-29T16:24:21-08:00",
      "updated_on": "2019-01-29T16:24:21-08:00",
      "notes": null,
      "status": "active"
    }
  ],
  "pagination": {
    "current_page": 0,
    "total_pages": 1,
    "total_items": 1,
    "items_per_page": 10
  }
}

Response Codes

Status Description
200 Success returns a list of Sub Accounts
4xx & 5xx Sub Account Error Codes

View Sub Account Detail

Returns the Sub Account detail for any individual Sub Account based upon the Sub Account ID.

GET /SubAccounts/{id}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
id ID of the sub account. integer (path) Yes

Example Request

curl -X GET \
  https://api.voxolo.gy/v1/SubAccounts/0 \
  -H 'Cache-Control: no-cache' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

Property Description Type
id The ID of the Sub Account integer
name The name of the Sub Account. string
created_on The date the subaccount was created. ISO date string
modified_on The date the subaccount was modified. (Replaced by updated_on, scheduled to be deprecated Jan 2021) ISO date string
updated_on The date the subaccount was last updated on. ISO date string
notes Notes on the subaccount. Useful for differentiating subaccounts. string
status The current status of the subaccount. Includes: active or inactive. string
sip_domains The available SIP URI endpoints for this Sub Account object
sip_domains.callflows The unique SIP URI for CallFlows string
sip_domains.callflows_authentication An array of Sourve/Value pairs defining an access control list for the Callflows API. Default is null on create and can only be modified via the Update Sub Account method. array
sip_domains.callflows_authentication[i].source The source of the call request. Includes: other, twilio, msoft (microsoft). array
sip_domains.callflows_authentication[i].value If the source is twilio, value is your Account ID. If the source is other, value is an IP address. If the source is msoft, value is null as it defaults to Microsoft’s list of IPs. array
port_out_pin PIN number used when creating a port out request. The port out PIN on the Sub Account is used over a PIN on the Application. If there is a port out PIN on the phone number, that PIN will be used over the Sub Account PIN. string
service_address Object describing the service address (primary location where the service will be used) of the Sub Account. A Sub Account (child) will inherit the service address of the Application (parent) if there no service address is set on the Sub Account object
service_address.address_1 Address line 1 (Street address/PO Box) string
service_address.address_2 Address line 2 (Suite/Unit/Apartment) string
service_address.city City/Town/Village/District string
service_address.region Region/State/Province string
service_address.postal_code The postal or zip code string
service_address.country The service address country code (ISO Alpha-2) string
service_address.type_of_service The type of service address. Returns: business or residence string

Example Response

{
  "id": 0,
  "name": "My First Sub Account",
  "created_on": "2018-04-16T13:43:32-07:00",
  "modified_on": "2019-01-29T16:24:21-08:00",
  "updated_on": "2019-01-29T16:24:21-08:00",
  "port_out_pin": "1234",
  "service_address": {
    "address_1": "4695 MacArthur Ct",
    "address_2": "",
    "city": "Newport Beach",
    "region": "CA",
    "postal_code": "92660",
    "country": "US",
    "type_of_service": "business"
  },
  "sip_domains": {
    "callflows": "0000-0000.accounts.sip.voxolo.gy",
    "callflows_authentication": [
      {
        "source": "twilio",
        "value": "aaaa-eeeee-ooooo-uuuu"
      },
      {
        "source": "other",
        "value": "1.1.1.1"
      }
    ]
  }
}

Response Codes

Status Description
200 Success returns a Sub Account detail
4xx & 5xx Sub Account Error Codes

Update Sub Account

Modifies the Sub Account detail for any individual Sub Account based upon the Sub Account ID.

PUT /SubAccounts/{id}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
id ID of the sub account. integer (path)
name The name of the Sub Account. string (body)
port_out_pin PIN number used when creating a port out request. The port out PIN on the Sub Account is used over a PIN on the Application. If there is a port out PIN on the phone number, that PIN will be used over the Sub Account PIN. string (body)
status The current status of the subaccount. Accepts: active or inactive. string (body)
sip_domains The available SIP URI endpoints for this Sub Account object
sip_domains.callflows The unique SIP URI for CallFlows string
sip_domains.callflows_authentication An array of Sourve/Value pairs defining an access control list for the Callflows API. Default is null on create and can only be modified via the Update Sub Account method. array
sip_domains.callflows_authentication[i].source The source of the call request. Includes: other, twilio, msoft (microsoft). array
sip_domains.callflows_authentication[i].value If the source is twilio, value is your Account ID. If the source is other, value is an IP address. If the source is msoft, value is null as it defaults to Microsoft’s list of IPs. array
service_address Object describing the service address (primary location where the service will be used) of the Sub Account. A Sub Account (child) will inherit the service address of the Application (parent) if there no service address is set on the Sub Account object
service_address.address_1 Address line 1 (Street address/PO Box) string (body)
service_address.address_2 Address line 2 (Suite/Unit/Apartment) string (body)
service_address.city City/Town/Village/District string (body)
service_address.region Region/State/Province string (body)
service_address.postal_code The postal or zip code string (body)
service_address.country The service address country code. The country code must be given in ISO Alpha-2 format string (body)
service_address.type_of_service The type of service address. Accepts: business or residence string (body)

Example Request

curl -X PUT \
  https://api.voxolo.gy/v1/SubAccounts/1234 \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "name": "My First Sub Account",
    "port_out_pin": "1234",
    "sip_domains": {
      "callflows": "71114-2050516.accounts.sip.voxolo.gy",
      "callflows_authentication": [
        {
          "source": "other",
          "value": "1.1.1.1"
        }
      ]
    }
    "service_address": {
      "address_1": "4695 MacArthur Ct",
      "address_2": "",
      "city": "Newport Beach",
      "region": "CA",
      "postal_code": "92660",
      "country": "US",
      "type_of_service": "business"
    }
  }'

Response

Property Description Type
id The ID of the Sub Account. integer
name The name of the Sub Account. string
created_on The date the subaccount was created. ISO date string
modified_on The date the subaccount was modified. (Replaced by updated_on, scheduled to be deprecated Jan 2021) ISO date string
updated_on The date the subaccount was last updated on. ISO date string
port_out_pin PIN number used when creating a port out request. The port out PIN on the Sub Account is used over a PIN on the Application. If there is a port out PIN on the phone number, that PIN will be used over the Sub Account PIN. string
sip_domains The available SIP URI endpoints for this Sub Account object
sip_domains.callflows The unique SIP URI for CallFlows string
sip_domains.callflows_authentication An array of Sourve/Value pairs defining an access control list for the Callflows API. Default is null on create and can only be modified via the Update Sub Account method. array
sip_domains.callflows_authentication[i].source The source of the call request. Includes: other, twilio, msoft (microsoft). array
sip_domains.callflows_authentication[i].value If the source is twilio, value is your Account ID. If the source is other, value is an IP address. If the source is msoft, value is null as it defaults to Microsoft’s list of IPs. array
service_address Object describing the service address (primary location where the service will be used) of the Sub Account. A Sub Account (child) will inherit the service address of the Application (parent) if there no service address is set on the Sub Account object
service_address.address_1 Address line 1 (Street address/PO Box) string
service_address.address_2 Address line 2 (Suite/Unit/Apartment) string
service_address.city City/Town/Village/District string
service_address.region Region/State/Province string
service_address.postal_code The postal or zip code string
service_address.country The service address country code (ISO Alpha-2) string
service_address.type_of_service The type of service address. Returns: business or residence string

Example Response

{
  "id": 1234,
  "name": "My First Sub Account",
  "created_on": "2018-04-16T13:43:32-07:00",
  "modified_on": "2019-01-29T16:24:21-08:00",
  "updated_on": "2019-01-29T16:24:21-08:00",
  "port_out_pin": "1234",
  "sip_domains": {
    "callflows": "0000-000000.accounts.sip.voxolo.gy",
    "callflows_authentication": [
      {
        "source": "other",
        "value": "1.1.1.1"
      }
    ]
  },
  "service_address": {
    "address_1": "4695 MacArthur Ct",
    "address_2": "",
    "city": "Newport Beach",
    "region": "CA",
    "postal_code": "92660",
    "country": "US",
    "type_of_service": "business"
  },
  "sip_domains": {
    "callflows": "0000-0000.accounts.sip.voxolo.gy"
  }
}

Response Codes

Status Description
201 Success returns name and ID of Sub Account which was updated.
4xx & 5xx Sub Account Error Codes

Delete Sub Account

Deletes the specific Sub Account based on the Sub Account ID.

DELETE /SubAccounts/{id}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
id ID of the sub account. integer (path) Yes

Example Request

curl -X DELETE \
  https://api.voxolo.gy/v1/SubAccounts/12345 \
  -H 'Cache-Control: no-cache' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

No Response Body

Response Codes

Status Description
204 No content on success.
4xx & 5xx Sub Account Error Codes

Caller IDs

Create Caller ID

Creates a Caller ID. Caller IDs enable you make outbound calls that appear to be from a phone number that you assert. Caller IDs must be in E.164 format. Example: +17145551212.

Note: To place a call via a Caller ID, it must be verified first. See POST /CallerIDs/{caller_id}/Verify.

POST /CallerIDs/{caller_id}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
caller_id E.164 formatted phone number. string (path) Yes
description The description of the caller_id. string No
verification Configuration for caller ID verification. object No
verification.type The method by which this Caller ID will be verified: code or transfer. The default is code. string No

Example Request

curl -X POST \
  'https://api.voxolo.gy/v1/CallerIDs/%2B17145551212' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "description": "Desk Phone",
    "verification": {
      "type": "code"
    }
  }'

Response

Property Description Type
no The Caller ID in E.164 format. string
formatted The Caller ID in human-friendly format. string
capabilities Currently, will only/always contain voice_outbound for Caller IDs. array
description The user-defined description for the Caller ID. string
created_on The date/time this Caller ID object was created under this Application or Sub Account. ISO Date (string)
updated_on The date/time this Caller ID was last updated. ISO Date (string)
status The status: verified, unverified, blocked. string
usage The count of all-time calls from this Caller ID. integer
verification Configuration object for Caller ID verification. object
verification.type The method by which this Caller ID will be verified: code or transfer. The default is code. string
verification.prefix The prefix or phone number that Voxology’s automated verification call will be coming from. This is so you can either let your customer know what number they should be expecting a call from, or you can automate the verification process. string
verification.transfer_to The SIP URI to transfer the verification call to. Only returned when type is transfer. string

Example Response

{
  "no": "+17145551212",
  "formatted": "(714) 555-1212",
  "capabilities": ["voice_outbound"],
  "created_on": "2019-06-08T08:44:57-07:00",
  "updated_on": "2019-11-09T21:00:53-08:00",
  "description": "Desk phone at work.",
  "status": "unverified",
  "usage": 0,
  "verification": {
    "type": "code",
    "prefix": "+19498851559"
  }
}

Response Codes

Status Description
201 Returns Caller ID Object
4xx & 5xx General Error Codes
4xx & 5xx CallerID Error Codes

List Caller IDs

Returns a list of Caller IDs.

GET /CallerIDs?{query_string}

Authentication Type

API Key (Application-level)

Request

Name Description Type Required
page The page number to return. Zero-based index. Defaults to 0 integer (query) No
page_size The number of caller IDs per page. Defaults to 25 integer (query) No
sort_by The field to sort the list of Caller IDs by. Accepts created_on, updated_on, no (phone number), status and assigned_to. string (query) No
sort_order The direction to sort the list of Caller IDs by. Accepts asc or desc. Defaults to asc. string (query) No

Example Request

curl -X GET \
  https://api.voxolo.gy/v1/CallerIDs&page=0&page_size=10 \
  -H 'Cache-Control: no-cache' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

Property Description Type
caller_ids An array of currently active CallerID details. array
caller_ids[i].no The Caller ID in E.164 format. string
caller_ids[i].formatted The Caller ID in human-friendly format. string
caller_ids[i].capabilities Will only/always contain voice_outbound for Caller IDs. array
caller_ids[i].created_on The date/time this Caller ID object was created under this Application or Sub Account. ISO Date (string)
caller_ids[i].updated_on The date/time this Caller ID was last updated. ISO Date (string)
caller_ids[i].description The user-defined description for the Caller ID. string
caller_ids[i].status The status: verified, unverified, blocked. string
caller_ids[i].usage The count of all-time calls from this Caller ID. integer
caller_ids[i].verification Configuration object for Caller ID verification. object
caller_ids[i].verification.type The method by which this Caller ID will be verified: code or transfer. The default is code. string
caller_ids[i].verification.prefix The prefix or phone number that Voxology’s automated verification call will be coming from. This is so you can either let your customer know what number they should be expecting a call from, or you can automate the verification process. string
caller_ids[i].verification.transfer_to The SIP URI to transfer the verification call to. Only returned when type is transfer. string

Example Response

{
  "caller_ids": [
    {
      "no": "+17145551212",
      "formatted": "(714) 555-1212",
      "capabilities": ["voice_outbound"],
      "created_on": "2019-06-08T08:44:57-07:00",
      "updated_on": "2019-11-09T21:00:53-08:00",
      "description": "Desk phone at work.",
      "status": "unverified",
      "usage": 0,
      "verification": {
        "type": "code",
        "prefix": "+19498851559"
      }
    },
    {
      "no": "+17145551313",
      "formatted": "(714) 555-1313",
      "capabilities": ["voice_outbound"],
      "created_on": "2019-06-08T08:44:57-07:00",
      "updated_on": "2019-11-09T21:00:53-08:00",
      "description": "Coworker's desk phone.",
      "status": "unverified",
      "usage": 0,
      "verification": {
        "type": "transfer",
        "prefix": "+1410915",
        "transfer_to": "sip:+17145551313@verifycallerid.voxolo.gy"
      }
    }
  ],
  "pagination": {
    "current_page": 0,
    "total_pages": 1,
    "total_items": 2,
    "items_per_page": 10
  }
}

Response Codes

Status Description
200 Returns a list of callerIDs.
4xx & 5xx General Error Codes
4xx & 5xx CallerID Error Codes

View Caller ID

Returns the Caller ID configuration of a specific phone number. Phone number must be in E.164 format. (example: +17145551212)

GET /CallerIDs/{caller_id}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
caller_id E.164 formatted phone number. string (path) Yes

Example Request

curl -X GET \
  'https://api.voxolo.gy/v1/CallerIDs/%2B17145551212' \
  -H 'Cache-Control: no-cache' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

Property Description Type
no The Caller ID in E.164 format. string
formatted The Caller ID in human-friendly format. string
capabilities Currently, will only/always contain voice_outbound for Caller IDs. array
description The user-defined description for the Caller ID. string
created_on The date/time this Caller ID object was created under this Application or Sub Account. ISO Date (string)
updated_on The date/time this Caller ID was last updated. ISO Date (string)
status The status: verified, unverified, blocked. string
usage The count of all-time calls from this Caller ID. integer
verification Configuration object for Caller ID verification. object
verification.type The method by which this Caller ID will be verified: code or transfer. The default is code. string
verification.prefix The prefix or phone number that Voxology’s automated verification call will be coming from. This is so you can either let your customer know what number they should be expecting a call from, or you can automate the verification process. string
verification.transfer_to The SIP URI to transfer the verification call to. Only returned when type is transfer. string

Example Response

{
  "no": "+17145551212",
  "formatted": "(714) 555-1212",
  "capabilities": ["voice_outbound"],
  "created_on": "2019-06-08T08:44:57-07:00",
  "updated_on": "2019-11-09T21:00:53-08:00",
  "description": "Desk phone at work.",
  "status": "unverified",
  "usage": 0,
  "verification": {
    "type": "code",
    "prefix": "+19498851559"
  }
}

Response Codes

Status Description
200 Returns Caller ID Object
4xx & 5xx General Error Codes
4xx & 5xx CallerID Error Codes

Update Caller ID

Updates the Caller ID configuration of a specific phone number. Phone number must be in E.164 format. (example: +17145551212)

PUT /CallerIDs/{caller_id}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
caller_id E.164 formatted phone number. string (path) Yes
description The description of the caller_id. string (body) No
verification Configuration for caller ID verification. object No
verification.type The method by which this Caller ID will be verified: code or transfer. The default is code. string No

Example Request

curl -X PUT \
  'https://api.voxolo.gy/v1/CallerIDs/%2B17145551212' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
      "description": "Desk phone at work.",
      "verification": {
        "type": "transfer"
      }
  }'

Response

Property Description Type
no The Caller ID in E.164 format. string
formatted The Caller ID in human-friendly format. string
capabilities Currently, will only/always contain voice_outbound for Caller IDs. array
descriptio The user-defined description for the Caller ID. string
created_on The date/time this Caller ID object was created under this Application or Sub Account. ISO Date (string)
updated_on The date/time this Caller ID was last updated. ISO Date (string)
status The status: verified, unverified, blocked. string
usage The count of all-time calls from this Caller ID. integer
verification Configuration object for Caller ID verification. object
verification.type The method by which this Caller ID will be verified: code or transfer. The default is code. string
verification.prefix The prefix or phone number that Voxology’s automated verification call will be coming from. This is so you can either let your customer know what number they should be expecting a call from, or you can automate the verification process. string
verification.transfer_to The SIP URI to transfer the verification call to. Only returned when type is transfer. string

Example Response

{
  "no": "+17145551212",
  "formatted": "(714) 555-1212",
  "capabilities": ["voice_outbound"],
  "created_on": "2019-06-08T08:44:57-07:00",
  "updated_on": "2019-11-09T21:00:53-08:00",
  "description": "Desk phone at work.",
  "status": "unverified",
  "usage": 0,
  "verification": {
    "type": "transfer",
    "prefix": "+1410915",
    "transfer_to": "sip:+17145551212@verifycallerid.voxolo.gy"
  }
}

Response Codes

Status Description
200 Returns Caller ID Object
4xx & 5xx General Error Codes
4xx & 5xx CallerID Error Codes

Delete Caller ID

Deletes the Caller ID configuration of a specific phone number. Phone number must be in E.164 format. (example: +17145551212)

DELETE /CallerIDs/{caller_id}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
caller_id E.164 formatted phone number. string (path) Yes

Example Request

curl -X DELETE \
  'https://api.voxolo.gy/v1/CallerIDs/%2B17145551212' \
  -H 'Cache-Control: no-cache' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

No Response Body

Response Codes

Status Description
204 No content on success.
4xx & 5xx General Error Codes
4xx & 5xx CallerID Error Codes

Verify Caller ID

This request will trigger a call to the given phone number. There are two methods of verifying caller IDs after the call has been placed: code and transfer.

For type code, the PIN in the response must be entered after the prompt to allow the Caller ID to be used in outbound dialing.

For type transfer, the call to the phone number must be transferred back to Voxology using the SIP URI provided in the verification object of the caller ID. The URI follows the following format, sip:{callerID}@verifycallerid.voxolo.gy, and is returned in the Create Caller ID, View Caller ID and List Caller IDs methods if verification type transfer is assigned.

POST /CallerIDs/{caller_id}/Verify

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
caller_id E.164 formatted phone number. string (path) Yes

Example Request

curl -X POST \
  'https://api.voxolo.gy/v1/CallerIDs/%2B17145551212/Verify' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

Property Description Type
id The reference ID of the verify request. Not used in the API. integer
verify_pin The digits to enter during the verification phone call; null if verification_type is transfer. string
verification_type The verification method used for this caller ID. Can be code or transfer. string

Example Response

{
  "id": 12345,
  "verify_pin": "9876",
  "verification_type": "code"
}

Response Codes

Status Description
200 Verification information, like the PIN code.
4xx & 5xx General Error Codes
4xx & 5xx CallerID Error Codes

Call Flows (Callback Configuration)

Update Call Flow Configuration

NOTE: On January 10, 2022, we are updating the behavior for PUT /CallFlows/Configurations/PhoneNumbers/{phone_number}.

This method currently works like a PATCH, where only parameters provided in the request-body are updated. The update changes this method to work like a proper PUT, replacing the entire Callflow Configuration with the request-body and stomping any parameters not provided. This change allows for removing parts of the Configuration, such as callback_sms and callback_failover, without needing to delete the Configuration.

Append the parameter, ?future=now, to the PUT request path to use the new behavior in advance of January 10, 2022. It will be ignored after the update.

PUT /CallFlows/Configurations/PhoneNumbers/Default currently works in this way.

Default Configuration

PUT /CallFlows/Configurations/Default

Creates or updates the settings for Inbound Phone Numbers or Caller IDs. CallFlows parameters include the callback.url where Voxology will send Callback Requests to retrieve instructions for what you want us to do on the call (using our Call Flow Actions).

Phone Number Configuration

PUT /CallFlows/Configurations/PhoneNumbers/{phone_number}

Extensions Default Configuration

PUT /CallFlows/Configurations/Extensions/Default

Extension Configuration

PUT /CallFlows/Configurations/Extensions/{extension}

You may assign unique Call Flow Configurations to any Inbound Phone Number, Verified Outbound Caller ID, or Extension. The Default Call Flow Configuration on the Application or on any Application’s Sub Account, will serve as a “catch all” configuration for any Inbound Phone Number or Outbound Caller ID that does not have a configuration of it’s own. Extensions do not inherit the same Default Call Flow Configuration as Phone Numbers and Caller IDs. You may set an Extensions Default Call Flow Configuration specifically for Extensions.

Note: If Inbound Phone Numbers have been assigned to /ParkingLot, all CallFlows settings will be ignored. Inbound Phone Numbers must to be assigned to PhoneNumbers/CallFlows to be controlled.

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
phone_number Accepts a provisioned inbound phone number or verified caller ID in E.164 format (example: +17145551212). Not applicable to the /Default configuration. string (path) Conditional
extension Accepts an existing extension created on this application. Not applicable to the /Default configuration. string (path) Conditional
callback An object that describes the callback parameters. object (body) Yes
callback.url The endpoint URL where the request will be sent. string (body) Yes
callback.method The request method. Accepts: POST, GET. Default: POST. string (body) No
callback.content_type The format of the payload posted to the endpoint. Options: application/json, application/xml and application/x-www-form-urlencoded. Default: application/json. string (body) No
callback.headers An associative array of header names and values to include in every request. Use this field to include any desired authorization keys. object (body) No
callback.timeout In seconds, the time for the callback request to wait for a response before timing out. Allowed range: 1 - 15. Default: 5. integer (body) No
callback_failover If the callback request fails, a second request attempt will be made to this endpoint. Contains the same properties as the callback object. object (body) No
callback_sms The endpoint for inbound SMS callbacks to request. If not set, the default callback object is used. Contains the same properties as the callback object. Not accepted on Extensions Call Flow Configurations. object (body) No
callback_sms_failover If the callback_sms request fails, a second request attempt will be made to this endpoint. Contains the same properties as the callback object. Not accepted on Extensions Call Flow Configurations. object (body) No
answer_on_ring The number of allowed rings before the call is answered. Allowed range: 1 - 10. Default: 1. integer (body) No
custom_data Any data you want included in every request. object (body) No

Example Request

curl -X PUT \
  'https://api.voxolo.gy/v1/CallFlows/Configurations/PhoneNumbers/%2B17145551213' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "callback": {
      "method": "POST",
      "url": "https://myserver.com/ivr_app/callback-handler",
      "content_type": "application/json",
      "headers": {
        "X-Custom-Name": "custom header value"
      }
    },
    "answer_on_ring": 5,
    "custom_data": {
      "foo": "bar"
    }
  }'

Example Request // Minimal Callback Config

curl -X PUT \
  'https://api.voxolo.gy/v1/CallFlows/Configurations/PhoneNumbers/%2B17145551213' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "callback": {
      "method": "POST",
      "url": "https://myserver.com/ivr_app/callback-handler",
      "content_type": "application/json"
    },
    "answer_on_ring": 5,
    "custom_data": {
      "foo": "bar"
    }
  }'

Example // Extension Callback Config

curl -X PUT \
  'https://api.voxolo.gy/v1/CallFlows/Configurations/Extensions/123' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "callback": {
      "method": "POST",
      "url": "https://myserver.com/ivr_app/extensions/callback-handler",
      "content_type": "application/json",
      "headers": {
        "X-Custom-Name": "custom header value"
      }
    },
    "callback_failover": {
      "method": "GET",
      "url": "https://myserver.com/ivr_app/extensions/callback-handler-failover",
      "content_type": "application/json"
    },
    "custom_data": {
      "foo": "bar"
    }
  }'

Response

Property Description Type
no An object that describes the number and country code, or extension, this configuration is applied to. object
no.value The inbound phone number, verified caller ID in E.164 format (example: +17145551212), or the extension. Set to application or subaccount for Default Configuration. string
no.type Either the country code of the provisioned number, DEFAULT or EXTENSION. string
callback An object that describes the callback parameters. object
callback.url The endpoint URL where the request will be sent. string
callback.method The request method. Includes: POST, GET. string
callback.content_type The format of the payload posted to the endpoint. Options: application/json, application/xml and application/x-www-form-urlencoded. Default: application/json. string
callback.headers An associative array of header names and values to include in every request. Use this field to include any desired authorization keys. object
callback.timeout In seconds, the time for the callback request to wait for a response before timing out. Allowed range: 1 - 15. Default: 5. integer
callback_failover If the callback request fails, a second request attempt will be made to this endpoint. Contains the same properties as the callback object. object
callback_sms The endpoint for inbound SMS callbacks to request. If not set, the default callback object is used. Contains the same properties as the callback object. Not accepted on Extensions Call Flow Configurations. object
callback_sms_failover If the callback_sms request fails, a second request attempt will be made to this endpoint. Contains the same properties as the callback object. Not accepted on Extensions Call Flow Configurations. object
answer_on_ring The number of allowed rings before the call is answered. Allowed range: 1 - 10. Default: 1. integer
created_on The date/time the Call Flow configuration was first created. string
updated_on The date/time the Call Flow configuration was last updated. string
custom_data Any data you want included in every request. object
type Options: default, phone_number (inbound and outbound), caller_id (outbound only), extension, and default_extension. string

Example Response // Default update

{
  "no": {
    "value": "application",
    "type": "DEFAULT"
  },
  "callback": {
    "method": "POST",
    "url": "https://myserver.com/ivr_app/default-handler",
    "headers": {
      "Custom-Name": "custom header value"
    },
    "content_type": "application/json",
    "timeout": 5
  },
  "answer_on_ring": 1,
  "updated_on": "2019-01-29T16:24:21-08:00",
  "created_on": "2018-04-16T13:43:32-07:00",
  "custom_data": {
    "foo": "bar"
  },
  "log_callbacks_until": "2019-07-01T18:21:35.207Z",
  "type": "default"
}

Example Response // Number update

{
  "no": {
    "value": "+17145551212",
    "type": "US"
  },
  "callback": {
    "method": "POST",
    "url": "https://myserver.com/ivr_app/callback-handler",
    "headers": {
      "Custom-Name": "custom header value"
    },
    "content_type": "application/json",
    "timeout": 1
  },
  "answer_on_ring": 1,
  "updated_on": "2019-01-29T16:24:21-08:00",
  "created_on": "2018-04-16T13:43:32-07:00",
  "custom_data": null,
  "log_callbacks_until": "2018-03-09T02:03:07.104Z",
  "type": "phone_number"
}

Example Response // Extensions Default update

{
  "no": {
    "value": "+17145551212",
    "type": "US"
  },
  "callback": {
    "method": "POST",
    "url": "https://myserver.com/ivr_app/callback-handler",
    "headers": {
      "Custom-Name": "custom header value"
    },
    "content_type": "application/json",
    "timeout": 1
  },
  "answer_on_ring": 1,
  "updated_on": "2019-01-29T16:24:21-08:00",
  "created_on": "2018-04-16T13:43:32-07:00",
  "custom_data": null,
  "log_callbacks_until": "2018-03-09T02:03:07.104Z",
  "type": "default_extension"
}

Example Response // Extension update

{
  "no": {
    "value": "123",
    "type": "EXTENSION"
  },
  "callback": {
    "method": "POST",
    "url": "https://myserver.com/ivr_app/callback-handler",
    "headers": {
      "Custom-Name": "custom header value"
    },
    "content_type": "application/json",
    "timeout": 1
  },
  "answer_on_ring": 1,
  "updated_on": "2019-01-29T16:24:21-08:00",
  "created_on": "2018-04-16T13:43:32-07:00",
  "custom_data": null,
  "log_callbacks_until": "2018-03-09T02:03:07.104Z",
  "type": "extension"
}

Response Codes

Status Description
200 Successful request.
4xx & 5xx General Error Codes
4xx & 5xx Call Flow Error Codes

List Call Flow Configurations

Returns current callback configurations for all Inbound Phone Numbers and Caller IDs.

List Phone Numbers Configurations GET /CallFlows/Configurations/PhoneNumbers?{query_string}

List Extensions Configurations GET /CallFlows/Configurations/Extensions?{query_string}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
page The page number to return. Zero-based index. Defaults to 0 integer (query) No
page_size The number of callback configurations per page. Defaults to 25 integer (query) No

Example Request // Phone Numbers

curl -X GET \
  https://api.voxolo.gy/v1/CallFlows/Configurations/PhoneNumbers&page=0&page_size=10 \
  -H 'Cache-Control: no-cache' \
  -H 'X-API-Key: YOUR_API_KEY'

Example Request // Extensions

curl -X GET \
  https://api.voxolo.gy/v1/CallFlows/Configurations/Extensions&page=0&page_size=10 \
  -H 'Cache-Control: no-cache' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

Property Description Type
callbacks An array of callback parameters. array
callbacks[i].no An object that describes the phone number and country code to configure. object
callbacks[i].no.value Accepts a provisioned inbound phone number or verified caller ID in E.164 format (example: +17145551212). Not applicable to the /Default configuration. string
callbacks[i].no.type Either the country code of the provisioned number or DEFAULT. string
callbacks[i].callback An object that describes the callback parameters. object
callbacks[i].callback.url The endpoint URL where the request will be sent. string
callbacks[i].callback.method The request method. Accepts: POST, GET. Default: POST. string
callbacks[i].callback.content_type The format of the payload posted to the endpoint. Options: application/json, application/xml and application/x-www-form-urlencoded. Default: application/json. string
callbacks[i].callback.headers An associative array of header names and values to include in every request. Use this field to include any desired authorization keys. object
callbacks[i].callback.timeout In seconds, the time for the callback request to wait for a response before timing out. Allowed range: 1 - 15. Default: 5. number
callbacks[i].callback_failover If the callback request fails, a second request attempt will be made to this endpoint. Contains the same properties as the callback object. object
callbacks[i].callback_sms The endpoint for inbound SMS callbacks to request. If not set, the default callback object is used. Contains the same properties as the callback object. Not accepted on Extensions Call Flow Configurations. object
callbacks[i].callback_sms_failover If the callback_sms request fails, a second request attempt will be made to this endpoint. Contains the same properties as the callback object. Not accepted on Extensions Call Flow Configurations. object
callbacks[i].answer_on_ring The number of allowed rings before the call is answered. Allowed range: 1 - 10. Default: 1. integer
callbacks[i].created_on The date/time the Call Flow configuration was first created. string
callbacks[i].updated_on The date/time the Call Flow configuration was last updated. string
callbacks[i].custom_data Any data you want included in every request. object
callbacks[i].type Options: default, phone_number (inbound and outbound), caller_id (outbound only), extension, and default_extension string

Example Response // Phone Numbers

{
  "callbacks": [
    {
      "no": {
        "value": "+17145551212",
        "type": "US"
      },
      "callback": {
        "url": "https://myserver.com/ivr_app/callback-handler",
        "method": "POST",
        "content_type": "application/json",
        "headers": {
          "X-Custom-Name": "custom header value"
        },
        "timeout": 5
      },
      "answer_on_ring": 1,
      "updated_on": "2019-01-29T16:24:21-08:00",
      "created_on": "2018-04-16T13:43:32-07:00",
      "custom_data": null,
      "type": "phone_number"
    }
  ],
  "pagination": {
    "current_page": 0,
    "total_pages": 1,
    "total_items": 1,
    "items_per_page": 10
  }
}

Example Response // Extensions

{
  "callbacks": [
    {
      "no": {
        "value": "123",
        "type": "EXTENSION"
      },
      "callback": {
        "url": "https://myserver.com/ivr_app/callback-handler",
        "method": "POST",
        "content_type": "application/json",
        "headers": {
          "X-Custom-Name": "custom header value"
        },
        "timeout": 5
      },
      "answer_on_ring": 1,
      "updated_on": "2019-01-29T16:24:21-08:00",
      "created_on": "2018-04-16T13:43:32-07:00",
      "custom_data": null,
      "type": "extension"
    }
  ],
  "pagination": {
    "current_page": 0,
    "total_pages": 1,
    "total_items": 1,
    "items_per_page": 10
  }
}

Response Codes

Status Description
200 Successful request.
4xx & 5xx General Error Codes
4xx & 5xx Call Flow Error Codes

View Call Flow Configuration

Default Configuration

GET /CallFlows/Configurations/Default

Returns either your Default callback configuration, the callback configuration of a specific phone number, the Extensions Default callback configuration or the callback configuration of a specific extension. Phone number must be in E.164 format. (example: +17145551212)

Phone Number Configuration

GET /CallFlows/Configurations/PhoneNumbers/{phone_number}

Extensions Default Configuration

GET /CallFlows/Configurations/Extensions/Default

Extension Configuration

GET /CallFlows/Configurations/Extensions/{extension}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
phone_number Accepts a provisioned inbound phone number or verified caller ID in E.164 format (example: +17145551212). Not applicable to the /Default configuration. string (path) Conditional
extension Accepts an existing extension created on this application. Not applicable to the /Default configuration. string (path) Conditional

Example Request // Phone Number

curl -X GET \
  'https://api.voxolo.gy/v1/CallFlows/Configurations/PhoneNumbers/%2B17145551212' \
  -H 'Cache-Control: no-cache' \
  -H 'X-API-Key: YOUR_API_KEY'

Example Request // Extension

curl -X GET \
  'https://api.voxolo.gy/v1/CallFlows/Configurations/Extensions/123' \
  -H 'Cache-Control: no-cache' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

Property Description Type
no An object that describes the phone number and country code to configure. object
no.value Accepts a provisioned inbound phone number or verified caller ID in E.164 format (example: +17145551212). Not applicable to the /Default configuration. string
no.type Either the country code of the provisioned number or DEFAULT. string
callback An object that describes the callback parameters. object
callback.url The endpoint URL where the request will be sent. string
callback.method The request method. Accepts: POST, GET. Default: POST. string
callback.content_type The format of the payload posted to the endpoint. Options: application/json, application/xml and application/x-www-form-urlencoded. Default: application/json. string
callback.headers An associative array of header names and values to include in every request. Use this field to include any desired authorization keys. object
callback.timeout In seconds, the time for the callback request to wait for a response before timing out. Allowed range: 1 - 15. Default: 5. integer
callback_failover If the callback request fails, a second request attempt will be made to this endpoint. Contains the same properties as the callback object. object
callback_sms The endpoint for inbound SMS callbacks to request. If not set, the default callback object is used. Contains the same properties as the callback object. Not accepted on Extensions Call Flow Configurations. object
callback_sms_failover If the callback_sms request fails, a second request attempt will be made to this endpoint. Contains the same properties as the callback object. Not accepted on Extensions Call Flow Configurations. object
answer_on_ring The number of allowed rings before the call is answered. Allowed range: 1 - 10. Default: 1. integer
custom_data Any data you want included in every request. object
created_on The date/time the Call Flow configuration was first created. string
updated_on The date/time the Call Flow configuration was last updated. string
type Options: default, phone_number (inbound and outbound), caller_id (outbound only) string

Example Response // Phone Number

{
  "no": {
    "value": "+17145551212",
    "type": "US"
  },
  "callback": {
    "url": "https://myserver.com/ivr_app/callback-handler",
    "method": "POST",
    "content_type": "application/json",
    "headers": {
      "X-Custom-Name": "custom header value"
    },
    "timeout": 5
  },
  "answer_on_ring": 1,
  "updated_on": "2019-01-29T16:24:21-08:00",
  "created_on": "2018-04-16T13:43:32-07:00",
  "custom_data": null
}

Example Response // Extension

{
  "no": {
    "value": "123",
    "type": "EXTENSION"
  },
  "callback": {
    "url": "https://myserver.com/ivr_app/callback-handler",
    "method": "POST",
    "content_type": "application/json",
    "headers": {
      "X-Custom-Name": "custom header value"
    },
    "timeout": 5
  },
  "answer_on_ring": 1,
  "updated_on": "2019-01-29T16:24:21-08:00",
  "created_on": "2018-04-16T13:43:32-07:00",
  "custom_data": null
}

Response Codes

Status Description
200 Successful request.
4xx & 5xx General Error Codes
4xx & 5xx Call Flow Error Codes

Delete Call Flow Configuration

Deletes the callback configuration settings of the specified phone number or extension. Phone number must be in E.164 format. (example: +17145551212)

This method does not release the phone number or delete the extension.

Default Configuration

DELETE /CallFlows/Configurations/Default

Phone Number Configuration

DELETE /CallFlows/Configurations/PhoneNumbers/{phone_number}

Extensions Default Configuration

DELETE /CallFlows/Configurations/Extensions/Default

Extension Configuration

DELETE /CallFlows/Configurations/Extensions/{extension}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
phone_number Accepts a provisioned inbound phone number or verified caller ID in E.164 format (example: +17145551212). Not applicable to the /Default configuration. Conditional Yes
extension Accepts an existing extension created on this application. Not applicable to the /Default configuration. Conditional Yes

Example Request // Phone Number

curl -X DELETE \
  'https://api.voxolo.gy/v1/CallFlows/Configurations/PhoneNumbers/%2B17145551212' \
  -H 'Cache-Control: no-cache' \
  -H 'X-API-Key: YOUR_API_KEY'

Example Request // Extension

curl -X DELETE \
  'https://api.voxolo.gy/v1/CallFlows/Configurations/Extensions/123' \
  -H 'Cache-Control: no-cache' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

No Response Body

Response Codes

Status Description
204 No content on success.
4xx & 5xx General Error Codes
4xx & 5xx Call Flow Error Codes

Calls

Make Call

Creates a call to the specified phone number. On connection, the call is put in the specified inbound_api and the callback config for the specified caller_id_no is executed.

POST /Dials/Connect

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
call The call object to connect. string (body) Yes
call.no The phone number or SIP destination to call. Phone numbers are in E.164 format (example: +19495551212). SIP destinations are formatted as abc123@sip.mypbx.com. string (body) Yes
call.caller_id_no The phone number that will appear as the Caller ID. Phone numbers are in E.164 format (example: +19495551212). This phone number should have been previously provisioned and assigned to CallFlows and configured with a CallFlow Callback. string (body) Yes
session_data This object will be included in the CallFlows callback, allowing custom data to be passed on dial. object (body) No
override_callback_config The phone number that is associated with the override configuration. Phone numbers are in E.164 format (example: +19495551212). If set, this number will be used to load a Callback Config, ignoring the caller_id_no. This is useful when making an outbound call from a Caller ID or not setting up Callback Configs for every Inbound Number. string (body) No
external_id A user-defined ID for the call. string (body) No
exernal_group_id A user-defined ID for a group of calls. string (body) No
inbound_api Defaults to CallFlows. string (body) No
timeout The maximum time to wait during ringing in seconds. Valid: 20 to 240. integer (body) No
max_call_time The maximum length of the call in seconds. Valid: 60 to 172800. integer (body) No

Example Request

curl -X POST \
  https://api.voxolo.gy/v1/Dials/Connect \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "call": {
      "no": "+17145551212",
      "caller_id_no": "+19495551212"
    },
    "session_data": {
      "name": "Bob",
      "age": 21
    },
    "override_callback_config": "+19495558989",
    "external_id":"external_id_123",
    "external_group_id":"group_id_123",
    "inbound_api": "CallFlows",
    "timeout": 60,
    "max_call_time": 60
  }'

Response

Example Response

Property Description Type
call The call object to connect. string
call.id The ID of the call. string
call.no The phone number dialed. string
call.caller_id_no The from phone number appearing as the caller ID. string
inbound_api The inbound CallFlow type the call.caller_id_no is assigned to. string 
{
  "call": {
    "id": "1234@56",
    "no": "+17145551212",
    "caller_id_no": "+19495551212"
  },
  "inbound_api": "CallFlows"
}

Response Codes

Status Description
201 Returns a Call object on success.
4xx & 5xx General Error Codes

List Live Calls

Returns a list of all live calls.

GET /LiveCalls?{query_string}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
sort_by Sort the call list by connected_time or ID. Defaults to connected_time. string (query) No
sort_order The order of call list uses the sort_by field. Accepts:asc, desc. Defaults to asc. string (query) No
filter_on_nos A comma-separated list of phone numbers to filter on. string (query) No
filter_on_call_id_nos A comma-separated list of provisioned phone numbers to filter on string (query) No
max_results The maximum number of calls to return. Default is 500. number (query) No
min_connected_time Returns calls with connected_time greater than or equal to this value. number (query) No
max_connected_time Returns calls with connected_time less than or equal to this value. number (query) No

Example Request

curl -X GET \
  'https://api.voxolo.gy/v1/LiveCalls?sort_order=desc' \
  -H 'Cache-Control: no-cache' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

Property Description Type
calls An array of calls. array
calls[i].id The ID of the call. string
calls[i].no The phone number of the caller. string
calls[i].caller_id_no The from phone number. Basically, not the caller’s number. string
calls[i].status The status of the call: live-queued, live-ringing, live-in-progress, completed, busy, canceled, failed, no-answer. See the Call Status table for details on call status. string
calls[i].date The date and time the call was connected (ISO 8601). string
calls[i].session_data The session_data set in the /Dials/Connect request and/or the DIAL and SESSIONDATA actions. object
calls[i].connected_time The call’s duration in milliseconds. long
calls[i].error null, unless an error occurs. This is an internal diagnostic error and may not be useful to the API developer. string
calls[i].app_id The ID of the application used for this call. string
calls[i].subaccount_id The Sub Account ID of the application the call belongs to. integer
longest_call The longest call. string
longest_call.id The ID of the call. string
longest_call.connected_time The duration of the longest call in ms. integer
shortest_call The shortest call. string
shortest_call.id The ID of the call. string
shortest_call.connected_time The duration of the shortest call in ms. integer
total_calls The total number of calls retrieved. integer

Example Response

{
  "calls": [
    {
      "id": "123@4567",
      "no": "+17145551212",
      "caller_id_no": "+19495551212",
      "status": "live-in-progress",
      "date": "2016-10-10T22:02:54.809Z",
      "session_data": null,
      "connected_time": 12000,
      "app_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "subaccount_id": 0
    }
  ],
  "longest_call": {
    "id": "123@4567",
    "connected_time": 12000
  },
  "shortest_call": {
    "id": "123@4567",
    "connected_time": 12000
  },
  "total_calls": 100
}

Response Codes

Status Description
200 Returns an array of Call objects.
4xx & 5xx General Error Codes

View Live Call Detail

Returns the details of a call by ID.

The details of a call are available to this method for five minutes after the call ends. After that, this method pulls the detail from our logs. There is a chance of this method returning a 404 should the logs take longer than five minutes to update.

GET /LiveCalls/{call_id}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
call_id A call ID. string (path) Yes

Example Request

curl -X GET \
  https://api.voxolo.gy/v1/LiveCalls/142877@7875 \
  -H 'Cache-Control: no-cache' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

Property Description Type
id The ID of the call. string
no The phone number of the caller. string
caller_id_no The from phone number. Basically, not the caller’s number. string
app_id The ID of the application the call is running under. string
status The status of the call: live-queued, live-ringing, live-in-progress, completed, busy, canceled, failed, no-answer. See the Call Status table for details on call status. string
detection The likely “caller” on the far end. Codes: fax, live_person, voicemail, unknown. string
date The date and time the call was connected (ISO 8601). string
session_data The session_data set in the /Dials/Connect request. object
connected_time The call’s duration in milliseconds. long
error NULL, unless an error occurs. This is an internal diagnostic error and may not be useful to the API developer. string
subaccount_id The Sub Account ID of the application the call belongs to. integer

Example Response

{
  "id": "142877@7875",
  "no": "+17145551212",
  "caller_id_no": "+15625551212",
  "connected_time": 0,
  "status": "completed",
  "detection": "live_person",
  "date": "2016-09-07T19:59:08.901Z",
  "session_data": {
    "name": "Bob",
    "age": 21
  },
  "error": null,
  "app_id": "aaaa-bbbb-cccc-dddd-eeee",
  "subaccount_id": 0
}

Response Codes

Status Description
200 Returns a Call object.
4xx & 5xx General Error Codes

List Call Logs

Returns a list of call logs which may be filtered by date, direction and connect time. A maximum of 1,000 logs can be returned. If more than 1,000 logs are found, is_truncated will equal true.

GET /History/Logs/Calls?{query_string}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
begin_date The date of the earliest log to retrieve. Inclusive. The default value is one hour before now. Expects ISO 8601 format. string (query) No
end_date The date of the most recent log to retrieve. Non-inclusive. The default value is NOW. Expects ISO 8601 format. string (query) No
direction Accepts: inbound, outbound. Omitting this parameter will return both. string (query) No
connect_time Returns logs with connect times (in seconds) greater than or equal to this amount. integer (query) No
type Accepts: voice, sms. Default is voice. string (query) No
service The name of the service that produced the log. Returns: programmable_voice, sip_trunking. Default returns all. string (query) No
caller_no The user’s phone number (far end) that interacted with the API. Default returns all. string (query) No
api_no The Voxology phone number (near end) that is provisioned to the API. Default returns all. string (query) No

Example Request

curl -X GET \
  'https://api.voxolo.gy/v1/History/Logs/Calls?begin_date=2016-09-19T18%3A00%3A00.000Z&end_date=2016-09-19T19%3A00%3A00.138Z&direction=inbound%7Coutbound&connect_time=0' \
  -H 'Cache-Control: no-cache' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

Property Description Type
begin_date The begin date of the search. ISO Date
end_date The end date of the search. ISO Date
logs An array of log objects. array
logs[i].id The ID of the log. string
logs[i].api_no The phone number provisioned to the API (E.164 format: +17145551212). string
logs[i].call_id The call ID of the requested call string
logs[i].parent_call_id When using the DIAL action, this is the call_id of the originating call. The value is null if there is no originating call. string
logs[i].caller_no The phone number of the caller (E.164 format: +17145551212). string
logs[i].initiated_by Indicates the origin of the call. Possible values include api for outbound Make Call requests, sip_user and sip for inbound calls from SIP Users and SIP Interface, pstn for basic inbound calls, dial and transfer for outbound DIAL and TRANSFER action calls. string
logs[i].external_id A user-defined ID for the call. string
logs[i].external_group_id A user-defined ID for a group of calls. string
logs[i].start_time The time the call started. ISO Date
logs[i].end_time The time the call ended. ISO Date
logs[i].app_id The ID of the application the log belongs to. integer
logs[i].subaccount_id The Sub Account ID of the application the log belongs to. integer
logs[i].type The type of call: voice or sms. string
logs[i].direction Specifies the direction of the call: inbound or outbound string
logs[i].hangup_end The end of the call that first hung up. Returns: api (near end) or caller (far end). string
logs[i].duration The length of the call in milliseconds. long
logs[i].status The call state. Codes: live-queued, live-ringing, live-in-progress, completed, busy, canceled, failed, no-answer. See the Call Status table for details on call status. string
logs[i].error Any error that occurred when making or receiving the call. string
logs[i].error_code An error code for any error that occurred while making or receiving a phone call. See Call Flow Loop errors for details. integer
logs[i].detection The likely “caller” on the far end. Codes: fax, live_person, voicemail, unknown. string
logs[i].connect_time_billed The multiplier of minutes billed. 1 = one minute billed. float
logs[i].connect_time_sec The number of seconds the call was connected. Used for billing purposes. integer
logs[i].origin_api The API the call interacted with. CallFlows, Dials_SMS. string
logs[i].text_message For SMS calls, this is the message sent to received. string
logs[i].config The CallFlows configuration at the time of this call. See POST /CallFlows/Callbacks for details. object
logs[i].sip Object describing the SIP related information of the call, if applicable. object
logs[i].sip.call_id The unique identifier of the call as reflected by SIP signaling. string
logs[i].sip.response_code The final SIP response code in the SIP dialog. integer
logs[i].charge.total The charge for this call or message. This value is populated after the call is completed and may not be available immediately. float
logs[i].service The name of the service that produced the log. Returns: programmable_voice, sip_trunking. string
logs[i].lrn The Location Routing Number (LRN) at the time of the call. string
logs[i].post_dial_delay Measurement of how long it takes for a calling party to hear a ringback tone after initiating a call in milliseconds. long
logs[i].stir_shaken_status A status indicating the STIR/SHAKEN attestation level assigned to the call; includes number validation on inbound calls. See the STIR SHAKEN Status table for details. string
logs[i].extension_dialed If a registered Extension was dialed on the call, the most recent extension dialed is stored in this variable. string
is_truncated Indicates if more logs are available than were returned in the response. boolean
next_block_uri A URI to be used in a subsequent request to retrieve the next block in a truncated set of logs. If is_truncated is false, the value is null. string

Example Response

{
  "logs": [
    {
      "id": "xxx-yyy-zzz",
      "app_id": "aaaa-bbbb-cccc-dddd-eeee",
      "subaccount_id": 0,
      "call_id": "123456@789",
      "parent_call_id": "123456@788",
      "caller_no": "+17145551212",
      "api_no": "+19495551212",
      "initiated_by": "pstn",
      "external_id":"external_id_123",
      "external_group_id":"group_id_123",
      "start_time": "2016-09-19T18:00:04.810Z",
      "end_time": "2016-09-19T18:00:18.985Z",
      "type": "voice",
      "direction": "inbound",
      "hangup_end": "api",
      "duration": 14712,
      "status": "completed",
      "detection": "live_person",
      "error": null,
      "connect_time_billed": 0.2,
      "connect_time_sec": 12,
      "origin_api": "CallFlows",
      "config": {
        "no": "+19495551212",
        "callback": {
          "method": "GET",
          "url": "http://s3.amazonaws.com/com.domain.www/actions.json",
          "content_type": "application/json"
        },
        "answer_on_ring": "1",
        "updated_on": "2019-01-29T16:24:21-08:00",
        "created_on": "2018-04-16T13:43:32-07:00"
      },
      "charge": {
        "total": 0.1
      },
      "service": "programmable_voice",
      "lrn": "+15555555555",
      "stir_shaken_status": "TN-Validation-Passed-A",
      "extension_dialed": null
    }
  ],
  "begin_date": "2016-09-19T17:00:35.966Z",
  "end_date": "2016-09-19T18:00:35.966Z",
  "is_truncated": false,
  "next_block_uri": null
}

Response Codes

Status Description
200 Returns an array of call logs.
4xx & 5xx General Error Codes

View Call Log

Returns the call log detail for any individual call based on the call ID.

GET  /History/Logs/Calls/{call_id}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
call_id A call ID. string (path) Yes

Example Request

curl -X GET \
  'https://api.voxolo.gy/v1/History/Logs/Calls/123345@6789' \
  -H 'Cache-Control: no-cache' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

Property Description Type
id The ID of the log. string
api_no The phone number provisioned to the API (E.164 format: +17145551212). string
call_id The call ID of the requested call string
parent_call_id When using the DIAL action, this is the call_id of the originating call. The value is null if there is no originating call. string
caller_no The phone number of the caller (E.164 format: +17145551212). string
initiated_by Indicates the origin of the call. Possible values include api for outbound Make Call requests, sip_user and sip for inbound calls from SIP Users and SIP Interface, pstn for basic inbound calls, dial and transfer for outbound DIAL and TRANSFER action calls. string
external_id A user-defined ID for the call. string
external_group_id A user-defined ID for a group of calls. string
start_time The time the call started. ISO Date
end_time The time the call ended. ISO Date
app_id The ID of the application the log belongs to. integer
subaccount_id The Sub Account ID of the application the log belongs to. integer
type The type of call: voice or sms. string
direction Specifies the direction of the call: inbound or outbound string
hangup_end The end of the call that first hung up. Returns: api (near end) or caller (far end). string
duration The length of the call in milliseconds. long
status The call state. Codes: live-queued, live-ringing, live-in-progress, completed, busy, canceled, failed, no-answer. See the Call Status table for details on call status. string
error Any error that occurred when making or receiving the call. string
error_code An error code for any error that occurred while making or receiving a phone call. See Call Flow Loop errors for details. integer
detection The likely “caller” on the far end. Codes: fax, live_person, voicemail, unknown. string
connect_time_billed The multiplier of minutes billed. 1 = one minute billed. float
connect_time_sec The number of seconds the call was connected. Used for billing purposes. integer
origin_api The API the call interacted with. CallFlows, Dials_SMS. string
text_message For SMS calls, this is the message sent to received. string
config The CallFlows configuration at the time of this call. See POST /CallFlows/Callbacks for details. object
sip Object describing the SIP related information of the call, if applicable. object
sip.call_id The unique identifier of the call as reflected by SIP signaling. string
sip.response_code The final SIP response code in the SIP dialog. integer
charge.total The charge for this call or message. This value is populated after the call is completed and may not be available immediately. float
service The name of the service that produced the log. Returns: programmable_voice, sip_trunking. string
lrn The Location Routing Number (LRN) at the time of the call. string
post_dial_delay Measurement of how long it takes for a calling party to hear a ringback tone after initiating a call in milliseconds. long
stir_shaken_status A status indicating the STIR/SHAKEN attestation level assigned to the call; includes number validation on inbound calls. See the STIR SHAKEN Status table for details. string
extension_dialed If a registered Extension was dialed on the call, the most recent extension dialed is stored in this variable. string

Example Response

{
  "id": "xxx-yyy-zzz",
  "app_id": "aaaa-bbbb-cccc-dddd-eeee",
  "subaccount_id": 0,
  "call_id": "145229@9461",
  "parent_call_id": "145229@9460",
  "caller_no": "+17145551212",
  "api_no": "+19495551212",
  "initiated_by": "pstn",
  "external_id":"external_id_123",
  "external_group_id":"group_id_123",
  "start_time": "2016-09-19T18:00:04.810Z",
  "end_time": "2016-09-19T18:00:18.985Z",
  "type": "voice",
  "direction": "inbound",
  "hangup_end": "api",
  "duration": 14712,
  "status": "completed",
  "detection": "live_person",
  "error": null,
  "connect_time_billed": 0.2,
  "connect_time_sec": 12,
  "origin_api": "CallFlows",
  "config": {
    "no": "+19495551212",
    "callback": {
      "method": "GET",
      "url": "http://s3.amazonaws.com/com.domain.www/actions.json",
      "content_type": "application/json"
    },
    "answer_on_ring": "1",
    "updated_on": "2019-01-29T16:24:21-08:00",
    "created_on": "2018-04-16T13:43:32-07:00"
  },
  "charge": {
    "total": 0.1
  },
  "service": "programmable_voice",
  "lrn": "+15555555555",
  "stir_shaken_status": "TN-Validation-Passed-A",
  "extension_dialed": null,
  "created_on": "2016-03-16T10:09:00.000Z",
  "updated_on": "2016-03-16T12:49:00.000Z"
}

Response Codes

Status Description
200 Returns a Call object.
4xx & 5xx General Error Codes

End Call

Deletes the specified call by ID.

In order to place a message before ending the call, see hangup.

DELETE /LiveCalls/{call_id}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
call_id A call ID. string (path) Yes

Example Request

curl -X DELETE \
  https://api.voxolo.gy/v1/LiveCalls/142877@7875 \
  -H 'Cache-Control: no-cache' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

No Response Body

Response Codes

Status Description
204 No content on success.
4xx & 5xx General Error Codes

Hang Up

Creates a request to end the call by ID.

Includes the option of leaving an exit message.

POST /LiveCalls/{call_id}/Actions/HangUp

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
call_id A call ID. string (path) Yes
message The message to play before ending the call. Accepts one or more strings of TTS, Audio URL, M4A, and/or DTMF (example: dtmf://1234). Default is no message. string/array (body) Yes

Example Request

curl -X POST \
  https://api.voxolo.gy/v1/LiveCalls/123456@7890/Actions/HangUp \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "message": [
      "Let me play you a song before you go.",
      "https://s3.amazonaws.com/com.voxology.music/classical/BusyStrings.mp3"
    ]
  }'

Response

No Response Body

Response Codes

Status Description
204 No content on success.
4xx & 5xx General Error Codes

Collect Digits

Creates a collect key press event in the specified call by ID.

An optional message can be played.

POST /LiveCalls/{call_id}/Actions/Collect

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
call_id A call ID. string (path) Yes
message The message to play before collection. Accepts one or more strings of TTS, Audio URL, M4A, and/or DTMF (example: dtmf://1234). Default is no message. string/array (body) No
callback The callback object. object (body) Yes
callback.url The url the key presses will be sent to. string (body) Yes
callback.method The method of the request. Accepts: POST, GET, PUT, DELETE. Defaults to POST. string (body) No
num_digits The maximum numbers of digits to accept. Defaults to 1. integer (body) No
finish_on_key The key that ends key press collection. Accepts: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, #, *. Defaults to #. string (body) No

Example Request

curl -X POST \
  https://api.voxolo.gy/v1/LiveCalls/123456@7890/Actions/Collect \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "message": "https://s3.amazonaws.com/com.voxology.music/classical/BusyStrings.mp3",
    "callback": {
      "url": "https://s3.amazonaws.com/",
      "method": "POST"
    },
    "num_digits": 10,
    "finish_on_key": "#",
    "timeout": 10
  }'

Response

No Response Body

Response Codes

Status Description
204 No content on success.
4xx & 5xx General Error Codes

Stop Actions

Stops currently running actions on a call by ID. For example, stopping currently playing audio.

POST /LiveCalls/{call_id}/Actions/Stop

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
call_id A call ID. string (path) Yes
actions A comma-separated list of actions. Defaults to AUDIO. string (body) No

Example Request

curl -X POST \
  https://api.voxolo.gy/v1/LiveCalls/123456@7890/Actions/Stop \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "actions": "AUDIO"
  }'

Response

No Response Body

Response Codes

Status Description
204 No content on success.
4xx & 5xx General Error Codes

Leave Voicemail

Leaves a voicemail for the specified call by ID. Initiates the voicemail recording type.

This method will attempt to wait for a beep before playing the message.

It allows the caller to transition to another call prior to ending the current call.

POST /LiveCalls/{call_id}/Actions/LeaveVoiceMail

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
call_id A call ID. string (path) Yes
message The voicemail message to leave. Accepts one or more strings of TTS, Audio URL, M4A, and/or DTMF (example: dtmf://1234). Default is no message. string/array (body) No

Example Request

curl -X POST \
  https://api.voxolo.gy/v1/LiveCalls/123456@7890/Actions/LeaveVoiceMail \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "message": "https://s3.amazonaws.com/com.voxology.music/classical/BusyStrings.mp3",
  }'

Response

No Response Body

Response Codes

Status Description
204 No content on success.
4xx & 5xx General Error Codes

Tell

Plays TTS, Audio Files, M4A, and/or DTMF tones to a specified caller by ID.

Only the specified caller will hear the messages. Allows developer to combine any or all message types in any order. This is most helpful when “stitching” together various audio files for highly personalized messages.

Supported voice files: MP3, OGG, M4A, and WAV.

POST /LiveCalls/{call_id}/Actions/Tell

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
call_id A call ID. string (path) Yes
message An array of TTS messages, url to audio files and/or DTMF tones. string/array (body) Yes

Example Request

curl -X POST \
  https://api.voxolo.gy/v1/LiveCalls/123@4567/Actions/Tell \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "messages": [
      "https://s3.amazonaws.com/com.voxology.music/classical/BusyStrings.mp3",
      "1234 dollars and 56 cents.",
      "dtmf://123#"
    ]
  }'

Response

No Response Body

Response Codes

Status Description
204 No content on success.
4xx & 5xx General Error Codes

Call Transfer

Transfers the specified call to the specified phone number or SIP endpoint by ID.

POST /LiveCalls/{call_id}/Actions/Transfer

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
call_id A call ID. string (path) Yes
message The message to play before the transfer. Accepts one or more strings of TTS, Audio URL, M4A, and/or DTMF (example: dtmf://1234). Default is no message. string/array (body) No
call The call object to connect. string (body) Yes
call.no The phone number or SIP destination to call. Phone numbers are in E.164 format (example: +19495551212). SIP destinations are formatted as abc123@sip.mypbx.com. string (body) Yes
call.caller_id_no The phone number that will appear as the Caller ID. Phone numbers are in E.164 format (example: +19495551212). Defaults to the number of the caller that dialed your inbound number (caller_no in your callbacks). string (body) Yes

Example Request

curl -X POST \
  https://api.voxolo.gy/v1/LiveCalls/123456@7890/Actions/Transfer \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "message": "https://s3.amazonaws.com/com.voxology.music/classical/BusyStrings.mp3",
    "call": {
      "no": "+17145551212",
      "caller_id_no": "+15625551212"
    }
  }'

Response

No Response Body

Response Codes

Status Description
204 No content on success.
4xx & 5xx General Error Codes

Inject Actions List

Injects an array of ACTIONS into live calls. All CallFlows callback response Actions are supported.

POST /LiveCalls/{call_id}/Actions

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
call_id A call ID. string Yes
actions An array of ACTIONS array (body) Yes

Example Request

[
  {
    "type": "SAY",
    "params": {
      "text": "Welcome to our conference.",
      "loop": 1
    }
  },
  {
    "type": "CONFERENCE",
    "params": {
      "name": "test-conf"
    }
  }
]

Response

No Response Body

Response Codes

Status Description
204 No content on success.
4xx & 5xx General Error Codes

Modify Session Data

Write/overwrite session_data on a live call by ID.

This new session data will not change the unfinished ACTIONS being executed in the current callback.

The body must be a plain JavaScript object. This object will completely replace the current session data.

POST /LiveCalls/{call_id}/Actions/SessionData

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
call_id A call ID. string (path) Yes
data Any valid JSON object up to 16k object Yes

Example Request

curl -X POST \
  https://api.voxolo.gy/v1/LiveCalls/123456@7890/Actions/SessionData \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "name": "Bob",
    "age": 25,
  }'

Response

No Response Body

Response Codes

Status Description
204 No content on success.
4xx & 5xx General Error Codes

Conferences

List Conferences

Returns the list of live conferences for this application.

GET /LiveCalls/Conferences

Authentication Type

API Key (Application-level)

Request

No Request Body

Example Request

curl -X GET \
  'https://api.voxolo.gy/v1/LiveCalls/Conferences' \
  -H 'Cache-Control: no-cache' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

Property Description Type
conferences Array of conferences. array
id The ID of the conference. string
name The name given to the conference. string
status The status of the conference: in-progress, on-hold. string
num_participants The number of participants currently in the conference. integer
participants An array of participants currently in the conference. array
participants[i].id The ID of the participant. This is different than the call ID. string
participants[i].call.id The ID of the caller. string
participants[i].call.no The phone number of the caller. string
participants[i].muted Is the participant on mute in this conference? boolean
participants[i].on_hold Is the participant on hold in this conference? boolean
participants[i].start_on_join The value of this conference parameter when the participant joined. boolean
participants[i].hold_on_join The value of this conference parameter when the participant joined. boolean
participants[i].end_on_exit The value of this conference parameter when the participant joined. boolean
participants[i].hold_on_exit The value of this conference parameter when the participant joined. boolean

Example Response

{
  "conferences": [
    {
      "id": "abc123",
      "name": "myConference",
      "status": "in-progress",
      "num_participants": 3,
      "participants": [
        {
          "id": "xyz987",
          "call": {
            "id": "123@456",
            "no": "+17145551212"
          },
          "muted": false,
          "on_hold": false,
          "start_on_join": false,
          "hold_on_join": false,
          "end_on_exit": false,
          "hold_on_exit": false
        },
        {
          "id": "xyz789",
          "call": {
            "id": "123@457",
            "no": "+17145551213"
          },
          "muted": false,
          "on_hold": false,
          "start_on_join": false,
          "hold_on_join": false,
          "end_on_exit": false,
          "hold_on_exit": false
        },
        {
          "id": "abc987",
          "call": {
            "id": "123@459",
            "no": "+17145551214"
          },
          "muted": false,
          "on_hold": false,
          "start_on_join": false,
          "hold_on_join": false,
          "end_on_exit": true,
          "hold_on_exit": false
        }
      ]
    }
  ]
}

Response Codes

Status Description
200 Returns an array of conferences.
4xx & 5xx General Error Codes
4xx & 5xx Conference Error Codes

View Conference Detail

Returns details about the specified conference.

GET /LiveCalls/Conferences/{conf_id}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
conf_id The conference ID. string (path) Yes

Example Request

curl -X GET \
  https://api.voxolo.gy/v1/LiveCalls/Conferences/abc123 \
  -H 'Cache-Control: no-cache' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

Property Description Type
id The ID of the conference. string
name The name given to the conference. string
status The status of the conference: in-progress, on-hold. string
num_participants The number of participants currently in the conference. integer
participants An array of participants currently in the conference. array
participants[i].id The ID of the participant. This is different than the call ID. string
participants[i].call.id The ID of the caller. string
participants[i].call.no The phone number of the caller. string
participants[i].muted Is the participant on mute in this conference? boolean
participants[i].on_hold Is the participant on hold in this conference? boolean
participants[i].start_on_join The value of this conference parameter when the participant joined. boolean
participants[i].hold_on_join The value of this conference parameter when the participant joined. boolean
participants[i].end_on_exit The value of this conference parameter when the participant joined. boolean
participants[i].hold_on_exit The value of this conference parameter when the participant joined. boolean

Example Response

{
  "id": "abc123",
  "name": "myConference",
  "status": "in-progress",
  "num_participants": 3,
  "participants": [
    {
      "id": "xyz987",
      "call": {
        "id": "123@456",
        "no": "+17145551212"
      },
      "muted": false,
      "on_hold": false,
      "start_on_join": false,
      "hold_on_join": false,
      "end_on_exit": false,
      "hold_on_exit": false
    },
    {
      "id": "xyz789",
      "call": {
        "id": "123@457",
        "no": "+17145551213"
      },
      "muted": false,
      "on_hold": false,
      "start_on_join": false,
      "hold_on_join": false,
      "end_on_exit": false,
      "hold_on_exit": false
    },
    {
      "id": "abc987",
      "call": {
        "id": "123@459",
        "no": "+17145551214"
      },
      "muted": false,
      "on_hold": false,
      "start_on_join": false,
      "hold_on_join": false,
      "end_on_exit": true,
      "hold_on_exit": false
    }
  ]
}

Response Codes

Status Description
200 Returns a conference object.
4xx & 5xx General Error Codes
4xx & 5xx Conference Error Codes

View Participant Detail

Returns information about the specified participant of the specified conference.

GET /LiveCalls/Conferences/{conf_id}/Participants/{part_id}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
conf_id The conference ID. string (path) Yes
part_id The participant ID. string (path) Yes

Example Request

curl -X GET \
  https://api.voxolo.gy/v1/LiveCalls/Conferences/abc123/Participants/xyz987 \
  -H 'Cache-Control: no-cache' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

Property Description Type
id The ID of the participant. This is different than the call ID. string
call.id The ID of the caller. string
call.no The phone number of the caller. string
muted Is the participant on mute in this conference? boolean
on_hold Is the participant on hold in this conference? boolean
start_on_join The value of this conference parameter when the participant joined. boolean
hold_on_join The value of this conference parameter when the participant joined. boolean
end_on_exit The value of this conference parameter when the participant joined. boolean
hold_on_exit The value of this conference parameter when the participant joined. boolean

Example Response

{
  "participants": [
    {
      "id": "xyz987",
      "call": {
        "id": "123@456",
        "no": "+17145551212"
      },
      "muted": false,
      "on_hold": false,
      "start_on_join": false,
      "hold_on_join": false,
      "end_on_exit": false,
      "hold_on_exit": false
    }
  ]
}

Response Codes

Status Description
200 Returns a Participant object.
4xx & 5xx General Error Codes
4xx & 5xx Conference Error Codes

Join Conference

Places a caller into the specified conference.

POST /LiveCalls/{call_id}/Actions/Conference/Join

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
call_id The call ID. string (path) Yes
conference_name The name of the conference. Conference name is scoped to the application. To avoid unwanted behavior, use unique conference names. Accepts: alpha-numeric, dashes, and underscores. string (body) Yes
message The message to play before joining the conference. Accepts one or more strings of TTS, Audio URL, M4A, and/or DTMF (example: dtmf://1234). Default is no message. string/array (body) No
mute_on_key The key combination to press to mute one’s self. Default is “1”. string (body) No
unmute_on_key The key combination to press to unmute one’s self. Default is “2”. string (body) No
exit_on_key The key combination to press to leave the conference. Default is “#”. string (body) No
max_participants The maximum number of participants allowed at one time. Join attempts that would exceed the max throw an error event. Default is Infinite. number (body) No
hold_audio The URL to the audio file to play when a participant is placed on hold. If omitted, our default hold music will be used. string (body) No

Example Request

curl -X POST \
  https://api.voxolo.gy/v1/LiveCalls/123456@7890/Actions/Conference/Join \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "conference_name": "my conference",
    "message": "https://s3.amazonaws.com/com.voxology.music/classical/BusyStrings.mp3",
    "mute_on_key": "1",
    "unmute_on_key": "2",
    "exit_on_key": "3",
    "max_participants": 50,
    "hold_audio": "https://myserver.com/conference-app/holdAudio.wav"
  }'

Response

No Response Body

Response Codes

Status Description
204 No content on success.
4xx & 5xx General Error Codes
4xx & 5xx Conference Error Codes

Join Conference to Whisper

Places a caller into the specified conference with the ability to listen to the conference, and talk to one target member in the conference.

POST /LiveCalls/{call_id}/Actions/Conference/JoinToWhisper

Authentication Type

API Key (Application-level)

REQUEST

Parameter Description Type Required
call_id The call ID of the caller joining to whisper. string(path) Yes
conference_name The name of the conference. Conference name is scoped to the application. To avoid unwanted behavior, use unique conference names. Accepts: alphanumeric, dashes, and underscores. string(body) Yes
message The message to play to the caller before joining the conference. Accepts one or more strings of TTS, Audio URL, M4A, and/or DTMF (example: dtmf://1234). Default is no message. string/array(body) No
mute_on_key The key combination to press to mute one’s self. Default is “1”. string(body) No
unmute_on_key The key combination to press to unmute one’s self. Default is “2”. string(body) No
exit_on_key The key combination to press to leave the conference. Default is “#”. string(body) No
target_call An object describing the target call. object Yes
target_call.id The ID of the caller being whispered to. string (body) Yes
target_call.message The message to play to the target before the listener joins. Accepts one or more strings of TTS, Audio URL, M4A, and/or DTMF (example: dtmf://1234). Default is no message. string/array(body) No

Example Request

curl -X POST \
  https://api.voxolo.gy/v1/LiveCalls/123456@7890/Actions/Conference/JoinToWhisper \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "conference_name": "CONFERENCE_NAME",
    "message": "You are joining a conference as a listener.",
    "target_call": {
      "id": "TARGET_CALLER_ID",
      "message": "A supervisor is now listening."
    },
    "mute_on_key": "1",
    "unmute_on_key": "2",
    "exit_on_key": "#"
  }'

Response

No Response Body

Response codes

Status Description
204 No content on success
4xx & 5xx General Error Codes
4xx & 5xx Conference Error Codes

Leave Conference

Forces the specified conference participant to leave a conference.

POST /LiveCalls/{call_id}/Actions/Conference/Leave

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
call_id The call ID. string (path) Yes
conference_name The name of the conference. string (body) Yes
message The message to play after leaving the conference. Accepts one or more strings of TTS, Audio URL, M4A, and/or DTMF (example: dtmf://1234). Default is no message. string/array (body) No

Example Request

curl -X POST \
  https://api.voxolo.gy/v1/LiveCalls/123456@7890/Actions/Conference/Leave \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "conference_name": "my conference",
    "message": "https://s3.amazonaws.com/com.voxology.music/classical/BusyStrings.mp3"
  }'

Response

No Response Body

Response Codes

Status Description
204 No content on success.
4xx & 5xx General Error Codes
4xx & 5xx Conference Error Codes

Mute Participant

Mutes the specified conference participant during a conference.

POST /LiveCalls/{call_id}/Actions/Conference/Mute

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
call_id The call ID. string (path) Yes
conference_name The name of the conference. string (body) Yes
message The message to play after leaving the conference. Accepts one or more strings of TTS, Audio URL, M4A, and/or DTMF (example: dtmf://1234). Default is no message. string/array (body) No

Example Request

curl -X POST \
  https://api.voxolo.gy/v1/LiveCalls/123456@7890/Actions/Conference/Mute \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "conference_name": "my conference",
    "message": "https://s3.amazonaws.com/com.voxology.music/classical/BusyStrings.mp3"
  }'

Response

No Response Body

Response Codes

Status Description
204 No content on success.
4xx & 5xx General Error Codes
4xx & 5xx Conference Error Codes

Unmute Participant

Unmutes the specified conference participant during a conference.

POST /LiveCalls/{call_id}/Actions/Conference/Unmute

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
call_id The call ID. string (path) Yes
conference_name The name of the conference. string (body) Yes
message The message to play after leaving the conference. Accepts one or more strings of TTS, Audio URL, M4A, and/or DTMF (example: dtmf://1234). Default is no message. string/array (body) No

Example Request

curl -X POST \
  https://api.voxolo.gy/v1/LiveCalls/123456@7890/Actions/Conference/Unmute \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "conference_name": "my conference",
    "message": "https://s3.amazonaws.com/com.voxology.music/classical/BusyStrings.mp3"
  }'

Response

No Response Body

Response Codes

Status Description
204 No content on success.
4xx & 5xx General Error Codes
4xx & 5xx Conference Error Codes

Hold Participant

Places the specified conference participant on hold.

POST /LiveCalls/{call_id}/Actions/Conference/Hold

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
call_id The call ID. string (path) Yes
conference_name The name of the conference. string (body) Yes
message The message to play after leaving the conference. Accepts one or more strings of TTS, Audio URL, M4A, and/or DTMF (example: dtmf://1234). Default is no message. string/array (body) No

Example Request

curl -X POST \
  https://api.voxolo.gy/v1/LiveCalls/123456@7890/Actions/Conference/Hold \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "conference_name": "my conference",
    "message": "https://s3.amazonaws.com/com.voxology.music/classical/BusyStrings.mp3"
  }'

Response

No Response Body

Response Codes

Status Description
204 No content on success.
4xx & 5xx General Error Codes
4xx & 5xx Conference Error Codes

Resume Participant

Remove the specified conference participant from hold.

POST /LiveCalls/{call_id}/Actions/Conference/Resume

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
call_id The call ID. string (path) Yes
conference_name The name of the conference. string (body) Yes
message The message to play after leaving the conference. Accepts one or more strings of TTS, Audio URL, M4A, and/or DTMF (example: dtmf://1234). Default is no message. string/array (body) No

Example Request

curl -X POST \
  https://api.voxolo.gy/v1/LiveCalls/123456@7890/Actions/Conference/Resume \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "conference_name": "my conference",
    "message": "https://s3.amazonaws.com/com.voxology.music/classical/BusyStrings.mp3"
  }'

Response

No Response Body

Response Codes

Status Description
204 No content on success.
4xx & 5xx General Error Codes
4xx & 5xx Conference Error Codes

Emergency Address

Validate Emergency Address

Validates an address for use as an Emergency Address. Enables you to validate an address to later be assigned as the Emergency Address for a phone number.

POST /ValidateEmergencyAddress

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
name Occupant’s name. string Yes
street_no Street number. string Yes
street Street name. string Yes
city City. string Yes
region State or region. string (2-digit state code) Yes
country Country. string (ISO Alpha-2) Yes
unit Unit or apartment number. string No
postal_code The postal code or ZIP code. string Yes

Example Request

curl -X POST \
  'https://api.voxolo.gy/v1/ValidateEmergencyAddress' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "name": "Jane Doe"
    "street_no": "4695",
    "street": "MacArthur Ct", 
    "city": "Newport Beach",
    "region": "CA",
    "country": "US",
    "unit": "123",
    "postal_code": "92660"
  }'

Response

Property Description Type
status The address validation status: ok, corrected, multiple, nomatch string
addresses A list of addresses (multiple if applicable) array
addresses[i].name Occupant’s name. string
addresses[i].street_no Street number. string
addresses[i].street Street name. string
addresses[i].city City. string
addresses[i].region State or region. string (2-digit state code)
addresses[i].country Country. string (ISO Alpha-2)
addresses[i].postal_code The postal code or ZIP code. string
addresses[i].unit Unit or apartment number. string

Example Response

{
  "status": "ok",
  "addresses": [
    {
     "name": "Jane Doe",
     "street_no": "4695",
     "street": "MacArthur Ct",
     "city": "Newport Beach",
     "region": "CA",
     "country": "US",
     "postal_code": "92660",
     "unit": "123"
    }
  ]
}

Response Codes

Status Description
200 Returns validation status and addresses array
4xx & 5xx General Error Codes

Update a number’s Emergency Address

Assigns your validated emergency address to a number. Phone number must be in E.164 format. Example: +17145551212.

PUT /EmergencyAddresses/{phone_number}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
phone_number E.164 formatted phone number. string (path) Yes
name Occupant’s name. string Yes
street_no Street number. string Yes
street Street name. string Yes
city City. string Yes
region State or region. string (2-digit state code) Yes
country Country. string (ISO Alpha-2) Yes
unit Unit or apartment number. string No
postal_code The postal code or ZIP code. string Yes

Example Request

curl -X POST \
  'https://api.voxolo.gy/v1/EmergencyAddresses/{phone_number}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "name": "Jane Doe"
    "street_no": "4695",
    "street": "MacArthur Ct", 
    "city": "Newport Beach",
    "region": "CA",
    "country": "US",
    "unit": "123",
    "postal_code": "92660"
  }'

Response

Property Description Type
name Occupant’s name. string
street_no Street number. string
street Street name. string
city City. string
region State or region. string (2-digit state code)
acountry Country. string (ISO Alpha-2)
postal_code The postal code or ZIP code. string
unit Unit or apartment number. string

Example Response

{
    "name": "Jane Doe",
    "street_no": "4695",
    "street": "MacArthur Ct",
    "city": "Newport Beach",
    "region": "CA",
    "country": "US",
    "postal_code": "92660",
    "unit": "123"
}

Response Codes

Status Description
200 A successful request returns the address object
4xx & 5xx General Error Codes

View Emergency Address

Returns an emergency address assigned to a specific phone number.

GET /EmergencyAddresses/{phone_number}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
phone_number E.164 formatted phone number. string (path) Yes

Example Request

curl -X GET \
  'https://api.voxolo.gy/v1/EmergencyAddresses/{phone_number}' \
  -H 'Cache-Control: no-cache' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

Property Description Type
name Occupant’s name. string
street_no Street number. string
street Street name. string
city City. string
region State or region. string (2-digit state code)
acountry Country. string (ISO Alpha-2)
postal_code The postal code or ZIP code. string
unit Unit or apartment number. string

Example Response

{
    "name": "Jane Doe",
    "street_no": "4695",
    "street": "MacArthur Ct",
    "city": "Newport Beach",
    "region": "CA",
    "country": "US",
    "postal_code": "92660",
    "unit": "123"
}

Response Codes

Status Description
200 A successful request returns the address object
4xx & 5xx General Error Codes

Delete Emergency Address

Deletes an emergency address from a phone number.

DELETE /EmergencyAddresses/{phone_number}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
phone_number E.164 formatted phone number. string (path) Yes

Example Request

curl -X DELETE \
  'https://api.voxolo.gy/v1/EmergencyAddresses/{phone_number}' \
  -H 'Cache-Control: no-cache' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

No Response Body

Response Codes

Status Description
204 No content on success.
4xx & 5xx General Error Codes

Extensions

Extensions are 1-6 digit numbers in the Programmable Voice API that contain details on how to connect calls to a specific destination, such as a phone number or SIP User. Extensions act as shortcuts that make intra-company dialing simpler or provide the building blocks for a PBX on your company’s main phone line.

Assign Callback Configurations to Extensions to control calls once an Extension is dialed. The REDIRECTEXTENSION Call Flow Action redirects a live call to use the Callback Configuration for the Extension provided.

List Extensions

Returns a list of Extensions on this application.

GET /Extensions

AUTHENTICATION TYPE

API Key (Application-level)

REQUEST

No Request Body

Example Request

curl -X GET \
  https://api.voxolo.gy/v1/Extensions \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

Property Description Type
extensions An array of Extensions objects. array
extensions[i].extension The alphanumeric Extension, limited to 6 characters. ex. 123 string
extensions[i].description The user-defined description for the Extension. string
extensions[i].created_on The date the Extension was created. ISO date string
extensions[i].updated_on The date the Extension was last updated. string
extensions[i].extension_data User-definable JSON object that is returned in callbacks. string

Example Response

{
    "extensions": [
        {
            "extension": "123",
            "description": "example extension one",
            "created_on": "2023-01-01T22:25:39.000Z",
            "updated_on": "2023-01-01T22:25:39.000Z",
            "extension_data": null
        },
        {
            "extension": "456",
            "description": "example extension two",
            "created_on": "2023-01-02T22:25:50.000Z",
            "updated_on": "2023-01-02T22:25:50.000Z",
            "extension_data": null
        }
    ]
}

Response Codes

Status Description
200 Returns array of extension objects
4xx & 5xx General Error Codes

View Extension

Returns the Extensions object for a specific Extension.

GET /Extensions/{extension}

AUTHENTICATION TYPE

API Key (Application-level)

REQUEST

No Request Body

Example Request

curl -X GET \
  https://api.voxolo.gy/v1/Extensions/624 \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

Property Description Type
extension The alphanumeric Extension, limited to 6 characters. ex. 123 string
description The user-defined description for the Extension. string
created_on The date the Extension was created. ISO date string
updated_on The date the Extension was last updated. string
extension_data User-definable JSON object that is returned in callbacks. string

Example Response

{
    {
        "extension": "123",
        "description": "example extension one",
        "created_on": "2023-01-01T22:25:39.000Z",
        "updated_on": "2023-01-01T22:25:39.000Z",
        "extension_data": null
    }
}

Response Codes

Status Description
200 Returns a specified extensions object
4xx & 5xx General Error Codes

Create Extension

Creates an Extension.

POST /Extensions

AUTHENTICATION TYPE

API Key (Application-level)

Request

Parameter Description Type Required
extension The alphanumeric Extension, limited to 6 characters. ex. 624 string Yes
description The user-defined description for the Extension. string No
extension_data User-definable JSON object that is returned in callbacks. string No

Example Request

curl -X POST \
  https://api.voxolo.gy/v1/Extensions \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "extension":"624",
    "description":"example extension one"
}'

Response

Property Description Type
extension The alphanumeric Extension, limited to 6 characters. ex. 624 string
description The user-defined description for the Extension. string
created_on The date the Extension was created. ISO date string
updated_on The date the Extension was last updated. string
extension_data User-definable JSON object that is returned in callbacks. string

Example Response

{
    {
        "extension": "624",
        "description": "example extension one",
        "created_on": "2023-01-01T22:25:39.000Z",
        "updated_on": "2023-01-01T22:25:39.000Z",
        "extension_data": null
    }
}

Response Codes

Status Description
200 Returns the created extensions object
4xx & 5xx General Error Codes

Updates Extension

Updates a specified Extension.

PUT /Extensions/{extension}

AUTHENTICATION TYPE

API Key (Application-level)

Request

Parameter Description Type Required
extension The Extension to be updated. string Yes (path)
description The user-defined description for the Extension. string No
extension_data User-definable JSON object that is returned in callbacks. string No

Example Request

curl -X PUT \
  https://api.voxolo.gy/v1/Extensions/624 \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "description":"updated description for extension one"
}'

Response

Property Description Type
extension The alphanumeric Extension, limited to 6 characters. ex. 624 string
description The user-defined description for the Extension. string
created_on The date the Extension was created. ISO date string
updated_on The date the Extension was last updated. string
extension_data User-definable JSON object that is returned in callbacks. string

Example Response

{
    {
        "extension": "624",
        "description": "updated description for extension one",
        "created_on": "2023-01-01T22:25:39.000Z",
        "updated_on": "2023-01-01T22:25:39.000Z",
        "extension_data": null
    }
}

Response Codes

Status Description
200 Returns the updated extension object.
4xx & 5xx General Error Codes

Delete Extension

Deletes the specified Extension.

DELETE /Extensions/{extension}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
extension The Extension to delete. string (path) Yes

Example Request

curl -X DELETE \
  https://api.voxolo.gy/v1/Extensions/624 \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

No Response Body

Response Codes

Status Description
204 No content on success.
4xx & 5xx General Error Codes

Integrations

Update AWS S3 Authentication

Updates the AWS S3 bucket configuration under the appropriate application based upon the API Key used to authenticate. All recordings made on this account will be saved to the S3 bucket.

PUT /Integrations/RecordingStorage/AWS

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
access_key Amazon IAM Access key. string Yes
security_key Amazon IAM secret access key associated with the access key. string Yes
s3 An object that describes the S3 bucket. object Yes
s3.region The region of the S3 bucket. string Yes
s3.bucket The name of the S3 bucket. string Yes

Example Request

curl -X PUT \
  'https://api.voxolo.gy/v1/Integrations/RecordingStorage/AWS' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "access_key": "YOUR_ACCESS_KEY",
    "security_key": "YOUR_SECURITY_KEY",
    "s3": {
      "region": "YOUR_S3_REGION",
      "bucket": "YOUR_BUCKET_NAME"
    }
  }'

Response

Property Description Type
access_key Amazon IAM Access key. string
security_key Amazon IAM secret access key associated with the access key. string
s3 An object that describes the S3 bucket. object
s3.region The region of the S3 bucket. string
s3.bucket The name of the S3 bucket. string

Example Response

{
  "access_key": "YOUR_ACCESS_KEY",
  "security_key": "YOUR_SECURITY_KEY",
  "s3": {
    "region": "YOUR_REGION_NAME",
    "bucket": "YOUR_BUCKET_NAME"
  }
}

Response Codes

Status Description
200 Success returns an AWS configuration object
4xx & 5xx General Error Codes

View AWS S3 Authentication

Returns information on the AWS S3 bucket configuration under the appropriate application based upon the API Key used to authenticate.

GET /Integrations/RecordingStorage/AWS

Authentication Type

API Key (Application-level)

Request

No Request Body

Example Request

curl -X GET \
   https://api.voxolo.gy/v1/Integrations/RecordingStorage/AWS \
  -H 'Cache-Control: no-cache' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

Property Description Type
access_key Amazon IAM access key. string
security_key Indicates if an Amazon IAM secret access key is associated with the AWS 3S credentials. boolean
s3 An object that describes the S3 bucket. object
s3.region The region of the S3 bucket. string
s3.bucket The name of the S3 bucket. string

Example Response

{
  "access_key": "YOUR_ACCESS_KEY",
  "security_key": true,
  "s3": {
    "region": "us-west-1",
    "bucket": "YOUR_BUCKET_NAME"
  }
}

Response codes

Status Description
200 Returns AWS S3 configuration object.
4xx & 5xx General Error Codes

Delete AWS S3 Authentication

Deletes the AWS S3 configurations of the the application based upon the API Key used to authenticate.

DELETE /Integrations/RecordingStorage/AWS

Authentication Type

API Key (Application-level)

Request

No Request Body

Example Request

curl -X DELETE \
  https://api.voxolo.gy/v1/Integrations/RecordingStorage/AWS \
  -H 'Cache-Control: no-cache' \
  -H 'X-API-Key: YOUR_API_TOKEN'

Response

Property Description Type
access_key Amazon IAM access key. null
security_key Indicates if an Amazon IAM secret access key is associated with the AWS 3S credentials. null
s3 An object that describes the S3 bucket. object
s3.region The region of the S3 bucket. null
s3.bucket The name of the S3 bucket. null

Example Response

{
  "access_key": null,
  "security_key": null,
  "s3": {
    "region": null,
    "bucket": null
  }
}

Response Codes

Status Description
200 Returns AWS S3 configuration object.
4xx & 5xx General Error Codes

Update Watson Authentication

Updates the IBM Watson credentials of the application based upon the API Key used to authenticate.

PUT /Integrations/TTS/Watson

Authentication Type

API Key (Application-level)

Request

Parameter Description Type
text_to_speech An object that describes the Watson credentials. object
text_to_speech.api_key Account Owner’s Watson API Key from their IBM Cloud Text To Speech account. string

Example Request

curl -X PUT \
  https://api.voxolo.gy/v1/Integrations/TTS/Watson \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "text_to_speech": {
      "api_key": "123123123_abcabcabc-xyzxyzxyz"
    }
  }'

Response

Property Description Type
text_to_speech An object that describes the Watson credentials. object
text_to_speech.api_key Account Owner’s Watson API Key from their IBM Cloud Text To Speech account. string

Example Response

{
  "text_to_speech": {
    "api_key": "123123123_abcabcabc-xyzxyzxyz"
  }
}

Response Codes

Status Description
200 Returns Watson credentials object.
4xx & 5xx General Error Codes

View Watson Authentication

Returns IBM Watson Credentials of the application based upon the API Key used to authenticate.

GET /Integrations/TTS/Watson

Authentication Type

API Key (Application-level)

Request

No Request Body

Example Request

curl -X GET \
  https://api.voxolo.gy/v1/Integrations/TTS/Watson \
  -H 'Cache-Control: no-cache' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

Property Description Type
text_to_speech An object that describes the Watson credentials. object
text_to_speech.api_key Account Owner’s Watson API Key from their IBM Cloud Text To Speech account. string

Example Response

{
  "text_to_speech": {
    "api_key": "123123123_abcabcabc-xyzxyzxyz"
  }
}

Response codes

Status Description
200 Returns Watson credential object.
4xx & 5xx General Error Codes

Delete Watson Authentication

Deletes the IBM Watson credentials of the application based upon the API Key used to authenticate.

DELETE /Integrations/TTS/Watson

Authentication Type

API Key (Application-level)

Request

No Request Body

Example Request

curl -X DELETE \
  https://api.voxolo.gy/v1/Integrations/TTS/Watson \
  -H 'Cache-Control: no-cache' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

No Response Body

Response codes

Status Description
200 Returns Watson credentials object.
4xx & 5xx General Error Codes

Messages

Send Message

Creates and sends an SMS or MMS message to a specified phone number.

POST /Messages

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
caller_no The destination phone number (far end) where the message will be sent. Phone numbers are in E.164 format (example: +19495551212). Not required if group_nos provided. string Conditional
group_nos A list of destination numbers where the message will be sent. Use this parameter in place of caller_no to send a Group MMS message to multiple recipients. array No
api_no The Voxology phone number (near end) that the message will be sent from. This phone number must be SMS or MMS capable and should have previously been provisioned and assigned to CallFlows. Phone numbers are in E.164 format (example: +17145551212) string Yes
text_message The text body of the message. A single SMS supports a maximum of 160 GSM-7 characters. Messages above 160 characters are split into 153-character parts with a maximum of 1600 total characters. Messages containing Unicode characters are limited to 70 characters per part. The number of message parts is indicated in the num_parts property in the message logs. string Yes
media_urls An array of URLs pointing to the media to include in an MMS message. The URLs must be publically accessible or the message will not send. array No
external_id A queryable name for the messages. string No
external_group_id A queryable name for a group of messages. string No
time_to_live The amount of time in milliseconds that a message can sit in a queue (to be sent) before being canceled. If set, minimum time to live is 1000 milliseconds. integer No
status_webhook An object containing information on the status webhook. object No
status_webhook.url The endpoint to which the status webhooks will be sent. Click here to see status webhooks. string No

Example Request

curl --X POST \
  https://api.voxolo.gy/v1/Messages \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Cache-Control: no-cache' \
  -d '{
    "api_no": "+19495551212",
    "caller_no": "+17145551212",
    "text_message": "sample message",
    "media_urls":[
      "https://yourPublicMediaURL.com"
    ],
    "external_id": "external ID",
    "external_group_id": "group ID",
    "status_webhook": {
      "url": "yourWebhookURL.com"
    }
  }'

Response

Property Description Type
api_no The Voxology phone number (near end) that the message will be sent from. This phone number must be SMS capable and should have previously been provisioned and assigned to CallFlows. Phone numbers are in E.164 format (example: +17145551212) string
caller_no The destination phone number (far end) where the message will be sent. Phone numbers are in E.164 format (example: +19495551212). string
group_nos A list of destination numbers where the message will be sent. Use this parameter in place of caller_no to send a Group MMS message to multiple recipients. array
text_message The text body of the message. A single SMS supports a maximum of 160 GSM-7 characters. Messages above 160 characters are split into 153-character parts with a maximum of 1600 total characters. Messages containing Unicode characters are limited to 70 characters per part. The number of message parts is indicated in the num_parts property in the message logs. string
media_urls An array of URLs pointing to the media included in an MMS message. array
external_id A queryable name for the messages. string
external_group_id A queryable name for a group of messages. string
time_to_live The amount of time that a message can sit in a queue (to be sent) before being canceled. integer
message_id The message ID of the outbound message. string
status The status of the message. Click here to see possible statuses. string
uri The URI for this resource, relative to https://api.voxolo.gy. string
status_webhook An object containing information on the status webhook. object
status_webhook.url The endpoint to which the status webhooks will be sent. Click here to see status webhooks. string

Example Response

{
  "api_no": "+19495551212",
  "caller_no": "+17145551212",
  "text_message": "sample message",
  "media_urls": ["https://yourPublicMediaURL.com"],
  "external_id": "external ID",
  "external_group_id": "group ID",
  "time_to_live": 1000,
  "message_id": "SMO:cc3a7cef-ffb2-4e1e-a083-64c86817deed",
  "status": "accepted",
  "uri": "/v1/Messages/SMO:cc3a7cef-ffb2-4e1e-a083-64c86817deed",
  "status_webhook": {
    "url": "yourWebhookURL.com"
  }
}

Response Codes

Status Description
200 Returns a message ID.
4xx & 5xx General Error Codes

Send Messages Batch

Creates and sends an SMS or MMS message to each specified phone number in an array of message objects.

POST /Messages/Batch

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
external_group_id A queryable name for a group of messages. The group ID will be applied to every message in the messages array. string No
time_to_live The amount of time in milliseconds that each message can sit in a queue (to be sent) before being canceled. If set, minimum time to live is 1000 milliseconds. integer No
messages An array of message objects to be sent with the request. Max of 100 messages per request. array Yes
messages[i].caller_no The destination phone number (far end) where the message will be sent. Phone numbers are in E.164 format (example: +19495551212). Not required if group_nos provided. string Conditional
messages[i].group_nos A list of destination numbers where the message will be sent. Use this parameter in place of caller_no to send a Group MMS message to multiple recipients. array No
messages[i].api_no The Voxology phone number (near end) that the message will be sent from. This phone number must be SMS or MMS capable and should have previously been provisioned and assigned to CallFlows. Phone numbers are in E.164 format (example: +17145551212) string Yes
messages[i].text_message The text body of the message. A single SMS supports a maximum of 160 GSM-7 characters. Messages above 160 characters are split into 153-character parts with a maximum of 1600 total characters. Messages containing Unicode characters are limited to 70 characters per part. The number of message parts is indicated in the num_parts property in the message logs. string Yes
messages[i].media_urls An array of URLs pointing to the media to include in an MMS message. The URLs must be publically accessible or the message will not send. array No
messages[i].external_id A queryable name for the messages. string No
messages[i].status_webhook An object containing information on the status webhook. object No
messages[i].status_webhook.url The endpoint to which the status webhooks will be sent. Click here to see status webhooks. string No

Example Request

curl --X POST \
  https://api.voxolo.gy/v1/Messages/Batch \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Cache-Control: no-cache' \
  -d '{
    "external_group_id": "group ID",
    "time_to_live":10000,
    "messages":[
      {
        "api_no": "+19495551212",
        "caller_no": "+17145551212",
        "text_message": "sample message",
        "media_urls":[
          "https://yourPublicMediaURL.com"
        ],
        "external_id": "external ID",
        "status_webhook": {
          "url": "yourWebhookURL.com"
        }
      },
      {
        "api_no": "+19495551212",
        "group_nos": ["+19495551313", "+19495551414"],
        "text_message": "different sample message",
        "media_urls":[
          "https://yourPublicMediaURL.com"
        ],
        "external_id": "external ID" two,
        "status_webhook": {
          "url": "yourWebhookURL.com"
        }
      }
    ]
  }'

Response

Property Description Type
messages[i].api_no The Voxology phone number (near end) that the message will be sent from. This phone number must be SMS capable and should have previously been provisioned and assigned to CallFlows. Phone numbers are in E.164 format (example: +17145551212) string
messages[i].caller_no The destination phone number (far end) were the message will be sent. Phone numbers are in E.164 format (example: +19495551212). string
messages[i].group_nos A list of destination numbers where the message will be sent. Use this parameter in place of caller_no to send a Group MMS message to multiple recipients. string
messages[i].text_message The text body of the message. A single SMS supports a maximum of 160 GSM-7 characters. Messages above 160 characters are split into 153-character parts with a maximum of 1600 total characters. Messages containing Unicode characters are limited to 70 characters per part. The number of message parts is indicated in the num_parts property in the message logs. string
messages[i].media_urls An array of URLs pointing to the media included in an MMS message. array
messages[i].external_id A queryable name for the messages. string
messages[i].external_group_id A queryable name for a group of messages. string
messages[i].time_to_live The amount of time that a message can sit in a queue (to be sent) before being canceled. string
messages[i].message_id The message ID of the outbound message. string
messages[i].status The status of the message. Click here to see possible statuses. string
messages[i].error A message indicating an error with this specific message. Null if no error. string
messages[i].uri The URI for this resource, relative to https://api.voxolo.gy. string
messages[i].status_webhook An object containing information on the status webhook. object
messages[i].status_webhook.url The endpoint to which the status webhooks will be sent. Click here to see status webhooks. string

Example Response

{
  "messages": [
    {
      "api_no": "+19495551212",
      "caller_no": "+17145551212",
      "text_message": "sample message",
      "media_urls": ["https://yourPublicMediaURL.com"],
      "external_id": "external ID",
      "external_group_id": "group ID",
      "time_to_live": 10000,
      "message_id": "SMO:cc3a7cef-ffb2-4e1e-a083-64c86817deed",
      "status": "accepted",
      "uri": "/v1/Messages/SMO:cc3a7cef-ffb2-4e1e-a083-64c86817deed",
      "status_webhook": {
        "url": "yourWebhookURL.com"
      }
    },
    {
      "api_no": "+19495551212",
      "group_nos": ["+19495551313", "+19495551414"],
      "text_message": "different sample message",
      "media_urls": ["https://yourPublicMediaURL.com"],
      "external_id": "external ID two",
      "external_group_id": "group ID",
      "time_to_live": 10000,
      "message_id": "SMO:7a8612d5-30ca-4cbd-ac54-215aaff900f0",
      "status": "accepted",
      "uri": "/v1/Messages/SMO:7a8612d5-30ca-4cbd-ac54-215aaff900f0",
      "status_webhook": {
        "url": "yourWebhookURL.com"
      }
    }
  ]
}

Response Codes

Status Description
200 Returns a message ID for each message object in the messages array.
4xx & 5xx General Error Codes

List Messages

Returns a list of messages which may be filtered by date, phone numbers, direction, external ID and external group ID. A maximum of 1,000 logs can be returned. If more than 1,000 logs are found, is_truncated will equal true.

GET /Messages?{query_string}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
caller_no The user’s phone number (far end) that interacted with the API. string (query) No
api_no The Voxology phone number (near end) that is provisioned to the API. string (query) No
direction Accepts: inbound, outbound. Omitting this parameter will return both. string (query) No
begin_date The date of the earliest log to retrieve. Inclusive. The default value is one hour before now. Expects ISO 8601 format. string (query) No
end_date The date of the most recent log to retrieve. Non-inclusive. The default value is NOW. Expects ISO 8601 format. string (query) No
status Accepts: queued, sent, failed, delivered, undelivered, and received. See the Message Status table for details on messages. Use a comma separated list to search on multiple values. string No
external_id A queryable name for the messages. Only applicable to outbound messages. string (query) No
external_group_id A queryable name for a group of messages. Only applicable to outbound messages. string (query) No
is_truncated Indicates whether or not the list of messages are truncated. boolean No

Example Request

curl --X GET \
  https://api.voxolo.gy/v1/Messages?begin_date=2019-03-04T17:34:39.870Z&end_date=2019-03-04T18:43:24.341Z&status=sent,received,queued \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Cache-Control: no-cache'

Response

Property Description Type
begin_date The begin date of the search. ISO Date
end_date The end date of the search. ISO Date
messages An array of message objects. array
messages[i].message_id The unique message ID of the requested message. string
messages[i].created_on The date/time the message was first seen on the message gateway (outbound) or the date/time the message was received (inbound). ISO Date
messages[i].app_id The Application ID of the message. string
messages[i].subaccount_id The Sub Account ID of the message. integer
messages[i].caller_no The user’s phone number (far end) that interacted with the API (E.164 format: +17145551212). string
messages[i].group_nos A list of phone numbers included in a Group MMS message, excluding the api_no. For outbound, group_nos lists all recipients of the message. For inbound, groups_nos also includes the sender. (E.164 format: +17145551212). string
messages[i].api_no The Voxology phone number (near end) that is provisioned to the API. (E.164 format: +17145551212). string
messages[i].type The type of message. Returns: sms. string
messages[i].direction Specifies the direction of the message: inbound or outbound string
messages[i].status The status of the message. Returns: accepted, queued, sending, sent, failed, delivered, undelivered, receiving, or received. See the Message Status table for details on messages. string
messages[i].error_code The error code, if any, associated with your message. If your message status is failed or undelivered, the error_code can give you more information about the failure. The value will be null if the message was delivered successfully. integer
messages[i].error The human readable description of the error_code above. string
messages[i].text_message The text body of the message. Up to 1600 characters. string
messages[i].media_urls An array of URLs pointing to the media included in an MMS message. string
messages[i].media_urls[i].content_type The file type of the provided media. string
messages[i].media_urls[i].url The url pointing to the media provided in the MMS message. string
messages[i].external_id A queryable name for the messages. Will always be null for inbound messages. string
messages[i].external_group_id A queryable name for a group of messages. Will always be null for inbound messages. string
messages[i].num_parts The number of parts that make up the message. For SMS, if the text_message body is too large to be sent as a single message, it will be segmented into multiple parts and charged accordingly. For outbound Group MMS, num_parts is equal to the number of recipients. integer
messages[i].charge An object containing a list of charges for the message. object
messages[i].charge.total The charge for this message. This value is populated after the message is completed and may not be available immediately. float
messages[i].time_to_live The amount of time that a message can sit in a queue (to be sent) before being canceled. Will always be null for inbound messages. integer
messages[i].uri The URI for this resource, relative to https://api.voxolo.gy. string
messages[i].config The CallFlows configuration object of the phone number. Will always be null for outbound messages. object
messages[i].service The name of the service. Returns: programmable_messaging. string
messages[i].status_webhook An object containing the status webhook configuration. Will always be null for inbound messages. object
messages[i].status_webhook.url The endpoint to which the status webhooks will be sent. string

Example Response

{
  "messages": [
    {
      "message_id": "SMO:f670fe02-2d46-4645-8937-3f7bae1cedb9",
      "created_on": "2019-03-04T18:12:19.000Z",
      "app_id": "aaaa-bbbb-cccc-dddd-eeee",
      "subaccount_id": 0,
      "caller_no": "+19495551212",
      "group_nos": null,
      "api_no": "+17145551212",
      "type": "sms",
      "direction": "outbound",
      "status": "sent",
      "error": null,
      "error_code": null,
      "text_message": "example message",
      "external_id": "extern_id",
      "external_group_id": "group_id",
      "num_parts": 1,
      "charge": {
        "total": 0.01
      },
      "time_to_live": null,
      "uri": "/v1/Messages/SMO:f670fe02-2d46-4645-8937-3f7bae1cedb9",
      "config": null,
      "service": "programmable_messaging",
      "status_webhook": {
        "url": "yourEndpoint.com/sms-outbound-webhook-endpoint"
      }
    },
    {
      "message_id": "SMO:f670fe02-2d46-4645-8937-3f7bae1cedb9",
      "created_on": "2019-03-04T18:12:19.000Z",
      "app_id": "aaaa-bbbb-cccc-dddd-eeee",
      "subaccount_id": 0,
      "caller_no": null,
      "group_nos": ["+19495551212", "+19495551313"],
      "api_no": "+17145551212",
      "type": "mms",
      "direction": "outbound",
      "status": "sent",
      "error": null,
      "error_code": null,
      "text_message": "example mms message",
      "media_urls": [
        {
          "content_type": "image/jpeg",
          "url": "https://yourPublicMediaURL.com"
        }
      ],
      "external_id": "extern_id",
      "external_group_id": "group_id",
      "num_parts": 1,
      "charge": {
        "total": 0.01
      },
      "time_to_live": null,
      "uri": "/v1/Messages/SMO:f670fe02-2d46-4645-8937-3f7bae1cedb9",
      "config": null,
      "service": "programmable_messaging",
      "status_webhook": {
        "url": "yourEndpoint.com/sms-outbound-webhook-endpoint"
      }
    },
    {
      "message_id": "SMI:f670fe02-2d46-4645-8937-3f7bae1cedb9",
      "created_on": "2019-03-04T18:12:19.682Z",
      "app_id": "aaaa-bbbb-cccc-dddd-eeee",
      "subaccount_id": 0,
      "caller_no": "+17145551212",
      "group_nos": null,
      "api_no": "+19495551212",
      "type": "sms",
      "direction": "inbound",
      "status": "received",
      "error": null,
      "error_code": null,
      "text_message": "example message",
      "external_id": null,
      "external_group_id": null,
      "num_parts": null,
      "charge": {
        "total": 0.005
      },
      "time_to_live": null,
      "uri": "/v1/Messages/SMI:f670fe02-2d46-4645-8937-3f7bae1cedb9",
      "config": {
        "no": "+19495551212",
        "callback": {
          "method": "POST",
          "url": "yourEndpoint.com/callflow-inbound-endpoint",
          "content_type": "application/json"
        },
        "callback_sms": {
          "method": "POST",
          "url": "yourEndpoint.com/sms-inbound-endpoint",
          "content_type": "application/json"
        },
        "callback_sms_failover": {
          "method": "POST",
          "url": "yourEndpoint.com/sms-inbound-failover-endpoint",
          "content_type": "application/json"
        },
        "answer_on_ring": "1",
        "updated_on": "2019-01-29T16:24:21.000Z",
        "created_on": "2018-04-16T13:43:32.000Z"
      },
      "service": "programmable_messaging",
      "status_webhook": null
    }
  ],
  "begin_date": "2019-03-04T17:34:39.870Z",
  "end_date": "2019-03-04T18:52:31.257Z",
  "is_truncated": false
}

Response Codes

Status Description
200 Returns an array of messages.
4xx & 5xx General Error Codes

View Message

Returns the message details on an individual message based on the message_id.

GET /Messages/{message_id}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
message_id The message ID of the requested message. string (path) Yes

Example Request

curl --X GET \
  https://api.voxolo.gy/v1/Messages/SMO:f670fe02-2d46-4645-8937-3f7bae1cedb9 \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Cache-Control: no-cache'

Response

Property Description Type
message_id The unique message ID of the requested message. string
created_on The date/time the message was first seen on the message gateway (outbound), or the date/time the message was received (inbound). ISO Date
app_id The Application ID of the message. string
subaccount_id The Sub Account ID of the message. integer
caller_no The user’s phone number (far end) that interacted with the API (E.164 format: +17145551212). string
group_nos A list of phone numbers included in a Group MMS message, excluding the api_no. For outbound, group_nos lists all recipients of the message. For inbound, groups_nos also includes the sender. (E.164 format: +17145551212). array
api_no The Voxology phone number (near end) that is provisioned to the API (E.164 format: +17145551212). string
type The type of message. Returns: sms. string
direction Specifies the direction of the message: inbound or outbound. string
status The status of this message. Returns: accepted, queued, sending, sent, failed, delivered, undelivered, receiving, or received. See the Message Status table for details on messages. string
error_code The error code, if any, associated with the message. If your message status is failed or undelivered, the error_code can give you more information about the failure. The value will be null if the message was delivered successfully. integer
error The human readable description of the error_code above. string
text_message The text body of the message. Up to 1600 characters string
media_urls An array of URLs pointing to the media included in an MMS message. array
media_urls[i].content_type The file type of the provided media. string
media_urls[i].url The URL pointing to the media provided in the MMS message. string
external_id A queryable name for the messages. Will always be null for inbound messages. string
external_group_id A queryable name for a group of messages. Will always be null for inbound messages. string
num_parts The number of parts that make up the message. If the text_message body is too large to be sent as a single message, it will be segmented into multiple parts and charged accordingly. Will always be null for inbound messages. integer
charge An object containing a list of charges for the message. object
charge.total The charge for this message. This value is populated after the message is completed and may not be available immediately. float
time_to_live The amount of time that a message can sit in a queue (to be sent) before being canceled. Will always be null for inbound messages. integer
uri The URI for this resource, relative to https://api.voxolo.gy. string
config The CallFlows configuration object of the phone number. Will always be null for outbound messages. object
service The name of the service. Returns: programmable_messaging. string
status_webhook An object containing information on the status webhook. Will always be null for inbound messages. object
status_webhook.url The endpoint to which the status webhooks will be sent. Will always be null for inbound messages. string

Example Response // Inbound

{
  "service": "programmable_messaging",
  "type": "sms",
  "app_id": "aaaa-bbbb-cccc-dddd-eeee",
  "subaccount_id": 0,
  "message_id": "SMI:2d784af7-1410-41bd-9e89-f978082506c3",
  "created_on": "2019-03-04T18:12:19.682Z",
  "caller_no": "+17145551212",
  "group_nos": null,
  "api_no": "+19495551212",
  "direction": "inbound",
  "status": "received",
  "error": null,
  "error_code": null,
  "text_message": "example message",
  "external_id": null,
  "external_group_id": null,
  "num_parts": null,
  "time_to_live": null,
  "uri": "/v1/Messages/SMI:2d784af7-1410-41bd-9e89-f978082506c3",
  "charge": {
    "total": 0.005
  },
  "config": {
    "no": "+19495551212",
    "callback": {
      "method": "POST",
      "url": "yourEndpoint.com/callflow-inbound-endpoint",
      "content_type": "application/json"
    },
    "callback_sms": {
      "method": "POST",
      "url": "yourEndpoint.com/sms-inbound-endpoint",
      "content_type": "application/json"
    },
    "callback_sms_failover": {
      "method": "POST",
      "url": "yourEndpoint.com/sms-inbound-failover-endpoint",
      "content_type": "application/json"
    },
    "answer_on_ring": "1",
    "updated_on": "2019-01-29T16:24:21.000Z",
    "created_on": "2018-04-16T13:43:32.000Z"
  },
  "status_webhook": null
}

Example Response // Outbound

{
  "service": "programmable_messaging",
  "type": "mms",
  "app_id": "aaaa-bbbb-cccc-dddd-eeee",
  "subaccount_id": 0,
  "message_id": "SMO:cb3c8770-c321-4004-b60c-b6db9cdd6ad6",
  "created_on": "2019-03-04T18:12:19.000Z",
  "caller_no": "+19495551212",
  "group_nos": null,
  "api_no": "+17145551212",
  "direction": "outbound",
  "status": "sent",
  "text_message": "example message",
  "media_urls": [
    {
      "content_type": "image/jpeg",
      "url": "https://yourPublicMediaURL.com"
    }
  ],
  "external_id": "extern_id",
  "external_group_id": "group_id",
  "num_parts": 1,
  "charge": {
    "total": 0.01
  },
  "time_to_live": null,
  "uri": "/v1/Messages/SMO:cb3c8770-c321-4004-b60c-b6db9cdd6ad6",
  "config": null,
  "error": null,
  "error_code": null,
  "status_webhook": {
    "url": "yourEndpoint.com/sms-outbound-webhook-endpoint"
  }
}

Response Codes

Status Description
200 Returns a message object. -
4xx & 5xx General Error Codes

Messaging Registration

List 10DLC Brands

Returns a list of 10DLC Brands on this application. The list view returns only a subset of Brand information, see the View 10DLC Brand Details method for a complete view. 

GET /10DLCRegistration/Brands

AUTHENTICATION TYPE

API Key (Application-level)

REQUEST

No Request Body

Example Request

curl -X GET \
  https://api.voxolo.gy/v1/10DLCRegistration/Brands \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

Property Description Type
brands An array of Brand objects. array
brands[i].brand_id The unique ID for the Brand assigned by The Campaign Registry. string
brands[i].status The brand’s status with The Campaign Registry. Includes: VERIFIED, UNVERIFIED, VETTED_VERIFIED, SELF_DECLARED string
brands[i].doing_business_as The brand/marketing name of the company. string
brands[i].entity_type The type of business associated with this brand. string
brands[i].trust_score A score from 0-100 assigned by an external vetting provider. Determines throughput and volume levels with the Mobile Network Operators. integer
brands[i].created_on The date the Brand was created (ISO 8601). string
brands[i].updated_on The date the Brand was last updated (ISO 8601). string

Example Response

{
  "brands": [
    {
      "brand_id": "BX0001",
      "status": "VETTED_VERIFIED",
      "doing_business_as": "SMS Company",
      "trust_score": 100,
      "created_on": "2023-08-01T17:21:35.207Z",
      "updated_on": "2023-08-02T17:21:35.207Z"
    },
    {
      "brand_id": "BX0002",
      "status": "VETTED_VERIFIED",
      "doing_business_as": "Phone Company",
      "trust_score": 50,
      "created_on": "2023-08-03T17:21:35.207Z",
      "updated_on": "2023-08-04T17:21:35.207Z"
    }
  ]
}

Response Codes

Status Description
200 Returns array of Brand objects
4xx & 5xx General Error Codes

View 10DLC Brand Details

Returns a complete, detailed view of a specified 10DLC Brand on this application by its Campaign Registry ID.

GET /10DLCRegistration/Brands/{brand_id}

AUTHENTICATION TYPE

API Key (Application-level)

REQUEST

Parameter Description Type Required
brand_id The unique ID for the Brand assigned by The Campaign Registry. string (path) Yes

Example Request

curl -X GET \
  https://api.voxolo.gy/v1/10DLCRegistration/Brands/BX0001 \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

Property Description Type
brand_id The unique ID for the Brand assigned by The Campaign Registry. string
status The brands status with The Campaign Registry. Includes: VERIFIED, UNVERIFIED, VETTED_VERIFIED, SELF_DECLARED string
entity_name Legal name of the business associated with this brand. string
doing_business_as The brand/marketing name of the company string
entity_type The type of business associated with this brand. string
tax_id_issuing_country Country where the business is located and registered for tax purposes. Two-letter ISO-2 code. string
tax_id Legal Tax ID of the business issued by their country’s tax authority. In the U.S. this is the Employer Identification Number assigned by the IRS. string
firstname First name of the authorized point of the contact for the business. string
lastname Last name of the authoritzed point of the contact for the business. string
phone_no Support phone number used to contact the business. string
email Support email address used to contact the business. string
address Street Name and Number of the business address. string
city City of the business address. string
region State of Province of the business address. string
postal_code Postal or Zip code of the business address. string
country Country of the business address. Two-letter, ISO-2 code. string
stock_symbol Stock symbol, or ticker, used to identify the business on a stock exchange. string
stock_exchange The exchange code of the stock exchange the business is listed on. E.g. NASDAQ, NYSE string
website Url of the website or online presence of the business. string
vertical Segment or industry the business operates in. string
alternative_business_id Alternate business identification such as DUNS, GIIN or LEI number. string
alternative_business_id_type Type of alternate business ID. string
brand_relationship The nature of the relationship between your company and the Brand being registered. string
trust_score A score from 0-100 assigned by an external vetting provider. Determines throughput and volume levels with the Mobile Network Operators. integer
external_vetting_records An array of imported and/or ordered external vetting records. See our External Vetting methods for more details on external vetting records. array
created_on The date the Brand was created (ISO 8601). string
updated_on The date the Brand was last updated (ISO 8601). string

Example Response

{
    "brand_id": "BX0001",
    "status": "VETTED_VERIFIED",
    "entity_name": "Business Company",
    "doing_business_as": "SMS Company",
    "entity_type": "private_profit",
    "tax_id_issuing_country": "US",
    "tax_id": "0000000001",
    "firstname": "George",
    "lastname": "Washington",
    "phone_no": "+15551234567",
    "email": "support@business.com",
    "address": "123 Main St",
    "city": "New York",
    "region": "New York",
    "postal_code": "00001",
    "country": "US",
    "stock_symbol": "",
    "stock_exchange": "",
    "website": "https://www.voxolo.gy",
    "vertical": "technology",
    "alternative_business_id": "00001",
    "alternative_business_id_type": "DUNS",
    "brand_relationship": "basic_account",
    "trust_score":100,
    "external_vetting_records": [],
    "created_on": "2023-08-03T17:21:35.207Z",
    "updated_on": "2023-08-04T17:21:35.207Z"
}

Response Codes

Status Description
200 Returns a Brand object.
4xx & 5xx General Error Codes

Create 10DLC Brand

Creates a 10DLC Brand.

POST /10DLCRegistration/Brands

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
entity_name Legal name of the business associated with this brand. string Yes
doing_business_as The brand/marketing name of the company. Can be the same as the legal name. string Yes
entity_type The type of business associated with this brand. Accepts: private_profit, public_profit, non_profit, government, sole_proprietor. See our Intro to 10DLC for descriptions of each type. string Yes
tax_id_issuing_country Country where the business is located and registered for tax purposes. Two-letter ISO-2 code. string Yes
tax_id Legal Tax ID of the business issued by their country’s tax authority. In the U.S. this is the Employer Identification Number assigned by the IRS. string Yes
firstname First name of the authorized point of the contact for the business. string Conditional
lastname Last name of the authoritzed point of the contact for the business. string Conditional
phone_no Support phone number used to contact the business. string Yes
email Support email address used to contact the business. string Yes
address Street Name and Number of the business address. For best results with Brand vetting, use the same address associated with the business’s Tax ID/EIN. string Yes
city City of the business address. string Yes
region State of Province of the business address. string Yes
postal_code Postal or Zip code of the business address. string Yes
country Country where the business is located and registered for tax purposes. Two-letter ISO-2 code. string Yes
stock_symbol Stock symbol, or ticker, used to identify the business on a stock exchange. string Conditional
stock_exchange The exchange code of the stock exchange the business is listed on. E.g. NASDAQ, NYSE string Conditional
website Url of the website or online presence of the business. string Yes
vertical Segment or industry the business operates in. Accepts: professional, real_estate, healthcare, human_resources, energy, entertainment, retail, transportation, agriculture, insurance, postal, education, hospitality, financial, political, gambling, legal, construction, ngo, manufacturing, government, technology, communication string Yes
alternative_business_id Alternate business identification such as DUNS, GIIN or LEI number. string No
alternative_business_id_type Type of alternate business ID. Accepts: NONE, DUNS, GIIN, LEI string No
brand_relationship The nature of the relationship between the Campaign Service Provider (CSP) and the Brand being registered. If you are using Voxology as your CSP, this field is read-only. Accepts: basic_account, small_account, medium_account, large_account, key_account. See our Intro to 10DLC for relationship descriptions. string Yes

Example Request 

curl -X POST \
  https://api.voxolo.gy/v1/10DLCRegistration/Brands \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "entity_name": "Business Company",
    "doing_business_as": "SMS Company",
    "entity_type": "private_profit",
    "tax_id_issuing_country": "US",
    "tax_id": "0000000001",
    "firstname": "George",
    "lastname": "Washington",
    "phone_no": "+15551234567",
    "email": "support@business.com",
    "address": "123 Main St",
    "city": "New York",
    "region": "NY",
    "postal_code": "00001",
    "country": "US",
    "stock_symbol": "",
    "stock_exchange": "",
    "website": "https://www.voxolo.gy",
    "vertical": "technology",
    "alternative_business_id": "00001",
    "alternative_business_id_type": "DUNS",
    "brand_relationship": "basic_account"
    }'

Response

Property Description Type
brand_id The unique ID for the Brand assigned by The Campaign Registry. string
status The brand’s status with The Campaign Registry. string
entity_name Legal name of the business associated with this brand. string
doing_business_as The brand/marketing name of the company. string
entity_type The type of business associated with this brand. string
tax_id_issuing_country Two letter, ISO-2 country code where the business is located and registered for tax purposes. string
tax_id Legal Tax ID of the business issued by their country’s tax authority. In the U.S. this is the Employer Identification Number assigned by the IRS. string
firstname First name of the authorized point of the contact for the business. string
lastname Last name of the authoritzed point of the contact for the business. string
phone_no Support phone number used to contact the business. string
email Support email address used to contact the business. string
address Street Name and Number of the business address. string
city City of the business address. string
region State of Province of the business address. string
postal_code Postal or Zip code of the business address. string
country Country of the business address. Two-letter, ISO-2 code. string
stock_symbol Stock symbol, or ticker, used to identify the business on a stock exchange. string
stock_exchange The exchange code of the stock exchange the business is listed on. E.g. NASDAQ, NYSE string
website Url of the website or online presence of the business. string
vertical Segment or industry the business operates in. string
alternative_business_id Alternate business identification such as DUNS, GIIN or LEI number. string
alternative_business_id_type Type of alternate business ID. string
brand_relationship The nature of the relationship between your company and the Brand being registered. string
trust_score A score from 0-100 assigned by an external vetting provider. Determines throughput and volume levels with the Mobile Network Operators. integer
external_vetting_records An array of imported and/or ordered external vetting records. See our External Vetting methods for more details on external vetting records. array
created_on The date the Brand was created (ISO 8601). string
updated_on The date the Brand was last updated (ISO 8601). string

Example Response

{
    "brand_id": "BX0001",
    "status": "UNVERIFIED",
    "entity_name": "Business Company",
    "doing_business_as": "SMS Company",
    "entity_type": "private_profit",
    "tax_id_issuing_country": "US",
    "tax_id": "0000000001",
    "firstname": "George",
    "lastname": "Washington",
    "phone_no": "+15551234567",
    "email": "support@business.com",
    "address": "123 Main St",
    "city": "New York",
    "region": "New York",
    "postal_code": "00001",
    "country": "US",
    "stock_symbol": "",
    "stock_exchange": "",
    "website": "https://www.voxolo.gy",
    "vertical": "technology",
    "alternative_business_id": "00001",
    "alternative_business_id_type": "DUNS",
    "brand_relationship": "basic_account",
    "trust_score":100,
    "external_vetting_records": [],
    "created_on": "2023-08-03T17:21:35.207Z",
    "updated_on": "2023-08-04T17:21:35.207Z"
}

Response Codes

Status Description
200 Returns a Brand object.
4xx & 5xx General Error Codes

Update 10DLC Brand

Updates a 10DLC Brand.

PUT /10DLCRegistration/Brands/{brand_id}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
brand_id The ID of the 10DLC Brand. string (path) Yes
entity_name Legal name of the business associated with this brand. string Yes
doing_business_as The brand/marketing name of the company, if different than the legal name. string Yes
entity_type The type of business associated with this brand. Accepts: private_profit, public_profit, non_profit, government, sole_proprietor. See our Intro to 10DLC for descriptions of each type. string Yes
tax_id_issuing_country Country where the business is located and registered for tax purposes. Two-letter ISO-2 code. string Yes
tax_id Legal Tax ID of the business issued by their country’s tax authority. In the U.S. this is the Employer Identification Number assigned by the IRS. string Yes
firstname First name of the authorized point of the contact for the business. string Conditional
lastname Last name of the authoritzed point of the contact for the business. string Conditional
phone_no Support phone number used to contact the business. string Yes
email Support email address used to contact the business. string Yes
address Street Name and Number of the business address. For best results with Brand vetting, use the same address associated with the business’s Tax ID/EIN. string Yes
city City of the business address. string Yes
region State of Province of the business address. string Yes
postal_code Postal or Zip code of the business address. string Yes
country Country of the business address. Two-letter, ISO-2 code. string Yes
stock_symbol Stock symbol, or ticker, used to identify the business on a stock exchange. string Conditional
stock_exchange The exchange code of the stock exchange the business is listed on. E.g. NASDAQ, NYSE string Conditional
website Url of the website or online presence of the business. string Yes
vertical Segment or industry the business operates in. Accepts: professional, real_estate, healthcare, human_resources, energy, entertainment, retail, transportation, agriculture, insurance, postal, education, hospitality, financial, political, gambling, legal, construction, ngo, manufacturing, government, technology, communication string Yes
alternative_business_id Alternate business identification such as DUNS, GIIN or LEI number. string No
alternative_business_id_type Type of alternate business ID. Accepts: NONE, DUNS, GIIN, LEI string No
brand_relationship The nature of the relationship between the Campaign Service Provider (CSP) and the Brand being registered. If you are using Voxology as your CSP, this field is read-only. Accepts: basic_account, small_account, medium_account, large_account, key_account. See our Intro to 10DLC for relationship descriptions. string No

Example Request 

curl -X PUT \
  https://api.voxolo.gy/v1/10DLCRegistration/Brands \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "brand_id": "BX0001",
    "entity_name": "Business Company",
    "doing_business_as": "SMS Company",
    "entity_type": "private_profit",
    "tax_id_issuing_country": "US",
    "tax_id": "0000000001",
    "firstname": "George",
    "lastname": "Washington",
    "phone_no": "+15551234567",
    "email": "support@business.com",
    "address": "123 Main St",
    "city": "New York",
    "region": "New York",
    "postal_code": "00001",
    "country": "US",
    "stock_symbol": "",
    "stock_exchange": "",
    "website": "https://www.voxolo.gy",
    "vertical": "technology",
    "alternative_business_id": "00001",
    "alternative_business_id_type": "DUNS",
    "brand_relationship": "basic_account"
    }'

Response

Property Description Type
brand_id The unique ID for the Brand assigned by The Campaign Registry. string
status The brands status with The Campaign Registry. Includes: VERIFIED, UNVERIFIED, VETTED_VERIFIED, SELF_DECLARED string
entity_name Legal name of the business associated with this brand. string
doing_business_as The brand/marketing name of the company string
entity_type The type of business associated with this brand. string
tax_id_issuing_country Country where the business is located and registered for tax purposes. Two-letter ISO-2 code. string
tax_id Legal Tax ID of the business issued by their country’s tax authority. In the U.S. this is the Employer Identification Number assigned by the IRS. string
firstname First name of the authorized point of the contact for the business. string
lastname Last name of the authoritzed point of the contact for the business. string
phone_no Support phone number used to contact the business. string
email Support email address used to contact the business. string
address Street Name and Number of the business address. For best results with Brand vetting, use the same address associated with the business’s Tax ID/EIN. string
city City of the business address. string
region State of Province of the business address. string
postal_code Postal or Zip code of the business address. string
country Country of the business address. Two-letter, ISO-2 code. string
stock_symbol Stock symbol, or ticker, used to identify the business on a stock exchange. string
stock_exchange The exchange code of the stock exchange the business is listed on. E.g. NASDAQ, NYSE string
website Url of the website or online presence of the business. string
vertical Segment or industry the business operates in. string
alternative_business_id Alternate business identification such as DUNS, GIIN or LEI number. string
alternative_business_id_type Type of alternate business ID. string
brand_relationship The nature of the relationship between your company and the Brand being registered. string
trust_score A score from 0-100 assigned by an external vetting provider. Determines throughput and volume levels with the Mobile Network Operators. integer
external_vetting_records An array of imported and/or ordered external vetting records. See our External Vetting methods for more details on external vetting records. array
created_on The date the Brand was created (ISO 8601). string
updated_on The date the Brand was last updated (ISO 8601). string

Example Response

{
    "brand_id": "BX0001",
    "status": "UNVERIFIED",
    "entity_name": "Business Company",
    "doing_business_as": "SMS Company",
    "entity_type": "private_profit",
    "tax_id_issuing_country": "US",
    "tax_id": "0000000001",
    "firstname": "George",
    "lastname": "Washington",
    "phone_no": "+15551234567",
    "email": "support@business.com",
    "address": "123 Main St",
    "city": "New York",
    "region": "New York",
    "postal_code": "00001",
    "country": "US",
    "stock_symbol": "",
    "stock_exchange": "",
    "website": "https://www.voxolo.gy",
    "vertical": "technology",
    "alternative_business_id": "00001",
    "alternative_business_id_type": "DUNS",
    "brand_relationship": "basic_account",
    "trust_score":100,
    "external_vetting_records": [],
    "created_on": "2023-08-03T17:21:35.207Z",
    "updated_on": "2023-08-04T17:21:35.207Z"
}

Response Codes

Status Description
200 Returns a Brand object.
4xx & 5xx General Error Codes

Delete 10DLC Brand

Deletes a specified 10DLC Brand by its Brand ID.

DELETE /10DLCRegistration/Brands/{brand_id}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
brand_id The ID of the 10DLC Brand. string (path) Yes

Example Request

curl -X DELETE \
  https://api.voxolo.gy/v1/10DLCRegistration/Brands/BX0001 \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

No Response Body

Response Codes

Status Description
204 No content on success.
4xx & 5xx General Error Codes

Order External 10DLC Brand Vetting

Places an order for external vetting for a single 10DLC brand.

NOTE: This method is in development. In the meantime, if you would like to request external brand vetting, please email our CX team at support@voxolo.gy.

POST /10DLCRegistration/Brands/OrderExternalVetting/{brand_id}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
brand_id The ID of the 10DLC Brand string (path) Yes
vetting_provider External provider to order vetting from. Accepts: aegis_mobile, wmc_global. Defaults to aegis_mobile. See our Intro to 10DLC for more information on vetting providers. string No
vetting_class Classification of vetting done. Accepts: standard, enhanced. Note: only aegis_mobile accepts enhanced vetting. See our Intro to 10DLC for descriptions of each vetting class. string No

Example Request 

curl -X POST \
  https://api.voxolo.gy/v1/10DLCRegistration/Brands/OrderExternalVetting/BX0001 \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "vetting_provider": "aegis_mobile",
    "vetting_class": "standard"
    }'

Response

Property Description Type
vetting_provider External provider who processed the vetting request. string
vetting_id Token or ID for the vetting record generated by the vetting provider. string
vetting_token An additional, optional token generated by subset of vetting providers. string
vetting_class Classification of vetting done. string
vetting_status Current status of the vetting record. Includes: pending, active, failed. string
vetting_score Vetting score, also called Trust score, from 0-100. Determines the volume and throughput limits placed on the Brand by Mobile Network Operators. See our Intro to 10DLC for details. integer
vetting_failed_reasons A list of causes for a failed vetting status provided by the vetting provider. string
vetted_on The date vetting was completed and became active (ISO 8601). string
created_on The date vetting was submitted (ISO 8601). string

Example Response

{
    "vetting_id": "000001",
    "vetting_provider": "aegis_mobile",
    "vetting_class": "standard",
    "vetting_token": "AAAABBBCCCC",
    "vetting_status": "active",
    "vetting_score": 100,
    "vetting_failed_reasons": "",
    "vetted_on": "2023-08-01T18:21:35.207Z",
    "created_on": "2023-08-01T17:21:35.207Z"
}

Response Codes

Status Description
200 Returns a Vetting Record object.
4xx & 5xx General Error Codes

Import External 10DLC Brand Vetting

Imports an existing vetting record for a 10DLC brand using a token generated by the vetting provider.

NOTE: This method is in development. In the meantime, if you would like to import external brand vetting, please email our CX team at support@voxolo.gy.

POST /10DLCRegistration/Brands/ImportExternalVetting/{brand_id}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
brand_id The ID of the 10DLC Brand string (path) Yes
vetting_provider External provider who performed the vetting. Accepts: aegis_mobile, wmc_global, campaign_verify. string Yes
vetting_id Token or ID for the vetting record generated by the vetting provider. string es
vetting_token Optional secondary token generated by a subset of vetting provider. string No

Example Request 

curl -X POST \
  https://api.voxolo.gy/v1/10DLCRegistration/Brands/ImportExternalVetting/BX0001 \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "vetting_provider": "aegis_mobile",
    "vetting_id": "000001",
    "vetting_token": "AAABBBCCC"
    }'

Response

Property Description Type
vetting_provider External provider who processed the vetting request. string
vetting_id Token or ID for the vetting record generated by the vetting provider. string
vetting_token An additional, optional token generated by subset of vetting providers. string
vetting_class Classification of vetting done. string
vetting_status Current status of the vetting record. Includes: pending, active, failed. string
vetting_score Vetting score, also called Trust score, from 0-100. Determines the volume and throughput limits placed on the Brand by Mobile Network Operators. See our Intro to 10DLC for details. integer
vetting_failed_reasons A list of causes for a failed vetting status provided by the vetting provider. array
vetted_on The date vetting was completed and became active (ISO 8601). string
created_on The date vetting was submitted (ISO 8601). string

Example Response

{
    "vetting_id": "000001",
    "vetting_provider": "aegis_mobile",
    "vetting_class": "standard",
    "vetting_token": "AAAABBBCCCC",
    "vetting_status": "active",
    "vetting_score": 100,
    "vetting_failed_reasons": "",
    "vetted_on": "2023-08-01T18:21:35.207Z",
    "created_on": "2023-08-01T17:21:35.207Z"
}

Response Codes

Status Description
200 Returns a Vetting Record object.
4xx & 5xx General Error Codes

List 10DLC Campaigns

Returns a list of 10DLC Campaigns on this application. The list view returns a subset of Campaign information, see the View Campaign Detail method for a complete view. 

GET /10DLCRegistration/Campaigns

AUTHENTICATION TYPE

API Key (Application-level)

REQUEST

No Request Body

Example Request

curl -X GET \
  https://api.voxolo.gy/v1/10DLCRegistration/Campaigns \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

Property Description Type
campaigns An array of 10DLC Campaign objects. array
campaigns[i].campaign_id The unique ID for this Campaign generated by The Campaign Registry. string
campaigns[i].brand_id The unique ID of the Brand this Campaign is assigned to. string
campaigns[i].use_case The messaging use case designated for this Campaign. string
campaigns[i].description A short description of how this Campaign will be used by the Brand. string
campaigns[i].status The current status of the Campaign with The Campaign Registry. Possible values: active, expired array
campaigns[i].help_keywords An list of the keywords that will receive the HELP response containing Brand contact information. array
campaigns[i].help_message The message sent in response to any of the defined HELP keywords. Should contain a brief description of the message program, contact information for the Brand and instructions to opt-out of further messages. string
campaigns[i].opt_in_keywords A list of the keywords consumers can use to opt-in to messages from this Campaign. array
campaigns[i].opt_in_message The confirmation message sent in response to any of the opt-in keywords. string
campaigns[i].opt_out_keywords A list of the keywords consumers can use to opt-out of all future messages. array
campaigns[i].opt_out_message The confirmation message sent in response to any of the opt-out keywords. string
campaigns[i].created_on The date the Campaign was created (ISO 8601). string
campaigns[i].updated_on The date the Campaign was last updated (ISO 8601). string

Example Response

{
  "campaigns": [
   {
    "campaign_id": "CX0001",
    "brand_id": "BX0001",
    "use_case": "2FA",
    "description": "Sending messages with one time passwords used for 2FA security measures for our customers",
    "status": "active",
    "opt_in_keywords": ["START", "SUBSCRIBE"],
    "opt_in_message": "Thank you for opting-in to receive 2FA notifications. Msg rates apply.",
    "opt_out_keywords": ["STOP", "CANCEL"],
    "opt_out_message": "You have opt-ed out and will receive no further messages from this number",
    "help_keywords": ["HELP"],
    "help_message": "2FA Notifications for Voxology.  Reply STOP to cancel.  Call 800-555-1234 for support.",
    "created_on": "2023-08-03T17:21:35.207Z",
    "updated_on": "2023-08-04T17:21:35.207Z"
   },
   {
    "campaign_id": "CX0002",
    "brand_id": "BX0001",
    "use_case": "account_notification",
    "description": "Alerts and notifications used to send timely information to customers about their account status.",
    "status": "active",
    "opt_in_keywords": ["START", "SUBSCRIBE"],
    "opt_in_message": "Thank you for opting-in to receive account notifications. Msg rates apply.",
    "opt_out_keywords": ["STOP", "CANCEL"],
    "opt_out_message": "You have opt-ed out and will receive no further messages from this number",
    "help_keywords": ["HELP"],
    "help_message": "Account Notifications for Voxology.  Reply STOP to cancel.  Call 800-555-1234 for support.",
    "created_on": "2023-08-03T17:21:35.207Z",
    "updated_on": "2023-08-04T17:21:35.207Z"
   }
  ]
}

Response Codes

Status Description
200 Returns array of 10DLC Campaign objects
4xx & 5xx General Error Codes

View 10DLC Campaign Details

Returns a complete, detailed view of a specified 10DLC Campaign on this application by its Campaign Registry ID.

GET /10DLCRegistration/Campaigns/{campaign_id}

AUTHENTICATION TYPE

API Key (Application-level)

REQUEST

Parameter Description Type Required
campaign_id The ID of the 10DLC Campaign. string (path) Yes

Example Request

curl -X GET \
  https://api.voxolo.gy/v1/10DLCRegistration/Campaigns/CX0001 \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

Property Description Type
campaign_id The unique ID for this Campaign generated by The Campaign Registry. string
brand_id The unique ID of the Brand this Campaign is assigned to. string
use_case The messaging use case designated for this Campaign. string
sub_use_cases Sub-use cases designated for this Campaign. These are optional for most primary use cases. array
description A short description of how this Campaign will be used by the Brand. string
status The current status of the Campaign with The Campaign Registry. Includes: active, expired string
embedded_link Indicates if any message sent from this Campaign will include any kind of embedded link. Note: public url shorteners such as bitly or tinyurl are not accepted. boolean
embedded_phone Indicates if any message sent from this Campaign will include an embedded phone number. Excluding phone numbers provided in response to the HELP keyword. boolean
terms_and_conditions Indicates the creator of this campaign agrees to follow CTIA best practices and principles and confirms that campaign will not be used for affiliate marketing. Only true is accepted. boolean
number_pool Indicates this campaign can support 50+ numbers registered to it. Requires a unique provisioning process with T-Mobile. boolean
age_gated Indicates messages from this campaign include age-gated content as indicated by Carrier and CTIA guidelines. boolean
direct_lending Indicates messages rom this campaign will contain content related to direct lending or other loan agreements. boolean
subscriber_opt_in Indicates the operator of this Campaign is collecting consumer opt-ins. boolean
subscriber_opt_out Indicates the operator of this Campaign is collecting and processing consumer opt-outs. boolean
subscriber_help Indicates the operator of this Campaign will implement a message response to the keyword HELP containing the contact information for the Brand. boolean
message_samples An array of up to 5 strings containing examples of the types of messages sent from this Campaign. array
message_flow A description of the message flow for consumer opt-in. string
help_keywords An list of the keywords that will receive the HELP response containing Brand contact information. array
help_message The message sent in response to any of the defined HELP keywords. Should contain a brief description of the message program, contact information for the Brand and instructions to opt-out of further messages. string
opt_in_keywords A list of the keywords consumers can use to opt-in to messages from this Campaign. array
opt_in_message The confirmation message sent in response to any of the opt-in keywords. string
opt_out_keywords A list of the keywords consumers can use to opt-out of all future messages. array
opt_out_message The confirmation message sent in response to any of the opt-out keywords. string
auto_renew Indicates this campaign will auto renew at the end of each month. boolean
billed_on The timestamp of the last time this campaign was billed (ISO 8601). string
next_renewal_or_expiration_date The date the campaign will either auto renew or expire (YYYY-MM-DD). string
created_on The date the Campaign was created (ISO 8601). string
updated_on The date the Campaign was last updated (ISO 8601). string

Example Response

{
  "campaign_id": "CX0001",
  "brand_id": "BX0001",
  "use_case": "2FA",
  "sub_use_cases": [],
  "description": "Sending messages with one time passwords used for 2FA security measures for our customers",
  "status": "active",
  "embedded_link": true, 
  "embedded_phone": true, 
  "terms_and_conditions": true,
  "number_pool": false, 
  "age_gated": false, 
  "direct_lending": false,
  "subscriber_opt_in": true,
  "subscriber_opt_out": true,
  "subscriber_help": true, 
  "opt_in_keywords": ["START", "SUBSCRIBE"],
  "opt_in_message": "Thank you for opting-in to receive 2FA notifications. Msg rates apply.",
  "opt_out_keywords": ["STOP", "CANCEL"],
  "opt_out_message": "You have opt-ed out and will receive no further messages from this number",
  "help_keywords": ["HELP"],
  "help_message": "2FA Notifications for Voxology.  Reply STOP to cancel.  Call 800-555-1234 for support.",
  "message_flow": "Customers enable 2FA on their online profile and input the number they'd like notifications sent to.  A confirmation message is sent after they enter their number.",
  "message_samples": [
    "Enter this one-time code to login to your account: 12345"
  ],
  "auto_renew": true,
  "billed_on": "2023-08-29T00:00:00.000Z",
  "next_renewal_or_expiration_date": "2023-11-29",
  "created_on": "2023-08-03T17:21:35.207Z",
  "updated_on": "2023-08-04T17:21:35.207Z"
}

Response Codes

Status Description
200 Returns a 10DLC Campaign object
4xx & 5xx General Error Codes

Create 10DLC Campaign

Creates a 10DLC Campaign.

POST /10DLCRegistration/Campaigns

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
brand_id The unique ID of the Brand this Campaign will be assigned to. string Yes
use_case The messaging use case designated for this Campaign. Accepts: 2fa, account_notification, agents_franchise, carrier_exempt, charity, customer_care, delivery_notification, emergency, fraud_alert, higher_education, k12_education, low_volume, m2m, marketing, mixed, political, polling_voting, proxy, public_service_announcement, security_alert, social, sole_proprietor, sweepstake, trial, ucaas_high, ucaas_low. See our Intro to 10DLC for descriptions of each use case. string Yes
sub_use_cases Sub-use cases designated for this Campaign. This parameter uses the same list of values as use_case and is optional for most use cases. array Conditional
description A short description of how this Campaign will be used by the Brand. string Yes
embedded_link Indicates if any message sent from this Campaign will include any kind of embedded link. Note: public url shorteners such as bitly or tinyurl are not accepted. boolean Yes
embedded_phone Indicates if any message sent from this Campaign will include an embedded phone number. Excluding phone numbers provided in response to the HELP keyword. boolean Yes
terms_and_conditions Indicates the creator of this campaign agrees to follow CTIA best practices and principles and confirms that campaign will not be used for affiliate marketing. Only true is accepted. boolean Yes
number_pool Indicates this campaign can support 50+ numbers registered to it. Requires a unique provisioning process with T-Mobile. boolean Yes
age_gated Indicates messages from this campaign include age-gated content as indicated by Carrier and CTIA guidelines. boolean Yes
direct_lending Indicates messages rom this campaign will contain content related to direct lending or other loan agreements. boolean Yes
subscriber_opt_in Indicates the operator of this Campaign is collecting consumer opt-ins. boolean Yes
subscriber_opt_out Indicates the operator of this Campaign is collecting and processing consumer opt-outs. boolean Yes
subscriber_help Indicates the operator of this Campaign will implement a message response to the keyword HELP containing the contact information for the Brand. boolean Yes
message_samples An array of up to 5 strings containing examples of the types of messages sent from this Campaign. Different use cases require different amounts of message samples. Please refer to the use case requirements method for more details. array Yes
message_flow A brief description of the message flow for consumer opt-in. string Yes
help_keywords An list of the keywords that will receive the HELP response containing Brand contact information. array Yes
help_message The message sent in response to any of the defined HELP keywords. Should contain a brief description of the message program, contact information for the Brand and instructions to opt-out of further messages. string Yes
opt_in_keywords A list of the keywords consumers can use to opt-in to messages from this Campaign. array Yes
opt_in_message The confirmation message sent in response to any of the opt-in keywords. string Yes
opt_out_keywords A list of the keywords consumers can use to opt-out of all future messages. array Yes
opt_out_message The message sent in response to any of the opt-out keywords confirming the user will receive no further messages. string Yes
auto_renew Indicates this campaign will auto renew at the end of each month. boolean Yes

Example Request 

curl -X POST \
  https://api.voxolo.gy/v1/10DLCRegistration/Campaigns \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "brand_id": "BX0001",
    "use_case": "2FA",
    "sub_use_cases": [],
    "description": "Sending messages with one time passwords used for 2FA security measures for our customers",
    "embedded_link": true, 
    "embedded_phone": true, 
    "terms_and_conditions": true,
    "number_pool": false, 
    "age_gated": false, 
    "direct_lending": false,
    "subscriber_opt_in": true,
    "subscriber_opt_out": true,
    "subscriber_help": true, 
    "opt_in_keywords": ["START", "SUBSCRIBE"],
    "opt_in_message": "Thank you for opting-in to receive 2FA notifications. Msg rates apply.",
    "opt_out_keywords": ["STOP", "CANCEL"],
    "opt_out_message": "You have opt-ed out and will receive no further messages from this number",
    "help_keywords": ["HELP"],
    "help_message": "2FA Notifications for Voxology.  Reply STOP to cancel.  Call 800-555-1234 for support.",
    "message_flow": "Customers enable 2FA on their online profile and input the number they would like notifications sent to.  A confirmation message is sent after they enter their number.",
    "message_samples": [
      "Enter this one-time code to login to your account: 12345"
    ],
    "auto_renew": true
   }'

Response

Property Description Type
campaign_id The unique ID for this Campaign generated by The Campaign Registry. string
brand_id The unique ID of the Brand this Campaign is assigned to. string
use_case The messaging use case designated for this Campaign. string
sub_use_cases Sub-use cases designated for this Campaign. These are optional for most primary use cases. array
description A short description of how this Campaign will be used by the Brand. string
status The current status of the Campaign with The Campaign Registry. Includes: active, expired string
embedded_link Indicates if any message sent from this Campaign will include any kind of embedded link. Note: public url shorteners such as bitly or tinyurl are not accepted. boolean
embedded_phone Indicates if any message sent from this Campaign will include an embedded phone number. Excluding phone numbers provided in response to the “HELP” keyword. boolean
terms_and_conditions Indicates the creator of this campaign agrees to follow CTIA best practices and principles and confirms that campaign will not be used for affiliate marketing. Only true is accepted. boolean
number_pool Indicates this campaign can support 50+ numbers registered to it. Requires a unique provisioning process with T-Mobile. boolean
age_gated Indicates messages from this campaign include age-gated content as indicated by Carrier and CTIA guidelines. boolean
direct_lending Indicates messages rom this campaign will contain content related to direct lending or other loan agreements. boolean
subscriber_opt_in Indicates the operator of this Campaign is collecting consumer opt-ins. Required. boolean
subscriber_opt_out Indicates the operator of this Campaign is collecting and processing consumer opt-outs. Required. boolean
subscriber_help Indicates the operator of this Campaign will implement a message response to the keyword HELP containing the contact information for the Brand. Required. boolean
message_samples An array of up to 5 strings containing examples of the types of messages sent from this Campaign. array
message_flow A description of the message flow for consumer opt-in. string
help_keywords An list of the keywords that will receive the HELP response containing Brand contact information. array
help_message The message sent in response to any of the defined HELP keywords. Should contain a brief description of the message program, contact information for the Brand and instructions to opt-out of further messages. string
opt_in_keywords A list of the keywords consumers can use to opt-in to messages from this Campaign. array
opt_in_message The confirmation message sent in response to any of the opt-in keywords. string
opt_out_keywords A list of the keywords consumers can use to opt-out of all future messages. array
opt_out_message The confirmation message sent in response to any of the opt-out keywords. string
auto_renew Indicates this campaign will auto renew at the end of each month. boolean
billed_on The timestamp of the last time this campaign was billed (ISO 8601). string
next_renewal_or_expiration_date The date the campaign will either auto renew or expire. string
created_on The date the Campaign was created (ISO 8601). string
updated_on The date the Campaign was last updated (ISO 8601). string

Example Response

{
  "campaign_id": "CX0001",
  "brand_id": "BX0001",
  "use_case": "2FA",
  "sub_use_cases": [],
  "description": "Sending messages with one time passwords used for 2FA security measures for our customers",
  "status": "active",
  "embedded_link": true, 
  "embedded_phone": true, 
  "terms_and_conditions": true,
  "number_pool": false, 
  "age_gated": false, 
  "direct_lending": false,
  "subscriber_opt_in": true,
  "subscriber_opt_out": true,
  "subscriber_help": true, 
  "opt_in_keywords": ["START", "SUBSCRIBE"],
  "opt_in_message": "Thank you for opting-in to receive 2FA notifications. Msg rates apply.",
  "opt_out_keywords": ["STOP", "CANCEL"],
  "opt_out_message": "You have opt-ed out and will receive no further messages from this number",
  "help_keywords": ["HELP"],
  "help_message": "2FA Notifications for Voxology.  Reply STOP to cancel.  Call 800-555-1234 for support.",
  "message_flow": "Customers enable 2FA on their online profile and input the number they'd like notifications sent to.  A confirmation message is sent after they enter their number.",
  "message_samples": [
    "Enter this one-time code to login to your account: 12345"
  ],
  "auto_renew": true,
  "billed_on": "2023-08-29T00:00:00.000Z",
  "next_renewal_or_expiration_date": "2023-11-29",
  "created_on": "2023-08-03T17:21:35.207Z",
  "updated_on": "2023-08-04T17:21:35.207Z"
}

Response Codes

Status Description
200 Returns the 10DLC Campaign object
4xx & 5xx General Error Codes

Update 10DLC Campaign

Updates an existing 10DLC Campaign.

PUT /10DLCRegistration/Campaigns/{campaign_id}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
campaign_id The unique ID for this Campaign generated by The Campaign Registry. string (path) Yes
brand_id The unique ID of the Brand this Campaign will be assigned to. string Yes
use_case The messaging use case designated for this Campaign. Accepts: 2fa, account_notification, agents_franchise, carrier_exempt, charity, customer_care, delivery_notification, emergency, fraud_alert, higher_education, k12_education, low_volume, m2m, marketing, mixed, political, polling_voting, proxy, public_service_announcement, security_alert, social, sole_proprietor, sweepstake, trial, ucaas_high, ucaas_low. See our Intro to 10DLC for descriptions of each use case. string Yes
sub_use_cases Sub-use cases designated for this Campaign. These are optional for most primary use cases. Sub-use cases designated for this Campaign. These are optional for most primary use cases. See our Intro to 10DLC for possible sub-use cases. array Conditional
description A short description of how this Campaign will be used by the Brand. array Yes
embedded_link Indicates if any message sent from this Campaign will include any kind of embedded link. Note: public url shorteners such as bitly or tinyurl are not accepted. boolean Yes
embedded_phone Indicates if any message sent from this Campaign will include an embedded phone number. Excluding phone numbers provided in response to the HELP keyword. boolean Yes
terms_and_conditions Indicates the creator of this campaign agrees to follow CTIA best practices and principles and confirms that campaign will not be used for affiliate marketing. Only true is accepted. boolean Yes
number_pool Indicates this campaign can support 50+ numbers registered to it. Requires a unique provisioning process with T-Mobile. boolean Yes
age_gated Indicates messages from this campaign include age-gated content as indicated by Carrier and CTIA guidelines. boolean Yes
direct_lending Indicates messages rom this campaign will contain content related to direct lending or other loan agreements. boolean Yes
subscriber_opt_in Indicates the operator of this Campaign is collecting consumer opt-ins. boolean Yes
subscriber_opt_out Indicates the operator of this Campaign is collecting and processing consumer opt-outs. boolean Yes
subscriber_help Indicates the operator of this Campaign will implement a message response to the keyword HELP containing the contact information for the Brand. boolean Yes
message_samples An array of up to 5 strings containing examples of the types of messages sent from this Campaign. Different use cases require different amounts of messaage samples. Please refer to the use case requirments method for more details. array Yes
message_flow A brief description of the message flow for consumer opt-in. string Yes
help_keywords An list of the keywords that will receive the HELP response containing Brand contact information. array Yes
help_message The message sent in response to any of the defined HELP keywords. Should contain a brief description of the message program, contact information for the Brand and instructions to opt-out of further messages. string Yes
opt_in_keywords A list of the keywords consumers can use to opt-in to messages from this Campaign. array Yes
opt_in_message The confirmation message sent in response to any of the opt-in keywords. string Yes
opt_out_keywords A list of the keywords consumers can use to opt-out of all future messages. array Yes
opt_out_message The message sent in response to any of the opt-out keywords confirming the user will receive no further messages. string Yes
auto_renew Indicates this campaign will auto renew at the end of each month. boolean Yes

Example Request 

curl -X PUT \
  https://api.voxolo.gy/v1/10DLCRegistration/Campaigns/CX0001 \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "brand_id": "BX0001",
    "use_case": "2FA",
    "sub_use_cases": [],
    "description": "Sending messages with one time passwords used for 2FA security measures for our customers",
    "status": "active",
    "created_on":"",
    "updated_on":"",
    "embedded_link": true, 
    "embedded_phone": true, 
    "terms_and_conditions": true,
    "number_pool": false, 
    "age_gated": false, 
    "direct_lending": false,
    "subscriber_opt_in": true,
    "subscriber_opt_out": true,
    "subscriber_help": true, 
    "opt_in_keywords": ["START", "SUBSCRIBE"],
    "opt_in_message": "Thank you for opting-in to receive 2FA notifications. Msg rates apply.",
    "opt_out_keywords": ["STOP", "CANCEL"],
    "opt_out_message": "You have opt-ed out and will receive no further messages from this number",
    "help_keywords": ["HELP"],
    "help_message": "2FA Notifications for Voxology.  Reply STOP to cancel.  Call 800-555-1234 for support.",
    "message_flow": "Customers enable 2FA on their online profile and input the number they'd like notifications sent to.  A confirmation message is sent after they enter their number.",
    "message_samples": [
      "Enter this one-time code to login to your account: 12345"
    ],
    "auto_renew": true
   }'

Response

Property Description Type
campaign_id The unique ID for this Campaign generated by The Campaign Registry. string
brand_id The unique ID of the Brand this Campaign is assigned to. string
use_case The messaging use case designated for this Campaign. string
sub_use_cases Sub-use cases designated for this Campaign. These are optional for most primary use cases. array
description A short description of how this Campaign will be used by the Brand. string
status The current status of the Campaign with The Campaign Registry. Possible values: active, expired string
embedded_link Indicates if any message sent from this Campaign will include any kind of embedded link. Note: public url shorteners such as bitly or tinyurl are not accepted. boolean
embedded_phone Indicates if any message sent from this Campaign will include an embedded phone number. Excluding phone numbers provided in response to the HELP keyword. boolean
terms_and_conditions Indicates the creator of this campaign agrees to follow CTIA best practices and principles and confirms that campaign will not be used for affiliate marketing. Only true is accepted. boolean
number_pool Indicates this campaign can support 50+ numbers registered to it. Requires a unique provisioning process with T-Mobile. boolean
age_gated Indicates messages from this campaign include age-gated content as indicated by Carrier and CTIA guidelines. boolean
direct_lending Indicates messages rom this campaign will contain content related to direct lending or other loan agreements. boolean
subscriber_opt_in Indicates the operator of this Campaign is collecting consumer opt-ins. boolean
subscriber_opt_out Indicates the operator of this Campaign is collecting and processing consumer opt-outs. boolean
subscriber_help Indicates the operator of this Campaign will implement a message response to the keyword HELP containing the contact information for the Brand. boolean
message_samples An array of up to 5 strings containing examples of the types of messages sent from this Campaign. array
message_flow A description of the message flow for consumer opt-in. string
help_keywords An list of the keywords that will receive the HELP response containing Brand contact information. array
help_message The message sent in response to any of the defined HELP keywords. Should contain a brief description of the message program, contact information for the Brand and instructions to opt-out of further messages. string
opt_in_keywords A list of the keywords consumers can use to opt-in to messages from this Campaign. array
opt_in_message The confirmation message sent in response to any of the opt-in keywords. string
opt_out_keywords A list of the keywords consumers can use to opt-out of all future messages. array
opt_out_message The confirmation message sent in response to any of the opt-out keywords. string
auto_renew Indicates this campaign will auto renew at the end of each month. boolean
billed_on The timestamp of the last time this campaign was billed (ISO 8601). string
next_renewal_or_expiration_date The date the campaign will either auto renew or expire. string
created_on The date the Campaign was created (ISO 8601). string
updated_on The date the Campaign was last updated (ISO 8601). string

Example Response

{
  "campaign_id": "CX0001",
  "brand_id": "BX0001",
  "use_case": "2FA",
  "sub_use_cases": [],
  "description": "Sending messages with one time passwords used for 2FA security measures for our customers",
  "status": "active",
  "embedded_link": true, 
  "embedded_phone": true, 
  "terms_and_conditions": true,
  "number_pool": false, 
  "age_gated": false, 
  "direct_lending": false,
  "subscriber_opt_in": true,
  "subscriber_opt_out": true,
  "subscriber_help": true, 
  "opt_in_keywords": ["START", "SUBSCRIBE"],
  "opt_in_message": "Thank you for opting-in to receive 2FA notifications. Msg rates apply.",
  "opt_out_keywords": ["STOP", "CANCEL"],
  "opt_out_message": "You have opt-ed out and will receive no further messages from this number",
  "help_keywords": ["HELP"],
  "help_message": "2FA Notifications for Voxology.  Reply STOP to cancel.  Call 800-555-1234 for support.",
  "message_flow": "Customers enable 2FA on their online profile and input the number they'd like notifications sent to.  A confirmation message is sent after they enter their number.",
  "message_samples": [
    "Enter this one-time code to login to your account: 12345"
  ],
  "auto_renew": true,
  "billed_on": "2023-08-29T00:00:00.000Z",
  "next_renewal_or_expiration_date": "2023-11-29",
  "created_on": "2023-08-03T17:21:35.207Z",
  "updated_on": "2023-08-04T17:21:35.207Z"
}

Response Codes

Status Description
200 Returns the 10DLC Campaign object
4xx & 5xx General Error Codes

Delete 10DLC Campaign

Deletes an existing 10DLC Campaign and deprovisions the Campaign with Campaign Registry.

DELETE /10DLCRegistration/Campaigns/{campaign_id}

Authentication Type

API Key (Application-level)

REQUEST

Parameter Description Type Required
campaign_id The ID of the 10DLC Campaign string (path) Yes

Example Request

curl -X DELETE \
  https://api.voxolo.gy/v1/10DLCRegistration/Campaigns/CX0001 \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

No Response Body

Response Codes

Status Description
204 No content on success.
4xx & 5xx General Error Codes

Phone Numbers

List Available Inbound Numbers

Returns a list of phone numbers available for provisioning and purchase, including the capabilities that each phone number has.

GET /PhoneNumbers/Available?{query_string}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
capabilities Capabilities required on the phone number. Accepts: voice, sms, mms, cnam and emergency. This query parameter is inclusive. SMS enabled numbers may also be returned when searching for voice enabled numbers. Accepts comma-delimited values or multiple capabilities key/values String (query) Yes
country an ISO Alpha-2 country code. Default is US. String (query) No
type The phone number type. Accepts local, toll_free, and all. Default is all. string (query) No
max_results Sets the maximum number of results to return. Max value is 100. Default is 10. integer (query) No
search_by Search by this criteria. Accepts region, prefixes, postal_code, rate_center, latas, mms, cnam, emergency, and vanity. Default is region. string (query) No
search_on The value to search for, based on the search_by parameter. See search_on details in the next table. string (query) No

Search Details

search_by Parameter search_on Details Supported Types
region Accepts state or city, state. Separate city and state by a comma. (examples: “CA” or “Irvine,CA”) local
prefixes Accepts a comma-delimited list of prefixes. (example: “714,310,949”) local, toll_free
postal-code Accepts a five digit postal (or zip) code. local
rate-center Accepts rate center name and state (example: “NEWPORTBCH, CA”). This search overrides country parameter and includes all NANP countries. local
latas Accepts a comma-delimited list of latas (example: “123,456,789”). This search overrides country parameter and includes all NANP countries. local
vanity Accepts numbers, letters, and 2 different wildcard characters - an asterisk * and ampersand &. The character for any number is indicated by an asterisk *. The character for any repeated numbers are indicated by an ampersand &. (example: search_on=8&&***CATS may return: +18001232287) NOTE: Depending on how you send in the request, you may have to encode the * as %2A and & as %26. toll_free

Example Request

curl -X GET \
  'https://api.voxolo.gy/v1/PhoneNumbers/Available?capabilities=voice,cnam,emergency&search_by=prefixes&search_on=949' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY'

Example Request // Toll-free vanity number search

curl -X GET \
  'https://api.voxolo.gy/v1/PhoneNumbers/Available?capabilities=voice&type=toll_free&search_by=vanity&search_on=8%2A%2A9%2A%2A%2A%2A%26%26' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

Property Description Type
phone_numbers List of phone numbers. array
phone_numbers[i].no Phone number in E.164 format. string
phone_numbers[i].formatted A human-friendly phone number format. string
phone_numbers[i].type The phone number type. Includes local and toll_free. string
phone_numbers[i].capabilities[] The list of capabilities that are currently active on the phone number. Possible returns: voice_inbound, voice_outbound, sms_inbound, sms_outbound, mms_inbound, mms_outbound, cnam. array
phone_numbers[i].location An object describing location information about the phone number object
phone_numbers[i].location.city The city of the phone number. string
phone_numbers[i].location.region The region or state code of the phone number. string
phone_numbers[i].location.postal_code The phone number zip/postal code. string
phone_numbers[i].location.country The two-character country code of the phone number given in ISO Alpha-2 format. string
phone_numbers[i].location.rate_center The rate center of the phone number, if applicable. string
phone_numbers[i].location.lata The lata of the phone number, if applicable. string
phone_numbers[i].location.latitude The latitude of the phone number. string
phone_numbers[i].location.longitude the longitude of the phone number. string
phone_numbers[i].price The price for the particular phone number. string
phone_numbers[i].price_period The period at which the price for the number is billed. string
phone_numbers[i].estimated_active_date The estimated date when the phone number will be routed and ready for traffic. string
phone_numbers[i].estimated_active_date_user_message Additional information about estimated time to route the number. string
phone_numbers[i].manage_capabilities An object that describes the phone number’s capabilities settings. object
phone_numbers[i].manage_capabilities.voice An object that describes the phone number’s voice capability settings. object
phone_numbers[i].manage_capabilities.voice.status Options: active, inactive, pending, unavailable, error. string
phone_numbers[i].manage_capabilities.voice.is_modifiable Describes if the voice capability is fixed or can be turned on and off on this phone number. true means that voice can be turned on and off by toggling “status” to active/inactive. false means that the voice capability is unable to be turned on and off. boolean
phone_numbers[i].manage_capabilities.sms An object that describes the phone number’s sms capability settings. object
phone_numbers[i].manage_capabilities.sms.status Options: active, inactive, pending, unavailable, error. string
phone_numbers[i].manage_capabilities.sms.is_modifiable Describes if the sms capability is fixed or can be turned on and off on this phone number. true means that sms can be turned on and off by toggling “status” to active/inactive. false means that the sms capability is unable to be turned on and off. boolean
phone_numbers[i].manage_capabilities.mms An object that describes the phone number’s mms capability settings. object
phone_numbers[i].manage_capabilities.mms.status Options: active, inactive, pending, unavailable, error. string
phone_numbers[i].manage_capabilities.mms.is_modifiable Describes if the mms capability is fixed or can be turned on and off on this phone number. true means that mms can be turned on and off by toggling “status” to active/inactive. false means that the mms capability is unable to be turned on and off. boolean
phone_numbers[i].manage_capabilities.cnam An object that describes the phone number’s cnam capability setting. If cnam.status is set to active, you may set the caller_id_name on the phone number. object
phone_numbers[i].manage_capabilities.cnam.status Options: active, inactive, unavailable. string
phone_numbers[i].manage_capabilities.cnam.is_modifiable Describes if the cnam capability is fixed or can be turned on and off on this phone number. true means that cnam can be turned on and off by toggling “status” to active/inactive. false means that the cnam capability is unable to be turned on and off. boolean

Example Response

{
  "phone_numbers": [
    {
      "no": "+19495551212",
      "formatted": "(949) 555-1212",
      "type": "local",
      "capabilities": [
        "sms_inbound",
        "sms_outbound",
        "voice_inbound",
        "voice_outbound"
      ],
      "manage_capabilities": {
        "voice": {
          "status": "active",
          "is_modifiable": false
        },
        "cnam": {
          "status": "active",
          "is_modifiable": false
        },
        "sms": {
          "status": "active",
          "is_modifiable": true
        },
        "mms": {
          "status": "active",
          "is_modifiable": true
        }
      },
      "location": {
        "country": "US",
        "region": "CA",
        "city": "Rancho Viejo",
        "postal_code": "92672",
        "rate_center": "RANCHO VIEJO",
        "lata": "730",
        "latitude": 33.53147206979202,
        "longitude": -117.550266074771,
        "timezone": "America/Los_Angeles"
      },
      "price": 0.03766,
      "price_period": "day",
      "estimated_active_date": "2018-08-22T09:47:13.857.000Z",
      "estimated_active_date_user_message": "immediately"
    },
    {
      "no": "+19495551213",
      "formatted": "(949) 555-1213",
      "type": "local",
      "capabilities": ["voice_inbound", "voice_outbound"],
      "manage_capabilities": {
        "voice": {
          "status": "active",
          "is_modifiable": false
        },
        "cnam": {
          "status": "active",
          "is_modifiable": false
        },
        "sms": {
          "status": "active",
          "is_modifiable": true
        },
        "mms": {
          "status": "active",
          "is_modifiable": true
        }
      },
      "location": {
        "country": "US",
        "region": "CA",
        "city": "Newport Beach",
        "postal_code": "92658",
        "rate_center": "NEWPORT BEACH",
        "lata": "730",
        "latitude": 33.61891009999998,
        "longitude": -117.9289469,
        "timezone": "America/Los_Angeles"
      },
      "price": 0.035,
      "price_period": "day",
      "estimated_active_date": "2018-08-22T09:47:13.857.000Z",
      "estimated_active_date_user_message": "immediately"
    },
    {
      "no": "+19495551214",
      "formatted": "(949) 555-1214",
      "type": "local",
      "capabilities": ["voice_inbound", "voice_outbound"],
      "manage_capabilities": {
        "voice": {
          "status": "active",
          "is_modifiable": false
        },
        "cnam": {
          "status": "active",
          "is_modifiable": false
        },
        "sms": {
          "status": "active",
          "is_modifiable": true
        },
        "mms": {
          "status": "active",
          "is_modifiable": true
        }
      },
      "location": {
        "country": "US",
        "region": "CA",
        "city": "Newport Beach",
        "postal_code": "92658",
        "rate_center": "NEWPORT BEACH",
        "lata": "730",
        "latitude": 33.61891009999998,
        "longitude": -117.9289469,
        "timezone": "America/Los_Angeles"
      },
      "price": 0.035,
      "price_period": "day",
      "estimated_active_date": "2018-08-22T11:47:17.999.000Z",
      "estimated_active_date_user_message": "less than 2 hours"
    }
  ]
}

Example Response // Toll-free vanity number search

{
  "phone_numbers": [
    {
      "no": "+18339741031",
      "formatted": "(833) 974-1044",
      "type": "tollfree",
      "capabilities": ["voice_inbound", "voice_outbound"],
      "manage_capabilities": {
        "voice": {
          "status": "active",
          "is_modifiable": false
        },
        "cnam": {
          "status": "active",
          "is_modifiable": false
        },
        "sms": {
          "status": "active",
          "is_modifiable": true
        },
        "mms": {
          "status": "active",
          "is_modifiable": false
        }
      },
      "location": {
        "country": "US",
        "region": null,
        "city": null,
        "postal_code": null,
        "rate_center": null,
        "lata": null,
        "latitude": 0,
        "longitude": 0,
        "timezone": null
      },
      "price": 0.0657,
      "price_period": "day",
      "estimated_active_date": "2018-08-24T11:35:25.094.000Z",
      "estimated_active_date_user_message": "less than a day"
    },
    {
      "no": "+18339741022",
      "formatted": "(833) 974-1022",
      "type": "tollfree",
      "capabilities": ["voice_inbound", "voice_outbound"],
      "manage_capabilities": {
        "voice": {
          "status": "active",
          "is_modifiable": false
        },
        "cnam": {
          "status": "active",
          "is_modifiable": false
        },
        "sms": {
          "status": "active",
          "is_modifiable": true
        },
        "mms": {
          "status": "active",
          "is_modifiable": false
        }
      },
      "location": {
        "country": "US",
        "region": null,
        "city": null,
        "postal_code": null,
        "rate_center": null,
        "lata": null,
        "latitude": 0,
        "longitude": 0,
        "timezone": null
      },
      "price": 0.0657,
      "price_period": "day",
      "estimated_active_date": "2018-08-24T11:35:25.094.000Z",
      "estimated_active_date_user_message": "less than a day"
    },
    {
      "no": "+18339741026",
      "formatted": "(833) 974-1066",
      "type": "tollfree",
      "capabilities": ["voice_inbound", "voice_outbound"],
      "manage_capabilities": {
        "voice": {
          "status": "active",
          "is_modifiable": false
        },
        "cnam": {
          "status": "active",
          "is_modifiable": false
        },
        "sms": {
          "status": "active",
          "is_modifiable": true
        },
        "mms": {
          "status": "active",
          "is_modifiable": false
        }
      },
      "location": {
        "country": "US",
        "region": null,
        "city": null,
        "postal_code": null,
        "rate_center": null,
        "lata": null,
        "latitude": 0,
        "longitude": 0,
        "timezone": null
      },
      "price": 0.0657,
      "price_period": "day",
      "estimated_active_date": "2018-08-24T11:35:25.094.000Z",
      "estimated_active_date_user_message": "less than a day"
    }
  ]
}

Response Codes

Status Description
200 An array of available phone numbers.
4xx & 5xx General Error Codes
4xx & 5xx Phone Number Error Codes

List Provisioned Numbers

Returns a list of phone numbers assigned to CallFlows, ParkingLot, or Trunks/{trunk_id}. Omit /{assigned_to} to get all assigned numbers.

GET /PhoneNumbers/{assigned_to}?{query_string}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
assigned_to The routing destination of the phone number: CallFlows, ParkingLot, Trunks/{trunk_id}. string (path) No
capabilities Capabilities of the phone number. Accepts: voice and sms. This query parameter is inclusive, so a sms enabled number may also be returned when searching for a voice enabled number. Accepts comma-delimited values or multiple capabilities key/values String (query) No
country an ISO Alpha-2 country code. Default is US. string (query) No
type The phone number type. Accepts: local, toll_free, or all. Default is all. string (query) No
status The current status of the number. Accepts: reserving, reserved, routing, routed, released, paused, reserved_routing_error, or error. Default returns all except released. string (query) No
messaging_brand_id The 10DLC Brand ID assigned to the phone number. string (query) No
messaging_campaign_id The 10DLC Campaign ID assigned to the phone number. string (query) No
search_by Search by this criteria. Accepts: region, prefixes, postal_code, rate_center, latas. Default is region. string (query) No
search_on The value to search for, based on the search_by parameter. See search_on details in the next table. string (query) No
sort_by Sort the phone number list by: updated_on (date), created_on (date), no (phone number), status, assigned_to. Defaults to updated_on. string (query) No
sort_order The order of call list uses the sort_by field. Accepts: asc, desc. Defaults to asc. string (query) No
page The page number to return. Zero-based index. Defaults to 0. integer (query) No
page_size The number of phone numbers per page. Defaults to 25. integer (query) No
max_results Sets the maximum number of results to return. Max value is 100. Default is 10. integer (query) No

Search Details

search_by Parameter search_on Details Supported Types
region Accepts state or city, state. Separate city and state by a comma. (examples: “CA” or “Irvine,CA”) local
prefixes Accepts a comma-delimited list of prefixes in either standard or E164 format. If searching on a list of prefixes, they must all be in the same format.” (example: “714,310,949” or “+1714,+1310,+1949“) local, toll_free
postal_code Accepts a five digit postal (or zip) code. local
rate_center Accepts rate center name and state. (example: “NEWPORTBCH, CA”) local
latas Accepts a comma-delimited list of latas. (example: “123,456,789”) local
vanity Accepts numbers, letters, and 2 different wildcard characters - an asterisk * and ampersand &. The character for any number is indicated by an asterisk *. The character for any repeated numbers are indicated by an ampersand &. (example: search_on=8&&***CATS may return: +18001232287) NOTE: Depending on how you send in the request, you may have to encode the * as %2A and & as %26. toll_free

Example Request

curl -X GET \
  https://api.voxolo.gy/v1/PhoneNumbers/CallFlows&page=0&page_size=10 \
  -H 'Cache-Control: no-cache' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

Property Description Type
phone_numbers List of phone numbers. array
phone_numbers[i].no The phone number in E.164 format. string
phone_numbers[i].formatted A human-friendly phone number format. string
phone_numbers[i].assigned_to The routing destination of the phone number: CallFlows, ParkingLot, Trunks/{trunk_id}. string
phone_numbers[i].error Any error that occurred when provisioning the number. string
phone_numbers[i].capabilities[] The list of capabilities that are currently active on the phone number. Possible returns: voice_inbound, voice_outbound, sms_inbound, sms_outbound, mms_inbound, mms_outbound, cnam. array
phone_numbers[i].description User-definable description of the phone number. string
phone_numbers[i].caller_id_name If cnam capable, the Caller ID Name of the phone number. string
phone_numbers[i].status The current status of the number. Returns: reserving, reserved, routing, routed, released, paused, reserved_routing_error, or error. string
phone_numbers[i].price The fee for using this number. Price is in USD. integer
phone_numbers[i].price_period The recurring period the price will be charged. Returns: day. string
phone_numbers[i].created_on The date/time this phone number object was created under this Application or Sub Account. NOTE: if the Phone Number is moved between Applications or Sub Accounts, this date will be updated. ISO Date (string)
phone_numbers[i].updated_on The date/time this phone number was last updated. ISO Date (string)
phone_numbers[i].usage The number of calls made by the current holder of the phone number. integer
phone_numbers[i].port_out_pin PIN number used when creating a port out request. string
phone_numbers[i].type The phone number type. Includes: local or toll_free string
phone_numbers[i].messaging_brand_id The 10DLC Brand ID assigned to the phone number. A verified 10DLC Brand is required to send messages on local numbers. string
phone_numbers[i].messaging_campaign_id The 10DLC Campaign ID assigned to the phone number. A verified 10DLC Campaign is required to send messages on local numbers. string
phone_numbers[i].location An object describing location information about the phone number object
phone_numbers[i].location.city The city of the phone number. string
phone_numbers[i].location.region The region or state code of the phone number. string
phone_numbers[i].location.postal_code The phone number zip/postal code. string
phone_numbers[i].location.country The two-character country code of the phone number given in ISO Alpha-2 format. string
phone_numbers[i].location.rate_center The rate center of the phone number, if applicable. string
phone_numbers[i].location.lata The lata of the phone number, if applicable. string
phone_numbers[i].location.latitude The latitude of the phone number. string
phone_numbers[i].location.longitude the longitude of the phone number. string
phone_numbers[i].estimated_active_date The estimated date when the phone number will be routed and ready for traffic. string
phone_numbers[i].estimated_active_date_user_message Additional information about estimated time to route the number. This value is Null if the status is not reserved or routing. string
phone_numbers[i].manage_capabilities An object that describes the phone number’s capabilities settings. object
phone_numbers[i].manage_capabilities.voice An object that describes the phone number’s voice capability settings. object
phone_numbers[i].manage_capabilities.voice.status Options: active, inactive, pending, unavailable, error. string
phone_numbers[i].manage_capabilities.voice.is_modifiable Describes if the voice capability is fixed or can be turned on and off on this phone number. true means that voice can be turned on and off by toggling “status” to active/inactive. false means that the voice capability is unable to be turned on and off. boolean
phone_numbers[i].manage_capabilities.sms An object that describes the phone number’s sms capability settings. object
phone_numbers[i].manage_capabilities.sms.status Options: active, inactive, pending, unavailable, error. string
phone_numbers[i].manage_capabilities.sms.is_modifiable Describes if the sms capability is fixed or can be turned on and off on this phone number. true means that sms can be turned on and off by toggling “status” to active/inactive. false means that the sms capability is unable to be turned on and off. boolean
phone_numbers[i].manage_capabilities.mms An object that describes the phone number’s mms capability settings. object
phone_numbers[i].manage_capabilities.mms.status Options: active, inactive, pending, unavailable, error. string
phone_numbers[i].manage_capabilities.mms.is_modifiable Describes if the mms capability is fixed or can be turned on and off on this phone number. true means that mms can be turned on and off by toggling “status” to active/inactive. false means that the mms capability is unable to be turned on and off. boolean
phone_numbers[i].manage_capabilities.cnam An object that describes the phone number’s cnam capability setting. If cnam.status is set to active, you may set the caller_id_name on the phone number. object
phone_numbers[i].manage_capabilities.cnam.status Options: active, inactive, unavailable. string
phone_numbers[i].manage_capabilities.cnam.is_modifiable Describes if the cnam capability is fixed or can be turned on and off on this phone number. true means that cnam can be turned on and off by toggling “status” to active/inactive. false means that the cnam capability is unable to be turned on and off. boolean

Example Response

{
  "phone_numbers": [
    {
      "no": "+19495551212",
      "formatted": "(949) 555-1212",
      "assigned_to": "CallFlows",
      "description": "Office Desk Phone",
      "capabilities": [
        "sms_inbound",
        "sms_outbound",
        "voice_inbound",
        "voice_outbound"
      ],
      "manage_capabilities": {
        "voice": {
          "status": "active",
          "is_modifiable": false
        },
        "cnam": {
          "status": "active",
          "is_modifiable": false
        },
        "sms": {
          "status": "active",
          "is_modifiable": true
        },
        "mms": {
          "status": "active",
          "is_modifiable": true
        }
      },
      "caller_id_name": "Bob Jones",
      "status": "routed",
      "usage": 100,
      "price": 1,
      "price_period": "day",
      "created_on": "2019-03-08T13:15:33.000Z",
      "updated_on": "2019-12-03T16:20:42.000Z",
      "type": "local",
      "location": {
        "country": "US",
        "region": "CA",
        "city": "Newport Beach",
        "postal_code": "92658",
        "rate_center": "NEWPORT BEACH",
        "lata": "730",
        "latitude": 33.61891009999998,
        "longitude": -117.9289469,
        "timezone": "America/Los_Angeles"
      },
      "messaging_brand_id": "BX0001",
      "messaging_campaign_id": "CX0001",
      "estimated_active_date": "2018-08-22T14:55:52.000Z",
      "estimated_active_date_user_message": null
    }
  ],
  "pagination": {
    "current_page": 0,
    "total_pages": 1,
    "total_items": 1,
    "items_per_page": 10
  }
}

Response Codes

Status Description
200 An array phone number objects.
4xx & 5xx General Error Codes
4xx & 5xx Phone Number Error Codes

View Provisioned Number

Returns a specified phone number assigned to CallFlows, ParkingLot, or Trunks/{trunk_id}.

GET /PhoneNumbers/{phone_number}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
phone_number A purchased number string (path) No

Example Request

curl --X GET \
  'https://api.voxolo.gy/v1/PhoneNumbers/+19495551212' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

Property Description Type
no The phone number in E.164 format. string
formatted A human-friendly phone number format. string
assigned_to The routing destination of the phone number: CallFlows, ParkingLot, Trunks/{trunk_id}. string
error Any error that occurred when provisioning the number. string
capabilities[] The list of capabilities that are currently active on the phone number. Possible returns: voice_inbound, voice_outbound, sms_inbound, sms_outbound, mms_inbound, mms_outbound, cnam. array
description User-definable description of the phone number. string
caller_id_name If cnam capable, the Caller ID Name of the phone number. string
status The current status of the number. Returns: reserving, reserved, routing, routed, released, paused, reserved_routing_error, or error. string
price The fee for using this number. Price is in USD. number
price_period The recurring period the price will be charged. Returns: day. string
created_on The date/time this phone number object was created under this Application or Sub Account. NOTE: if the Phone Number is moved between Applications or Sub Accounts, this date will be updated. ISO Date (string)
updated_on The date/time this phone number was last updated. ISO Date (string)
usage The number of calls made by the current holder of the phone number. integer
port_out_pin PIN number used when creating a port out request. string
type The phone number type. Includes: local or toll_free string
messaging_brand_id The 10DLC Brand ID assigned to the phone number. A verified 10DLC Brand is required to send messages on local numbers. string
messaging_campaign_id The 10DLC Campaign ID assigned to the phone number. A verified 10DLC Campaign is required to send messages on local numbers. string
location An object describing location information about the phone number. object
location.city The city of the phone number. string
location.region The region or state code of the phone number. string
location.postal_code The phone number zip/postal code. string
location.country The two-character country code of the phone number given in ISO Alpha-2 format. string
location.rate_center The rate center of the phone number, if applicable. string
location.lata The lata of the phone number, if applicable. string
location.latitude The latitude of the phone number. string
location.longitude the longitude of the phone number. string
estimated_active_date The estimated date when the phone number will be routed and ready for traffic. string
estimated_active_date_user_message Additional information about estimated time to route the number. This value is Null if the status is not reserved or routing. string
manage_capabilities An object that describes the phone number’s capabilities settings. object
manage_capabilities.voice An object that describes the phone number’s voice capability settings. object
manage_capabilities.voice.status Options: active, inactive, pending, unavailable, error. string
manage_capabilities.voice.is_modifiable Describes if the voice capability is fixed or can be turned on and off on this phone number. true means that voice can be turned on and off by toggling “status” to active/inactive. false means that the voice capability is unable to be turned on and off. boolean
manage_capabilities.sms An object that describes the phone number’s sms capability settings. object
manage_capabilities.sms.status Options: active, inactive, pending, unavailable, error. string
manage_capabilities.sms.is_modifiable Describes if the sms capability is fixed or can be turned on and off on this phone number. true means that sms can be turned on and off by toggling “status” to active/inactive. false means that the sms capability is unable to be turned on and off. boolean
manage_capabilities.mms An object that describes the phone number’s mms capability settings. object
manage_capabilities.mms.status Options: active, inactive, pending, unavailable, error. string
manage_capabilities.mms.is_modifiable Describes if the mms capability is fixed or can be turned on and off on this phone number. true means that mms can be turned on and off by toggling “status” to active/inactive. false means that the mms capability is unable to be turned on and off. boolean
manage_capabilities.cnam An object that describes the phone number’s cnam capability setting. If cnam.status is set to active, you may set the caller_id_name on the phone number. object
manage_capabilities.cnam.status Options: active, inactive, unavailable. string
manage_capabilities.cnam.is_modifiable Describes if the cnam capability is fixed or can be turned on and off on this phone number. true means that cnam can be turned on and off by toggling “status” to active/inactive. false means that the cnam capability is unable to be turned on and off. boolean

Example Response

{
  "no": "+19495551212",
  "formatted": "(949) 555-1212",
  "assigned_to": "CallFlows",
  "description": "Office Desk Phone",
  "capabilities": [
    "sms_inbound",
    "sms_outbound",
    "voice_inbound",
    "voice_outbound"
  ],
  "manage_capabilities": {
    "voice": {
      "status": "active",
      "is_modifiable": false
    },
    "cnam": {
      "status": "active",
      "is_modifiable": false
    },
    "sms": {
      "status": "active",
      "is_modifiable": true
    },
    "mms": {
      "status": "active",
      "is_modifiable": true
    }
  },
  "caller_id_name": "Bob Jones",
  "status": "routed",
  "usage": 100,
  "price": 1,
  "price_period": "day",
  "created_on": "2019-03-08T13:15:33.000Z",
  "updated_on": "2019-12-03T16:20:42.000Z",
  "type": "local",
  "location": {
    "country": "US",
    "region": "CA",
    "city": "Newport Beach",
    "postal_code": "92658",
    "rate_center": "NEWPORT BEACH",
    "lata": "730",
    "latitude": 33.61891009999998,
    "longitude": -117.9289469,
    "timezone": "America/Los_Angeles"
  },
  "messaging_brand_id": "BX0001",
  "messaging_campaign_id": "CX0001",
  "estimated_active_date": "2018-08-22T14:55:52.000Z",
  "estimated_active_date_user_message": null
}

Response Codes

Status Description
200 An array phone number objects.
4xx & 5xx General Error Codes
4xx & 5xx Phone Number Error Codes

Provision Phone Numbers

Purchase and assign phone numbers to CallFlows, ParkingLot, or Trunks/{trunk_id}.

The Provision request will accept the complete phone_numbers object that is returned in the GET /PhoneNumbers/Available response.

PLEASE NOTE: The manage_capabilities object enables you to turn on/off certain capabilities upon provisioning. If you do not include the manage_capabilities object in your provision request, the phone number(s) will automatically be provisioned with only the minimum capabilities (typically voice and sometimes cnam).

The maximum amount of numbers that can be provisioned at a time is 25. The Provision request will accept the complete phone_numbers object that is returned in the GET /PhoneNumbers/Available response.

POST /PhoneNumbers/{assigned_to}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
assigned_to The routing destination of the phone number: CallFlows, ParkingLot, Trunks/{trunk_id}. string (path) Yes
phone_numbers List of phone numbers. array (body) Yes
phone_numbers[i].no Phone number in E.164 format. string (body) Yes
phone_numbers[i].manage_capabilities An object that describes the phone number’s capabilities settings. If this object is not included, the minimum capabilities will be set. object No
phone_numbers[i].manage_capabilities.voice An object that describes the phone number’s voice capability settings. object No
phone_numbers[i].manage_capabilities.voice.status Options: active, inactive, pending, unavailable, error. string No
phone_numbers[i].manage_capabilities.voice.is_modifiable Describes if the voice capability is fixed or can be turned on and off on this phone number. true means that voice can be turned on and off by toggling “status” to active/inactive. false means that the voice capability is unable to be turned on and off. boolean No
phone_numbers[i].manage_capabilities.sms An object that describes the phone number’s sms capability settings. object No
phone_numbers[i].manage_capabilities.sms.status Options: active, inactive, pending, unavailable, error. string No
phone_numbers[i].manage_capabilities.sms.is_modifiable Describes if the sms capability is fixed or can be turned on and off on this phone number. true means that sms can be turned on and off by toggling “status” to active/inactive. false means that the sms capability is unable to be turned on and off. boolean No
phone_numbers[i].manage_capabilities.mms An object that describes the phone number’s mms capability settings. object No
phone_numbers[i].manage_capabilities.mms.status Options: active, inactive, pending, unavailable, error. string No
phone_numbers[i].manage_capabilities.mms.is_modifiable Describes if the mms capability is fixed or can be turned on and off on this phone number. true means that mms can be turned on and off by toggling “status” to active/inactive. false means that the mms capability is unable to be turned on and off. boolean No
phone_numbers[i].manage_capabilities.cnam An object that describes the phone number’s cnam capability setting. If cnam.status is set to active, you may set the caller_id_name on the phone number. object No
phone_numbers[i].manage_capabilities.cnam.status Options: active, inactive, unavailable. string No
phone_numbers[i].manage_capabilities.cnam.is_modifiable Describes if the cnam capability is fixed or can be turned on and off on this phone number. true means that cnam can be turned on and off by toggling “status” to active/inactive. false means that the cnam capability is unable to be turned on and off. boolean No

Example Request

curl -X POST \
  https://api.voxolo.gy/v1/PhoneNumbers/CallFlows \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "phone_numbers": [
      {
        "no": "+19495551212",
        "manage_capabilities": {
          "voice": {
            "status": "active",
            "is_modifiable": false
          },
          "sms": {
            "status": "active",
            "is_modifiable": true
          },
          "cnam": {
            "status": "active",
            "is_modifiable": false
          }
        }
      },
      {
        "no": "+19495551213",
        "manage_capabilities": {
          "voice": {
            "status": "active",
            "is_modifiable": false
          },
          "sms": {
            "status": "active",
            "is_modifiable": true
          },
          "cnam": {
            "status": "active",
            "is_modifiable": false
          }
        }
      }
    ]
  }'

Response

Property Description Type
assigned_to The routing destination of the phone number. Includes: CallFlows, ParkingLot, Trunks/{trunk_id}. string
phone_numbers List of phone numbers with provision status. array
phone_numbers[i].no Phone number in E.164 format. string
phone_numbers[i].formatted A human-friendly phone number format. string
phone_numbers[i].assigned_to The routing destination of the phone number: CallFlows, ParkingLot, Trunks/{trunk_id}. string
phone_numbers[i].description User-definable description of the phone number. string
phone_numbers[i].capabilities[] The list of capabilities that are currently active on the phone number. Possible returns: voice_inbound, voice_outbound, sms_inbound, sms_outbound, mms_inbound, mms_outbound, cnam. array
phone_numbers[i].description User-definable description of the phone number. string
phone_numbers[i].caller_id_name If cnam capable, the Caller ID Name of the phone number. string
phone_numbers[i].status The current status of the number. Returns: reserving, reserved, routing, routed, released, paused, reserved_routing_error, or error. string
phone_numbers[i].price The fee for using this number. Price is in USD. integer
phone_numbers[i].price_period The recurring period the price will be charged. Returns: day. string
phone_numbers[i].created_on The date/time this phone number object was created under this Application or Sub Account. NOTE: if the Phone Number is moved between Applications or Sub Accounts, this date will be updated. ISO Date (string)
phone_numbers[i].updated_on The date/time this phone number was last updated. ISO Date (string)
phone_numbers[i].usage The number of calls made by the current holder of the phone number. integer
phone_numbers[i].type The phone number type. Includes: local or toll_free string
phone_numbers[i].messaging_brand_id The 10DLC Brand ID assigned to the phone number. A verified 10DLC Brand is required to send messages on local numbers. string
phone_numbers[i].messaging_campaign_id The 10DLC Campaign ID assigned to the phone number. A verified 10DLC Campaign is required to send messages on local numbers. string
phone_numbers[i].location An object describing location information about the phone number. object
phone_numbers[i].location.city The city of the phone number. string
phone_numbers[i].location.region The region or state code of the phone number. string
phone_numbers[i].location.postal_code The phone number zip/postal code. string
phone_numbers[i].location.country The two-character country code of the phone number given in ISO Alpha-2 format. string
phone_numbers[i].location.rate_center The rate center of the phone number, if applicable. string
phone_numbers[i].location.lata The lata of the phone number, if applicable. string
phone_numbers[i].location.latitude The latitude of the phone number. string
phone_numbers[i].location.longitude the longitude of the phone number. string
phone_numbers[i].estimated_active_date The estimated date when the phone number will be routed and ready for traffic. string
phone_numbers[i].manage_capabilities An object that describes the phone number’s capabilities settings. object
phone_numbers[i].manage_capabilities.voice An object that describes the phone number’s voice capability settings. object
phone_numbers[i].manage_capabilities.voice.status Options: active, inactive, pending, unavailable, error. string
phone_numbers[i].manage_capabilities.voice.is_modifiable Describes if the voice capability is fixed or can be turned on and off on this phone number. true means that voice can be turned on and off by toggling “status” to active/inactive. false means that the voice capability is unable to be turned on and off. boolean
phone_numbers[i].manage_capabilities.sms An object that describes the phone number’s sms capability settings. object
phone_numbers[i].manage_capabilities.sms.status Options: active, inactive, pending, unavailable, error. string
phone_numbers[i].manage_capabilities.sms.is_modifiable Describes if the sms capability is fixed or can be turned on and off on this phone number. true means that sms can be turned on and off by toggling “status” to active/inactive. false means that the sms capability is unable to be turned on and off. boolean
phone_numbers[i].manage_capabilities.mms An object that describes the phone number’s mms capability settings. object
phone_numbers[i].manage_capabilities.mms.status Options: active, inactive, pending, unavailable, error. string
phone_numbers[i].manage_capabilities.mms.is_modifiable Describes if the mms capability is fixed or can be turned on and off on this phone number. true means that mms can be turned on and off by toggling “status” to active/inactive. false means that the mms capability is unable to be turned on and off. boolean
phone_numbers[i].manage_capabilities.cnam An object that describes the phone number’s cnam capability setting. If cnam.status is set to active, you may set the caller_id_name on the phone number. object
phone_numbers[i].manage_capabilities.cnam.status Options: active, inactive, unavailable. string
phone_numbers[i].manage_capabilities.cnam.is_modifiable Describes if the cnam capability is fixed or can be turned on and off on this phone number. true means that cnam can be turned on and off by toggling “status” to active/inactive. false means that the cnam capability is unable to be turned on and off. boolean

Example Response

{
  "assigned_to": "CallFlows",
  "phone_numbers": [
    {
      "no": "+19495551212",
      "formatted": "(949) 555-1212",
      "assigned_to": "CallFlows",
      "status": "routed",
      "type": "local",
      "description": "New Phone Number",
      "messaging_brand_id": null,
      "messaging_campaign_id": null,  
      "created_on": "2021-03-16T17:51:57.000Z",
      "updated_on": "2021-03-16T17:51:57.000Z",
      "capabilities": [
        "voice_inbound",
        "voice_outbound",
        "cnam",
        "sms_inbound",
        "sms_outbound"
      ],
      "caller_id_name": "NAMEGOESHERE",
      "manage_capabilities": {
        "voice": {
          "status": "active",
          "is_modifiable": false
        },
        "sms": {
          "status": "active",
          "is_modifiable": true
        },
        "mms": {
          "status": "inactive",
          "is_modifiable": true
        },
        "cnam": {
          "status": "active",
          "is_modifiable": false
        }
      },
      "location": {
        "country": "US",
        "region": "CA",
        "city": "Newport Beach",
        "postal_code": "92658",
        "rate_center": "NEWPORT BEACH",
        "lata": "738",
        "latitude": 37.64099160460602,
        "longitude": -120.758966617446,
        "timezone": "America/Los_Angeles"
      },
      "price": 0.0328,
      "price_period": "day",
      "estimated_active_date_user_message": "immediately"
    },
    {
      "no": "+19495551213",
      "formatted": "(949) 555-1213",
      "assigned_to": "CallFlows",
      "status": "routed",
      "type": "local",
      "description": "New Phone Number",
      "messaging_brand_id": null,
      "messaging_campaign_id": null,  
      "created_on": "2021-03-16T17:51:57.000Z",
      "updated_on": "2021-03-16T17:51:57.000Z",
      "capabilities": [
        "voice_inbound",
        "voice_outbound",
        "cnam",
        "sms_inbound",
        "sms_outbound",
        "mms_inbound",
        "mms_outbound"
      ],
      "caller_id_name": "NAMEGOESHERE",
      "manage_capabilities": {
        "voice": {
          "status": "active",
          "is_modifiable": false
        },
        "sms": {
          "status": "active",
          "is_modifiable": true
        },
        "mms": {
          "status": "active",
          "is_modifiable": true
        },
        "cnam": {
          "status": "active",
          "is_modifiable": false
        }
      },
      "location": {
        "country": "US",
        "region": "CA",
        "city": "Newport Beach",
        "postal_code": "92658",
        "rate_center": "NEWPORT BEACH",
        "lata": "730",
        "latitude": 33.61891009999998,
        "longitude": -117.9289469,
        "timezone": "America/Los_Angeles"
      },
      "price": 0.0328,
      "price_period": "day",
      "estimated_active_date": "2021-03-16T17:44:16.429.000Z"
    }
  ]
}

Response Codes

Status Description
200 Returns all the phone numbers under this assigned_to.
4xx & 5xx General Error Codes
4xx & 5xx Phone Number Error Codes

Update Phone Numbers

Update a phone number’s description and/or caller_id_name.

PUT /PhoneNumbers/{phone_number}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
no Phone number in E.164 format. string Yes
description User-definable description of the phone number. string No
caller_id_name If cnam capable, the name of the phone number’s owner. Max 15 characters. string No
port_out_pin The PIN used to verify a port-out request when porting a phone number away from Voxology. A port-out PIN may either be set on the phone number or on the Sub Account or Application as a default. If set on the phone number, it will take president over the default. The port out PIN must be an alpha numeric value with no more than 10 characters. To remove a port-out PIN, set it to null, an empty string will not work. string No
messaging_brand_id The 10DLC Brand ID assigned to the phone number. A verified 10DLC Brand is required to send Messages on local numbers. string No
messaging_campaign_id The 10DLC Campaign ID assigned to the phone number. A verified 10DLC Campaign is required to send Messages on local numbers. A Campaign must be in an active state before it can be assigned to a phone number. string No
manage_capabilities An object that describes the phone number’s capabilities settings. If this object is not included, the minimum capabilities will be set. object No
manage_capabilities.voice An object that describes the phone number’s voice capability settings. object No
manage_capabilities.voice.status Options: active, inactive, pending, unavailable, error. string No
manage_capabilities.voice.is_modifiable Describes if the voice capability is fixed or can be turned on and off on this phone number. true means that voice can be turned on and off by toggling “status” to active/inactive. false means that the voice capability is unable to be turned on and off. This field cannot be modified. boolean No
manage_capabilities.sms An object that describes the phone number’s sms capability settings. object No
manage_capabilities.sms.status Options: active, inactive, pending, unavailable, error. string No
manage_capabilities.sms.is_modifiable Describes if the sms capability is fixed or can be turned on and off on this phone number. true means that sms can be turned on and off by toggling “status” to active/inactive. false means that the sms capability is unable to be turned on and off. This field cannot be modified. boolean No
manage_capabilities.mms An object that describes the phone number’s mms capability settings. object No
manage_capabilities.mms.status Options: active, inactive, pending, unavailable, error. string No
manage_capabilities.mms.is_modifiable Describes if the mms capability is fixed or can be turned on and off on this phone number. true means that mms can be turned on and off by toggling “status” to active/inactive. false means that the mms capability is unable to be turned on and off. This field cannot be modified. boolean No
manage_capabilities.cnam An object that describes the phone number’s cnam capability setting. If cnam.status is set to active, you may set the caller_id_name on the phone number. object No
manage_capabilities.cnam.status Options: active, inactive, unavailable. string No
manage_capabilities.cnam.is_modifiable Describes if the cnam capability is fixed or can be turned on and off on this phone number. true means that cnam can be turned on and off by toggling “status” to active/inactive. false means that the cnam capability is unable to be turned on and off. This field cannot be modified. boolean No

Example Request

curl -X PUT \
  https://api.voxolo.gy/v1/PhoneNumbers/%2B19495551212 \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "description": "Mobile Phone",
    "caller_id_name": "Jane Doe",
    "messaging_brand_id": "BX0001",
    "messaging_campaign_id": "CX0001",
    "manage_capabilities": {
        "voice": {
          "status": "active",
          "is_modifiable": false
        },
        "sms": {
          "status": "active",
          "is_modifiable": true
        },
        "mms": {
          "status": "inactive",
          "is_modifiable": true
        },
        "cnam": {
          "status": "active",
          "is_modifiable": false
        }
      }
  }'

Response

Property Description Type
no The phone number in E.164 format. string
formatted A human-friendly phone number format. string
assigned_to The routing destination of the phone number: CallFlows, ParkingLot, Trunks/{trunk_id}. null for available numbers. null
error Any error that occurred when provisioning the number. string
capabilities Features supported by the phone number: voice_inbound, voice_outbound, sms_inbound, sms_outbound, mms_inbound, mms_outbound, cnam array
description User-definable description of the phone number. string
caller_id_name If cnam capable, the name of the phone number’s owner. string
status The current status of the number. string
price The fee for using this number. integer
price_period The recurring period the price will be charged: day. string
created_on The date/time this phone number object was created under this Application or Sub Account. NOTE: if the Phone Number is moved between Applications or Sub Accounts, this date will be updated. ISO Date (string)
updated_on The date/time this phone number was last updated. ISO Date (string)
usage The number of calls made for the lifetime of the phone number. integer
type The phone number type. Includes: local or toll_free string
messaging_brand_id The 10DLC Brand ID assigned to the phone number. A verified 10DLC Brand is required to send Messages on local numbers. string
messaging_campaign_id The 10DLC Campaign ID assigned to the phone number. A verified 10DLC Campaign is required to send Messages on local numbers. string
location An object describing location information about the phone number. object
location.city The city of the phone number. string
location.region The region or state code of the phone number. string
location.postal_code The phone number zip/postal code. string
location.country The two-character country code of the phone number given in ISO Alpha-2 format. string
location.rate_center The rate center of the phone number, if applicable. string
location.lata The lata of the phone number, if applicable. string
location.latitude The latitude of the phone number. string
location.longitude the longitude of the phone number. string
estimated_active_date The estimated date when the phone number will be routed and ready for traffic. string
manage_capabilities An object that describes the phone number’s capabilities settings. object
manage_capabilities.voice An object that describes the phone number’s voice capability settings. object
manage_capabilities.voice.status Options: active, inactive, pending, unavailable, error. string
manage_capabilities.voice.is_modifiable Describes if the voice capability is fixed or can be turned on and off on this phone number. true means that voice can be turned on and off by toggling “status” to active/inactive. false means that the voice capability is unable to be turned on and off. boolean
manage_capabilities.sms An object that describes the phone number’s sms capability settings. object
manage_capabilities.sms.status Options: active, inactive, pending, unavailable, error. string
manage_capabilities.sms.is_modifiable Describes if the sms capability is fixed or can be turned on and off on this phone number. true means that sms can be turned on and off by toggling “status” to active/inactive. false means that the sms capability is unable to be turned on and off. boolean
manage_capabilities.mms An object that describes the phone number’s mms capability settings. object
manage_capabilities.mms.status Options: active, inactive, pending, unavailable, error. string
manage_capabilities.mms.is_modifiable Describes if the mms capability is fixed or can be turned on and off on this phone number. true means that mms can be turned on and off by toggling “status” to active/inactive. false means that the mms capability is unable to be turned on and off. boolean
manage_capabilities.cnam An object that describes the phone number’s cnam capability setting. If cnam.status is set to active, you may set the caller_id_name on the phone number. object
manage_capabilities.cnam.status Options: active, inactive, unavailable. string
manage_capabilities.cnam.is_modifiable Describes if the cnam capability is fixed or can be turned on and off on this phone number. true means that cnam can be turned on and off by toggling “status” to active/inactive. false means that the cnam capability is unable to be turned on and off. boolean

Example Response

{
  "no": "+19495551212",
  "formatted": "(949) 555-1212",
  "assigned_to": "CallFlows",
  "description": "Office Desk Phone",
  "capabilities": [
    "cnam",
    "sms_inbound",
    "sms_outbound",
    "voice_inbound",
    "voice_outbound"
  ],
  "manage_capabilities": {
    "voice": {
      "status": "active",
      "is_modifiable": false
    },
    "cnam": {
      "status": "active",
      "is_modifiable": false
    },
    "sms": {
      "status": "active",
      "is_modifiable": true
    },
    "mms": {
      "status": "inactive",
      "is_modifiable": true
    }
  },
  "caller_id_name": "Bob Jones",
  "status": "routed",
  "usage": 100,
  "price": 1,
  "price_period": "day",
  "created_on": "2019-03-08T13:15:33.000Z",
  "updated_on": "2019-12-03T16:20:42.000Z",
  "type": "local",
  "location": {
    "city": "Trabuco Canyon",
    "region": "CA",
    "postal_code": "92678",
    "country": "US",
    "rate_center": "TRABUCO CANYON",
    "lata": "730",
    "latitude": 33.65252140000001,
    "longitude": -117.6231047
  },
  "messaging_brand_id": "BX0001",
  "messaging_campaign_id": "CX0001", 
  "estimated_active_date": "2019-04-10T10:01:56.000Z"
}

Response Codes

Status Description
200 The details of the updated phone number.
4xx & 5xx General Error Codes
4xx & 5xx Phone Number Error Codes

Move Phone Numbers

Move numbers from application (parent) to sub account application (child), from sub account application (child) to application (parent), or between sub account applications. Numbers can only be moved within the same subtree.

PUT /PhoneNumbers/Move/{assigned_to}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
assigned_to The routing destination of the phone number: CallFlows, ParkingLot, Trunks/{trunk_id}. Default is CallFlows string (path) No
app_id The ID of the application to which you are moving the phone number(s). This parameter is required when moving a phone number from a sub account (child) to parent application. string (body) Conditional
subaccount_id The ID of the sub account to which you are moving the phone number(s). This parameter is required when moving phone numbers from the parent application to the sub account (child), or between two sub accounts (siblings) under the same parent application. integer (body) Conditional
phone_numbers List of phone numbers array (body) Yes
phone_numbers[i].no Phone number in E.164 format. string (body) Yes

Example Request // Moving from application (parent) to sub account (child)

curl -X PUT \
  https://api.voxolo.gy/v1/PhoneNumbers/Move/CallFlows \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "subaccount_id": "YOUR_SUB_ACCOUNT_ID",
    "phone_numbers": [
      {
        "no": "+19495551212"
      },
      {
        "no": "+19495551213"
      }
    ]
  }'

Example Request // Moving from sub account (child) to application (parent)

curl -X PUT \
  https://api.voxolo.gy/v1/SubAccounts/YOUR_SUB_ACCOUNT_ID/PhoneNumbers/Move/CallFlows \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "app_id": "YOUR_PARENT_ACCOUNT_ID",
    "phone_numbers": [
      {
        "no": "+19495551212"
      },
      {
        "no": "+19495551213"
      }
    ]
  }'

Example Request // Moving from sub account to sub account (siblings)

curl -X PUT \
  https://api.voxolo.gy/v1/SubAccounts/YOUR_SIBLING_SUB_ACCOUNT_ID/PhoneNumbers/Move/CallFlows \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "subaccount_id": "YOUR_SIBLING_SUB_ACCOUNT_ID",
    "phone_numbers": [
      {
        "no": "+13231234567"
      },
      {
        "no": "+13237654321"
      }
    ]
  }'

Response

Property Description Type
phone_numbers List of phone numbers that the user attempted to move. array
phone_numbers[i].no Phone number in E.164 format. string
phone_numbers[i].formatted A human-friendly phone number format. string
phone_numbers[i].error Only included if move fails string

Example Response

[
  {
    "no": "+19495551212",
    "formatted": "(949) 555-1212"
  },
  {
    "no": "+19495553434",
    "formatted": "(949) 555-3434"
  }
]

Response Codes

Status Description
200 List of phone numbers.
4xx & 5xx General Error Codes
4xx & 5xx Phone Number Error Codes

Release Phone Numbers

Permanently releases phone number(s) from your application or sub account. If you prefer to hang on to the phone number(s), you could instead assign them to your ParkingLot.

DELETE /PhoneNumbers/{assigned_to}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
assigned_to The routing destination of the phone number: CallFlows, ParkingLot, Trunks/{trunk_id}. string (path) Yes
phone_numbers List of phone numbers. array (body) Yes
phone_numbers[i].no E.164 formatted phone number. string (body) Yes

Example Request

curl -X DELETE \
  https://api.voxolo.gy/v1/PhoneNumbers/CallFlows \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "phone_numbers": [
      {
        "no": "+19495551212"
      },
      {
        "no": "+19495551213"
      },
      {
        "no": "+19495551214"
      }
    ]
  }'

Note: The API will accept the complete phone_numbers object returned by GET /PhoneNumbers/{assigned_to}. However, only no is required.

Response

No content.

Response Codes

Status Description
204 No content on success.
4xx & 5xx General Error Codes
4xx & 5xx Phone Number Error Codes

Phone Number Information

Phone Number Information Lookup

Returns information about a phone number, including a phone number’s location, caller id name (cnam), carrier, and type (landline, mobile, etc.). Also supports integrations with 3rd party lookup services who can provide reverse phone number lookups and a phone number’s reputation score.

GET /PhoneNumberInformation/{phone_number}?{query_string}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
phone_number Accepts a phone number in E.164 format (example: +17145551212). string (path) Yes
include Information to include in the phone number search. Each value has a charge associated with it. See our pricing page for details. We do not include this information in a toll-free search. Accepts: cnam, carrier, and location. string (query) Yes
integrations 3rd party lookups that each have a charge associated with them. See our pricing page for details. Accepts: trestle_reverse_phone string (query) No

INTEGRATIONS DETAILS

Integration Parameter Description Provider
trestle_reverse_phone trestle Reverse Phone Lookup enables you to “get an owner’s current name, address, demographics, phone details, associated people, and relatives.” A full description of the return data can be found here trestle

Example Request

curl -X GET \
  'https://api.voxolo.gy/v1/PhoneNumberInformation/+1323214321?include=cnam,carrier,location&integrations=trestle_reverse_phone' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

Property Description Type
country_code The two-character country code of the phone number given in ISO Alpha-2 format. string
phone_number The searched for phone number in E.164 format. string
phone_number_formatted The searched for phone number in human-friendly format. string
carrier An object describing the carrier information about the number. object
carrier.carrier_name The carrier name of the phone number. string
carrier.phone_number_type The phone number type. Includes: mobile, landline, voip, landline/voip, null string
cnam An object describing the Caller ID name of the phone number. object
cnam.caller_name If cnam capable, the Caller ID Name of the phone number. Possibly null. object
location An object describing location information about the phone number object
location.time_zone The timezone of the phone number string
location.city The city of the phone number. string
location.region The region or state code of the phone number. string
location.postal_code The phone number zip/postal code. string
location.country The two-character country code of the phone number given in ISO Alpha-2 format. string
location.rate_center The rate center of the phone number, if applicable. string
location.lata The lata of the phone number, if applicable. string
location.latitude The latitude of the phone number. string
location.longitude the longitude of the phone number. string
integrations An object that contains information returned from 3rd party APIs. object

Example Response

{
  "country_code": "US",
  "phone_number": "+13238732860",
  "phone_number_formatted": "(323) 873-2860",
  "carrier": {
    "error": null,
    "carrier_name": "BANDWIDTH.COM CLEC  LLC - CA",
    "phone_number_type": "voip"
  },
  "cnam": {
    "error": null,
    "caller_name": "JOHN DOE"
  },
  "location": {
    "time_zone": "America/Los_Angeles",
    "latitude": 34.10129344875499,
    "longitude": -118.324525950829,
    "country": "US",
    "rate_center": "LOS ANGELES DA 14:Hollywood",
    "city": "Los Angeles:DA 14",
    "postal_code": "90028",
    "lata": "730",
    "region": "CA"
  },
  "integrations": {
    "trestle_reverse_phone": {
      "current_addresses": [
        {
          "id": "Location.fdea85c1-7ed2-420e-8af1-86ce685009f8",
          "location_type": "PostalCode",
          "street_line_1": null,
          "street_line_2": null,
          "city": "Los Angeles",
          "postal_code": "90011",
          "zip4": null,
          "state_code": "CA",
          "country_code": "US",
          "lat_long": {
            "latitude": 34.0071,
            "longitude": -118.2585,
            "accuracy": "PostalCode"
          },
          "is_active": null,
          "delivery_point": null,
          "link_to_person_start_date": null
        }
      ],
      "belongs_to": {},
      "warnings": {},
      "historical_addresses": {},
      "carrier": "Bandwidth SMSEnabled",
      "associated_people": {},
      "is_valid": true,
      "line_type": "NonFixedVOIP",
      "phone_number": "3238732860",
      "alternate_phones": {},
      "id": "Phone.48796fef-a2e0-4b08-cfe3-bc7128b78216",
      "country_calling_code": "1"
    }
  },
  "error": null
}

Response Codes

Status Description
200 Successful request.
4xx & 5xx General Error Codes

Port Requests

Use these methods to initiate requests to port numbers from another provider into Voxology’s platform. There are separate methods to port local and hosted SMS (SMS-enabled landlines) numbers.

Create Hosted SMS Port Request

Initiates a request to port existing messaging capabilities of a phone number, or enable messaging capabilities on a landline, while leaving the voice function with the number’s current provider.

POST /PortRequests/HostedSMS

AUTHENTICATION TYPE

API Key (Application-level)

REQUEST

Parameter Description Type Required
desired_due_date Requested date for the port to complete. This is passed on to the losing vendor in the port request, but they are not beholden to it. string Yes
loa_file Base64 encoded string of an uploaded Letter of Authorization stating you have authority to transfer one or multiple phone numbers to a new vendor. string No
phone_numbers An array of phone numbers to be included in the request to port messaging capabilities to Voxology. array No
phone_numbers[i].no A phone number to port messaging in E164 format. string No

Example Request

curl -X POST \
  https://api.voxolo.gy/v1/PortRequests/HostedSMS \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
   -d '{
    "desired_due_date": "2024-01-01",
    "loa_file": "YWtqaHNkamZoc2Fka2puZ2ZhLGt...",
    "phone_numbers": [
        {
            "no": "+15551234567"
        }
    ]
}'

Response

Property Description Type
id Unique ID for this port request. array
loa_file Base64 encoded string of an uploaded Letter of Authorization stating you have authority to transfer one or multiple phone numbers to a new vendor. string
created_on The timestamp of when the port request was first submitted. ISO date string
updated_on The timestamp of when the port request was last updated. ISO date string
phone_numbers An array of phone numbers included in the port request to enable messaging with Voxology. array
phone_numbers[i].no A phone number included in the port request in E164 format. string
phone_numbers[i].status The current status of the port request for this specific number. Includes pending, completed, and rejected. string
phone_numbers[i].reject_reason When applicable, the provided reason for why we were unable to port the messaging capability on this number. string

Example Response

{
    "id": "00001112222",
    "desired_due_date": "2024-01-01",
    "loa_file": "YWtqaHNkamZoc2Fka2puZ2ZhLGt...",
    "created_on": "2023-01-01T22:25:39.000Z",
    "updated_on": "2023-01-01T22:25:39.000Z",
    "phone_numbers": [
        {
            "no": "+15551234567",
            "status": "pending",
            "reject_reason": "",
        }
    ]
}

Response Codes

Status Description
200 Returns port request details
4xx & 5xx General Error Codes

Create Local Port Request

Initiates a request to port local phone numbers into Voxology.

POST /PortRequests/Local

AUTHENTICATION TYPE

API Key (Application-level)

REQUEST

Parameter Description Type Required
desired_due_date Requested date for the port to complete. This is passed on to the losing vendor in the port request, but they are not beholden to it. string Yes
loa_file Base64 encoded string of an uploaded Letter of Authorization stating you have authority to transfer one or multiple phone numbers to a new vendor. string Yes
bill_file Base64 encoded string of an uploaded Phone Bill proving ownership of the phone numbers in this port request. string Yes
phone_numbers The list of phone numbers, with account information for the losing vendor, to be included in the port request. array Yes
phone_numbers[i].no A phone number to port in E164 format. string Yes
phone_numbers[i].account_name Name of the account owner. string Yes
phone_numbers[i].account_password Authentication key for the account, if applicable. string No
phone_numbers[i].account_telephone_number Primary contact phone number on the account. string Yes
phone_numbers[i].account_number Unique ID for the account with the losing vendor, if applicable. string No
phone_numbers[i].account_pin Access PIN used to authorize the port request. This must match the PIN set on the phone number on the losing vendor. string Yes
phone_numbers[i].address Mailing address listed on the account with the losing vendor. object Yes
phone_numbers[i].address.name Name registered to the mailing address. string Yes
phone_numbers[i].address.street Street number and name. string Yes
phone_numbers[i].address.city City of address. string Yes
phone_numbers[i].address.region State or region. string Yes
phone_numbers[i].address.postal_code 5 digit postal or zip code. string Yes
phone_numbers[i].address.country 2 character country code. string Yes
phone_numbers[i].desired_capabilites Capabilities, beyond voice, desired on the phone number, such as SMS and MMS. These can also be enabled after the port is completed. string[] No

Example Request

curl -X POST \
  https://api.voxolo.gy/v1/PortRequests/Local \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
   -d '{
    "desired_due_date": "2024-01-01",
    "loa_file": "YWtqaHNkamZoc2Fka2puZ2ZhLGt...",
    "bill_file": "VGhpcyBpcyByYW5kb20gd29yZtH...",
    "phone_numbers": [
        {
            "no": "+15551234567",
            "account_name": "John Smith",
            "account_password": "not_my_password",
            "account_telephone_number": "+15559876543",
            "account_number": "000111222",
            "account_pin": "1234",
            "address": {
                "name": "Good Business Inc",
                "street": "123 Main St.",
                "city": "Los Angeles",
                "region": "CA",
                "postal_code": "90001",
                "country": "US"
            },
            "desired_capabilities": [ "SMS", "MMS" ]
        }
    ]
}'

Response

Property Description Type
id Unique ID for this port request. string
desired_due_date Requested date for the port to complete. This is passed on to the losing vendor in the port request, but they are not beholden to it. string
loa_file Base64 encoded string of an uploaded Letter of Authorization stating you have authority to transfer one or multiple phone numbers to a new vendor. string
bill_file Base64 encoded string of an uploaded Letter of Authorization stating you have authority to transfer one or multiple phone numbers to a new vendor. string
phone_numbers The list of phone numbers, with account information for the losing vendor, to be included in the port request. array
phone_numbers[i].no A phone number to port in E164 format. string
phone_numbers[i].account_name Name of the account owner. string
phone_numbers[i].account_password Authentication key for the account, if applicable. string
phone_numbers[i].account_telephone_number Primary contact phone number on the account. string
phone_numbers[i].account_number Unique ID for the account with the losing vendor, if applicable. string
phone_numbers[i].account_pin Access PIN used to authorize the port request. This must match the PIN set on the phone number on the losing vendor. string
phone_numbers[i].address Mailing address listed on the account with the losing vendor. object
phone_numbers[i].address.name Name registered to the mailing address. string
phone_numbers[i].address.street Street number and name. string
phone_numbers[i].address.city City of address. string
phone_numbers[i].address.region State or region. string
phone_numbers[i].address.postal_code 5 digit postal or zip code. string
phone_numbers[i].address.country 2 character country code. string
phone_numbers[i].desired_capabilites Capabilities, beyond voice, desired on the phone number, such as SMS and MMS. These can also be enabled after the port is completed. string[]
phone_numbers[i].status Current state of the port. Includes: ‘pending’, 'complete’, 'canceled’, 'rejected’ string
phone_numbers[i].reject_reason The provided reason the port request was rejected, when applicable. string
phone_numbers[i].foc_date The date the port request will complete. The assignment of a FOC date indactes the port has been approved. string

Example Response

{
     "desired_due_date": "2024-01-01",
    "loa_file": "YWtqaHNkamZoc2Fka2puZ2ZhLGt...",
    "bill_file": "VGhpcyBpcyByYW5kb20gd29yZtH...",
    "phone_numbers": [
        {
            "no": "+15551234567",
            "account_name": "John Smith",
            "account_password": "not_my_password",
            "account_telephone_number": "+15559876543",
            "account_number": "000111222",
            "account_pin": "1234",
            "address": {
                "name": "Good Business Inc",
                "street": "123 Main St.",
                "city": "Los Angeles",
                "region": "CA",
                "postal_code": "90001",
                "country": "US"
            },
            "desired_capabilities": [ "SMS", "MMS" ],
            "status": "pending",
            "reject_reason": "",
            "foc_date": "2024-01-08"
        }
    ]
}

Response Codes

Status Description
200 Returns port request details
4xx & 5xx General Error Codes

Queues

List Queues

Returns a list of Call Queues.

GET /LiveCalls/Queues

Authentication Type

API Key (Application-level)

Request

No Request Body

Example Request

curl -X GET \
  https://api.voxolo.gy/v1/LiveCalls/Queues \
  -H 'Cache-Control: no-cache' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

Property Description Type
queues A list of available queues. array
queues.name The queue’s unique name. string
queues.hold_times Hold time stats for the queue. object
queues.hold_times.estimated The estimated hold time in seconds. integer

Example Response

{
  "queues": [
    {
      "name": "name_of_queue",
      "hold_times": {
        "estimated": 1.234
      }
    }
  ]
}

Response Codes

Status Description
200 Returns a list of queues.
4xx & 5xx General Error Codes
4xx & 5xx Queue Error Codes

View Queue Details

Returns the details of a queue.

GET /LiveCalls/Queues/{queue_name}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
queue_name Name of the queue. string (path) Yes

Example Request

curl -X GET \
  https://api.voxolo.gy/v1/LiveCalls/Queues/name_of_queue \
  -H 'Cache-Control: no-cache' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

Property Description Type
name The queue’s unique name. string
hold_times Hold time stats for the queue. object
hold_times.estimated The estimated hold time in seconds. integer

Example Response

{
  "name": "name_of_queue",
  "hold_times": {
    "estimated": 1.234
  }
}

Response Codes

Status Description
200 Returns queue detail.
4xx & 5xx General Error Codes
4xx & 5xx Queue Error Codes

List Queued Calls

Returns all of the calls in the specified queue.

GET /LiveCalls/Queues/{queue_name}/Calls

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
queue_name Name of the queue. string (path) Yes

Example Request

curl -X GET \
  https://api.voxolo.gy/v1/LiveCalls/Queues/name_of_queue/Calls \
  -H 'Cache-Control: no-cache' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

Property Description Type
calls An array of queued calls, sorted from first to last. array
calls.call The call object. object
calls.call.id The unique ID for the call. string
calls.call.no The phone number for the call. string
calls.call.caller_id_no The phone number provisioned to the application. string
calls.queued_on The date and time the call was queued in ISO 8601. string
calls.hold_time The number of seconds the call has been queued. integer
calls.position The position of the call in the queue. integer
queue_name The name of the queue. string
hold_times A group of hold time data. object
hold_times.average The average hold time of all current calls. This is not estimated hold time. integer
hold_times.least The lowest current hold time. integer
hold_times.greatest The highest current hold time. integer

Example Response

{
  "calls": [
    {
      "call": {
        "id": "1234@5678",
        "no": "+17145551212",
        "caller_id_no": "+19495551212"
      },
      "queued_on": "2017-02-16T17:16:11.597Z",
      "hold_time": 30.123,
      "position": 1
    }
  ],
  "queue_name": "name_of_queue",
  "hold_times": {
    "average": 1.23,
    "least": 10.123,
    "greatest": 45.678
  }
}

Response Codes

Status Description
200 A list of queued calls.
4xx & 5xx General Error Codes
4xx & 5xx Queue Error Codes

View Queued Call Detail

Returns the details of a queued call.

GET /LiveCalls/Queues/{queue_name}/Calls/{call_id}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
queue_name Name of the queue. string (path) Yes
call_id ID of the call. string (path) Yes

Example Request

curl -X GET \
  https://api.voxolo.gy/v1/LiveCalls/Queues/name_of_queue/Calls/abc123 \
  -H 'Cache-Control: no-cache' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

Property Description Type
call The call object. object
call.id The classic call ID. string
call.no The phone number for the call. string
call.caller_id_no The phone number provisioned to the application. string
queued_on The date and time the call was queued in ISO 8601. string
hold_time The number of seconds the call has been queued. integer
position The position of the call in the queue. integer

Example Response

{
  "call": {
    "id": "1234@5678",
    "no": "+17145551212",
    "caller_id_no": "+19495551212"
  },
  "queued_on": "2017-02-16T17:16:11.597Z",
  "hold_time": 30.123,
  "position": 3
}

Response Codes

Status Description
200 Returns the queued call detail.
4xx & 5xx General Error Codes
4xx & 5xx Queue Error Codes

Peek at Queue

Returns the next call in the queue. Peek does not remove the queued call.

GET /LiveCalls/Queues/{queue_name}/Peek

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
queue_name Name of the queue. string (path) Yes

Example Request

curl -X GET \
  https://api.voxolo.gy/v1/LiveCalls/Queues/name_of_queue/Peek \
  -H 'Cache-Control: no-cache' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

Property Description Type
call The call object. object
call.id The classic call ID. string
call.no The phone number for the call. string
call.caller_id_no The phone number provisioned to the application. string
queued_on The date and time the call was queued in ISO 8601. string
hold_time The number of seconds the call has been queued. integer
position The position of the call relevant to other calls in the queue. integer

Example Response

{
  "call": {
    "id": "1234",
    "no": "9991112222"
  },
  "queued_on": "2016-09-15T15:53:00",
  "hold_time": 60,
  "position": 5
}

Response Codes

Status Description
200 Returns the queued call’s details.
4xx & 5xx General Error Codes
4xx & 5xx Queue Error Codes

Poll Queue

Returns the next call from the queue. The call will then continue to execute its regular call flow.

This request will block/long poll for up to 15 seconds on an empty queue. To avoid blocking, PEEK then POLL.

GET /LiveCalls/Queues/{queue_name}/Poll

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
queue_name Name of the queue. string (path) Yes

Example Request

curl -X GET \
  https://api.voxolo.gy/v1/LiveCalls/Queues/name_of_queue/Poll \
  -H 'Cache-Control: no-cache' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

Property Description Type
call The call object. object
call.id The classic call ID. string
call.no The phone number for the call. string
call.caller_id_no The phone number provisioned to the application. string
queued_on The date and time the call was queued in ISO 8601. string
hold_time The number of seconds the call has been queued. integer
position The position of the call relevant to other calls in the queue. integer

Example Response

{
  "call": {
    "id": "1234",
    "no": "9991112222"
  },
  "queued_on": "2016-09-15T15:53:00",
  "hold_time": 60,
  "position": 5
}

Response Codes

Status Description
200 Returns the dequeued call’s details.
4xx & 5xx General Error Codes
4xx & 5xx Queue Error Codes

Remove Queued Call

Deletes the specified call from the queue, regardless of position. When the call exits, it will continue its normal call flow.

DELETE /LiveCalls/Queues/{queue_name}/Calls/{call_id}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
queue_name Name of the queue. string (path) Yes
call_id ID of the call. string (path) Yes

Example Request

curl -X DELETE \
  https://api.voxolo.gy/v1/LiveCalls/Queues/name_of_queue/Calls/abc123 \
  -H 'Cache-Control: no-cache' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

No Response Body

Response Codes

Status Description
204 No content on success.
4xx & 5xx General Error Codes
4xx & 5xx Queue Error Codes

Delete Queue

Deletes the specified queue. Any queued calls will be released to continue their regular call flows. A deleted queue will not appear in the list of queues. To recreate the queue, simply offer a call.

DELETE /LiveCalls/Queues/{queue_name}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
queue_name Name of the queue. string (path) Yes

Example Request

curl -X DELETE \
  https://api.voxolo.gy/v1/LiveCalls/Queues/name_of_queue \
  -H 'Cache-Control: no-cache' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

Property Description Type
name The queue’s unique name. string
hold_times Hold time stats for the queue. object
hold_times.estimated The estimated hold time in seconds. integer

Example Response

{
  "name": "name_of_queue",
  "hold_times": {
    "estimated": 360
  }
}

Response Codes

Status Description
200 Returns the deleted queue’s details.
4xx & 5xx General Error Codes
4xx & 5xx Queue Error Codes

Recordings

Start Recording

Creates a call recording. Initiates the call recording type.

POST /LiveCalls/{call_id}/Actions/Recording/Start

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
call_id ID of the call. string (path) Yes
group A queryable name for the recording. string (body) No
message The message to place after recording has started. string/array (body) No
pre_message The message to play before the recording has started. string/array (body) No
tracks[] The tracks to record. Accepts: caller (far end), transfer (near end). Defaults to caller. array No

Example Request

curl -X POST \
  https://api.voxolo.gy/v1/LiveCalls/123456@7890/Actions/Recording/Start \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "group": "support_technical",
    "pre_message": "This call is about to be recorded.",
    "message": "This call is now being recorded.",
    "tracks": [
      "caller",
      "transfer"
    ]
  }'

Response

No Response Body

Response Codes

Status Description
204 No content on success.
4xx & 5xx General Error Codes

Pause Recording

This method allows developers to pause a call recording. This is useful for when it’s desirable to excerpt portions of a conversation while generating one audio file.

POST /LiveCalls/{call_id}/Actions/Recording/Pause

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
call_id ID of the call. string (path) Yes
tracks[] The tracks to record. Accepts: caller (far end), transfer (near end). Defaults to caller. array No

Example Request

curl -X POST \
  https://api.voxolo.gy/v1/LiveCalls/123456@7890/Actions/Recording/Pause \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

No Response Body

Response Codes

Status Description
204 No content on success.
4xx & 5xx General Error Codes

Resume Recording

This method allows developers to resume a paused call recording.

POST /LiveCalls/{call_id}/Actions/Recording/Resume

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
call_id ID of the call. string (path) Yes
tracks[] The tracks to record. Accepts: caller (far end), transfer (near end). Defaults to caller. array No

Example Request

curl -X POST \
  https://api.voxolo.gy/v1/LiveCalls/123456@7890/Actions/Recording/Resume \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

No Response Body

Response Codes

Status Description
204 No content on success.
4xx & 5xx General Error Codes

Stop Recording

This method allows developers to stop a call recording.

POST /LiveCalls/{call_id}/Actions/Recording/Stop

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
call_id ID of the call. string (path) Yes

Example Request

curl -X POST \
  https://api.voxolo.gy/v1/LiveCalls/123456@7890/Actions/Recording/Stop \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

No Response Body

Response Codes

Status Description
204 No content on success.
4xx & 5xx General Error Codes

List Recordings

Returns a filtered list of recordings across all applications.

A maximum of 1,000 recordings can be returned per request. If is_truncated indicates that more recordings were available, narrow your date range.

Authentication Type

API Key (Application-level)

GET /History/Recordings?{query_string}

Request

Parameter Description Type Required
begin_date Set the earliest recording to return by date/time in ISO 8601 format. Default: one hour before now. string (query) No
end_date Set the latest recording to return by date/time in ISO format. Default: now. string (query) No
group Returns all recordings with the specified group value set in the Record action. string (query) No
app_id Returns all recordings for the given application ID. * string (query) No
subaccount_id Returns all recordings for the given application Sub Account ID. * integer (query) No
call_no Returns all recordings originated with the given phone number. Expects E.164 format. string (query) No
direction Returns recordings based on the originating call’s direction. Omit to include all. string (query) No
type Returns recordings based on the type of recording used. Accepts call for recordings initiated by the RECORD Call Flow Action or Start Recording REST method. Accepts voicemail for recordings initiated by the RECORDMESSAGE Call Flow Action or the Leave Voicemail REST Method. Omit to include both. string (query) No

Example Request

curl -X GET \
  'https://api.voxolo.gy/v1/History/Recordings?begin_date=2016-03-23T22%3A05%3A32.000Z&end_date=2016-03-29T22%3A05%3A34.249Z&group=audio_recording&app_id=eaffd4-1234-4a95-9876-9c0b8&call_no=%2017145551212&call_id=1234%4056' \
  -H 'Cache-Control: no-cache' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

Property Description Type
recordings An array of recording objects. array
recordings[i].id The ID of the recording. string
recordings[i].app_id The ID of the application used for this call. string
recordings[i].call_id The ID of the call that was recorded. string
recordings[i].subaccount_id The Sub Account ID of the application used for this call. integer
recordings[i].group The user-defined group. string
recordings[i].caller_no The phone number of the originating caller (E.164 format: +17145551212). string
recordings[i].start_time The time the recording started. date
recordings[i].end_time The time the recording ended. date
recordings[i].duration The length of the recording in milliseconds. long
recordings[i].type The type of the recording. call for recordings initiated by the RECORD Call Flow Action or Start Recording REST method. voicemail for recordings initiated by the RECORDMESSAGE Call Flow Action or the Leave Voicemail REST Method. string

Example Response

{
  "recordings": [
    {
      "id": "MTMwMDE1QDQ2OjViOTyMzY3YjRkMDdjNHwx",
      "app_id": "eaffd4-1234-4a95-9876-9c0b8",
      "call_id": "121587@1912686780",
      "subaccount_id": 0,
      "group": "audio_recording",
      "caller_no": "+17145551212",
      "start_time": "2016-03-29T22:05:32.000Z",
      "end_time": "2016-03-29T22:05:34.249Z",
      "duration": 2249,
      "type": "voicemail"
    }
  ],
  "is_truncated": false
}

Response Codes

Status Description
200 Returns an array of recording objects.
4xx & 5xx General Error Codes

View Recordings

Returns a filtered list of recordings per a single call.

Authentication Type

API Key (Application-level)

GET /History/Recordings/{call_id}

Request

Parameter Description Type Required
call_id Returns all recordings originated on the given call ID. string (path) No

Example Request

curl -X GET \
  'https://api.voxolo.gy/v1/History/Recordings/12345@67890' \
  -H 'Cache-Control: no-cache' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

Property Description Type
recordings An array of recording objects. array
recordings[i].id The ID of the recording. string
recordings[i].app_id The ID of the application used for this call. string
recordings[i].call_id The ID of the call that was recorded. string
recordings[i].subaccount_id The Sub Account ID of the application used for this call. integer
recordings[i].group The user-defined group. string
recordings[i].caller_no The phone number of the originating caller (E.164 format: +17145551212). string
recordings[i].start_time The time the recording started. date
recordings[i].end_time The time the recording ended. date
recordings[i].duration The length of the recording in milliseconds. long
recordings[i].type The type of the recording. call for recordings initiated by the RECORD Call Flow Action or Start Recording REST method. voicemail for recordings initiated by the RECORDMESSAGE Call Flow Action or the Leave Voicemail REST Method. string

Example Response

{
  "recordings": [
    {
      "id": "MTMwMDE1QDQ2OjViOTyMzY3YjRkMDdjNHwx",
      "app_id": "eaffd4-1234-4a95-9876-9c0b8",
      "call_id": "121587@1912686780",
      "subaccount_id": 0,
      "group": "audio_recording",
      "caller_no": "+17145551212",
      "start_time": "2016-03-29T22:05:32.000Z",
      "end_time": "2016-03-29T22:05:34.249Z",
      "duration": 2249,
      "type": "voicemail"
    }
  ],
  "is_truncated": false
}

Response Codes

Status Description
200 Returns an array of recording objects.
4xx & 5xx General Error Codes

Download Recording

Returns downloaded audio files of recordings. Available formats: ulw, vox, mp3, wav, wavM, ogg, aac, au.

GET /History/Recordings/{id}/{format}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
id ID of the recording. string (path) Yes
format Audio format of the downloaded file: ulw, vox, mp3, wav, wavM, ogg, aac, au. Note that ulw and wavM are mono tracks. string (path) Yes

Example Request

curl -X GET \
  https://api.voxolo.gy/v1/History/Recordings/MTMwMDE1QDQ2OjViOTyMzY3YjRkMDdjNHwx/mp3 \
  -H 'Cache-Control: no-cache' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

Audio File

Response Codes

Status Description
200 Returns a data stream of the requested audio file.
4xx & 5xx General Error Codes

Delete Recording

Deletes a call recording.

DELETE /History/Recordings/{id}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
id ID of the recording. string (path) Yes

Example Request

curl -X DELETE \
  https://api.voxolo.gy/v1/History/Recordings/MTMwMDE1QDQ2OjViOTyMzY3YjRkMDdjNHwx \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

No Response Body

Response Codes

Status Description
200 No content on success.
4xx & 5xx General Error Codes

SIP Trunks

List SIP Trunks

Returns a list of SIP Trunks on this application.

GET /Trunks

AUTHENTICATION TYPE

API Key (Application-level)

REQUEST

No Request Body

Example Request

curl -X GET \
  https://api.voxolo.gy/v1/Trunks \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

Property Description Type
trunks An array of Trunk objects. array
trunks[i].trunk_id The unique ID of the SIP Trunk. string
trunks[i].created_on The date when the SIP Trunk was created. ISO date string
trunks[i].modified_on The date of the last update to the SIP Trunk. (Replaced by updated_on, scheduled to be deprecated Jan 2021) ISO date string
trunks[i].updated_on The date of the last update to the SIP Trunk. ISO date string
trunks[i].app_id The Application ID for this Trunk. string
trunks[i].subaccount_id The Sub Account ID for this this Trunk (if applicable) string
trunks[i].direction Indicates whether if SIP Trunk is outbound or inbound string
trunks[i].simultaneous_call_limit The number of concurrent channels to allow for either an outbound or inbound SIP Trunk. Set a limit on concurrent calls for either your outbound or inbound trunk. Once the limit is reached, outbound calls will be blocked with a 503 signal and inbound calls will hear a BUSY tone. integer
trunks[i].description User-definable description of the SIP Trunk. string
trunks[i].recording Object containing recording settings object
trunks[i].recording.setting If pre_connect all calls on this trunk will be recorded. If do_not_record, no calls on this trunk will be recorded. Options: pre_connect, do_not_record string
trunks[i].inbound Object containing inbound information object
trunks[i].inbound.destination DNS name or IP Address where Voxology will send SIP requests on inbound activity. string
trunks[i].inbound.failover Object containing failover information object
trunks[i].inbound.failover.source Set a failover destination source should Voxology be unable to reach your inbound.destination IP Address or NDS name. You may fail over to another Voxology inbound SIP Trunk, phone number, SIP URI or the Programmable Voice API to control the calls programmatically. Accepts: trunk_id, phone_number, sip_uri, api paired with the inbound.failover.value below. string
trunks[i].inbound.failover.value The value of the inbound.failover.source: trunk_id accepts the uuid of the alternative trunk, phone_number accepts the destination phone number in E.164 format (e.g. +19495551212), sip_uri accepts a sip uri, api accepts either CallFlows or ParkingLot which will enable the call to be controlled via Voxology’s Programmable Voice API. string
trunks[i].inbound.phone_numbers_uri The URI to see the list of provisioned numbers on the Trunk. string
trunks[i].outbound Object containing outbound information object
trunks[i].outbound.domain The unique url to which you will send your SIP requests. Voxology SIP domains must be alphanumeric (a-z, 0-9), may contain hyphens (-), and must end with: trunk.voxolo.gy string
trunks[i].outbound.authentication Array of Source/Value pairs array
trunks[i].outbound.authentication[i].source The source of the SIP invite. Options: twilio or other string
trunks[i].outbound.authentication[i].value If the source is twilio, the value is the Account SID. If the source is other, the value is the IP Address or CIDR block string
trunks[i].outbound.override_early_media Early media setting - defaults to null. Override early media with a localized ring from either the country of the to number or the from number. Or you may set it to a specific country’s ring. Accepts: to_country, from_country, an ISO Alpha-2 country code. string
trunks[i].outbound.fax_support The current status of fax support on this SIP Trunk. Includes: enabled or disabled. string
trunks[i].outbound.max_post_dial_delay The maximum amount of “post dial delay” before Voxology cancels with a 503 error. NOTE: Post Dial Delay is the time between when a number is dialed and when the caller begins to hear ringing. Allowed range: 7-30 seconds. Default: null. integer
trunks[i].sip Object containing the sip settings and information object
trunks[i].sip.transport The transport layer protocol of the trunk. Accecpts UDP, TCP and TLS Default: UDP. string
trunks[i].sip.media The media path of the trunk. Accecpts RTP and SRTP Default: RTP. string
trunks[i].stream The object containing media stream configuration details. object
trunks[i].stream.url The url to where the WebSocket connection will be initiated and audio will start streaming. Must begin with ws:// or wss://. string
trunks[i].stream.media_type The format media will be streamed in. Accepts base64 and binary. Defaults to base64. string
trunks[i].stream.tracks[] An array that lists which tracks will have media streamed. Accepts near (API) and far (caller). array
trunks[i].stream.stream_data A custom, stringified JSON object to include in the media stream Websocket message. string

Example Response

{
  "trunks": [
    {
      "trunk_id": "952bfde1-8079-4c32-92c3-6339810e1be3",
      "status": "active",
      "created_on": "2018-07-30T15:12:41.000Z",
      "modified_on": "2018-07-30T15:12:41.000Z",
      "updated_on": "2018-07-30T15:12:41.000Z",
      "app_id": "aaaa-bbbb-cccc-dddd-eeee",
      "subaccount_id": 12345,
      "direction": "outbound",
      "sip": {
        "transport": "UDP",
        "media": "RTP"
      },
      "simultaneous_call_limit": 1,
      "description": "outbound trunk sample",
      "recording": {},
      "outbound": {
        "domain": null,
        "authentication": [
          {
            "source": "twilio",
            "value": "aaaaa-bbbbb-ccccc-ddddd-eeeee"
          },
          {
            "source": "other",
            "value": "000.000.00.00"
          },
          {
            "source": "other",
            "value": "000.000.00.00"
          }
        ],
        "override_early_media": "TO",
        "fax_support": "enabled",
        "max_post_dial_delay": 10
      }
    },
    {
      "trunk_id": "952ba0d1-8079-4c32-12c3-6339810e1be9",
      "status": "inactive",
      "created_on": "2018-07-30T15:12:41.000Z",
      "modified_on": "2018-07-30T15:12:41.000Z",
      "updated_on": "2018-07-30T15:12:41.000Z",
      "app_id": "aaaa-bbbb-cccc-dddd-eeee",
      "direction": "inbound",
      "simultaneous_call_limit": 1,
      "description": "inbound trunk sample",
      "recording": {},
      "inbound": {
        "destination": "000.000.00.00",
        "failover": {
          "value": null
        },
        "phone_numbers_uri": "/v1/PhoneNumbers/Trunks/952ba0d1-8079-4c32-12c3-6339810e1be9"
      },
      "stream": {
        "url": "ws://websocketurl.com",
        "media_type": "base64",
        "tracks": [
            "near",
            "far"
        ],
        "stream_data": "{\"k1\":\"v1\",\"k2\":2}"
      }
    }
  ]
}

Response Codes

Status Description
200 Returns array of trunk objects
4xx & 5xx General Error Codes

View SIP Trunk

Returns the SIP Trunk object of the specified SIP Trunk.

GET Trunks/{trunk_id}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
trunk_id The ID of the SIP Trunk string (path) Yes

Example Request

curl -X GET \
  'https://api.voxolo.gy/v1/Trunks/0a2dccfe-2a2b-42bf-8f15-b1042275511b' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

Property Description Type
trunk_id The unique ID of the SIP Trunk. string
status The current status of the SIP Trunk. Includes: active or inactive. string
created_on The date the SIP Trunk was created on. ISO date string
modified_on The date of the last update to the SIP Trunk. (Replaced by updated_on, scheduled to be deprecated Jan 2021) ISO date string
updated_on The date the subaccount was last updated on. ISO date string
app_id The Application ID for this Trunk. string
subaccount_id The Sub Account ID for this this Trunk (if applicable). string
direction Indicates whether if SIP Trunk is outbound or inbound. string
simultaneous_call_limit The number of concurrent channels to allow for either an outbound or inbound SIP Trunk. Set a limit on concurrent calls for either your outbound or inbound trunk. Once the limit is reached, outbound calls will be blocked with a 503 signal and inbound calls will hear a BUSY tone. integer
description User-definable description of the SIP Trunk. string
recording Object containing recording settings. object
recording.setting If pre_connect all calls on this trunk will be recorded. If do_not_record, no calls on this trunk will be recorded. Options: pre_connect, do_not_record string
inbound Object containing inbound information object
inbound.destination DNS name or IP Address where Voxology will send SIP requests on inbound activity. string
inbound.failover Object containing failover information. object
inbound.failover.source Set a failover destination source should Voxology be unable to reach your inbound.destination IP Address or NDS name. You may fail over to another Voxology inbound SIP Trunk, phone number, SIP URI or the Programmable Voice API to control the calls programmatically. Accepts: trunk_id, phone_number, sip_uri, api paired with the inbound.failover.value below. string
inbound.failover.value The value of the inbound.failover.source: trunk_id accepts the uuid of the alternative trunk, phone_number accepts the destination phone number in E.164 format (e.g. +19495551212), sip_uri accepts a sip uri, api accepts either CallFlows or ParkingLot which will enable the call to be controlled via Voxology’s Programmable Voice API. string
inbound.phone_numbers_uri The URI to see the list of provisioned numbers on the Trunk. string
outbound Object containing outbound information. object
outbound.domain The unique url to which you will send your SIP requests. Voxology SIP domains must be alphanumeric (a-z, 0-9), may contain hyphens (-), and must end with: trunk.voxolo.gy string
outbound.authentication Array of Source/Value pairs array
outbound.authentication[i].source The source of the SIP invite. Options: twilio or other string
outbound.authentication[i].value If the source is twilio, the value is the Account SID. If the source is other, the value is the IP Address or CIDR block string
outbound.override_early_media Early media setting - defaults to null. Override early media with a localized ring from either the country of the to number or the from number. Or you may set it to a specific country’s ring. Accepts: to_country, from_country, an ISO Alpha-2 country code. string
outbound.fax_support The current status of fax support on this SIP Trunk. Includes: enabled or disabled. string
outbound.max_post_dial_delay The maximum amount of “post dial delay” before Voxology cancels with a 503 error. NOTE: Post Dial Delay is the time between when a number is dialed and when the caller begins to hear ringing). Allowed range: 7-30 seconds. Default: null. integer
sip Object containing the sip settings and information object
sip.transport The transport layer protocol of the trunk. Accecpts UDP, TCP and TLS Default: UDP. string
sip.media The media path of the trunk. Accecpts RTP and SRTP Default: RTP. string
stream The object containing media stream configuration details. object
stream.url The url to where the WebSocket connection will be initiated and audio will start streaming. Must begin with ws:// or wss://. string
stream.media_type The format media will be streamed in. Accepts base64 and binary. Defaults to base64. string
stream.tracks[] An array that lists which tracks will have media streamed. Accepts near (API) and far (caller). array
stream.stream_data A custom, stringified JSON object to include in the media stream Websocket message. string

Example Response // Inbound

{
  "trunk_id": "952bfde1-8079-4c32-92c3-6339810e1be3",
  "status": "active",
  "created_on": "2018-07-30T11:23:21.000Z",
  "updated_on": "2019-01-29T16:24:21.000Z",
  "modified_on": "2018-07-30T11:23:21.000Z",
  "app_id": "aaaa-bbbb-cccc-dddd-eeee",
  "direction": "inbound",
  "sip": {
        "transport": "UDP",
        "media": "RTP"
  },
  "simultaneous_call_limit": 1,
  "description": null,
  "recording": {},
  "inbound": {
    "destination": "000.000.00.00",
    "failover": {
      "value": null
    },
    "phone_numbers_uri": "/v1/PhoneNumbers/Trunks/952bfde1-8079-4c32-92c3-6339810e1be3"
  },
  "stream": {
    "url": "ws://websocketurl.com",
    "media_type": "base64",
    "tracks": [
        "near",
        "far"
    ],
    "stream_data": "{\"k1\":\"v1\",\"k2\":2}"
  }
}

Example Response // Outbound

{
  "trunk_id": "952bfde1-8079-4c32-92c3-6339810e1be3",
  "status": "active",
  "created_on": "2018-07-30T15:12:41.000Z",
  "modified_on": "2018-07-30T15:12:41.000Z",
  "updated_on": "2019-01-29T16:24:21.000Z",
  "app_id": "aaaa-bbbb-cccc-dddd-eeee",
  "direction": "outbound",
  "sip": {
        "transport": "UDP",
        "media": "RTP"
  },
  "recording": {
                "setting": "pre_connect",
                "tracks": [
                    "far"
                ]
  },
  "simultaneous_call_limit": 1,
  "description": "outbound trunk 7",
  "recording": {},
  "outbound": {
    "domain": null,
    "authentication": [
      {
        "source": "twilio",
        "value": "aaaaa-bbbbb-ccccc-ddddd-eeeee"
      },
      {
        "source": "other",
        "value": "000.000.00.00"
      },
      {
        "source": "other",
        "value": "000.000.00.00"
      }
    ],
    "override_early_media": "TO",
    "fax_support": "enabled",
    "max_post_dial_delay": 10,
  },
  "stream": {
    "url": "ws://websocketurl.com",
    "media_type": "base64",
    "tracks": [
      "near",
      "far"
    ],
    "stream_data": "{\"k1\":\"v1\",\"k2\":2}"
  }
}

Response Codes

Status Description
200 Returns a Trunk object
4xx & 5xx General Error Codes

Create SIP Trunk

Creates a SIP Trunk.

POST /Trunks

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
description User-definable description of the SIP Trunk. string No
direction Indicates the direction of the SIP Trunk as inbound or outbound. Options: inbound or outbound string Yes
simultaneous_call_limit The number of concurrent channels to allow for either an outbound or inbound SIP Trunk. Set a limit on concurrent calls for either your outbound or inbound trunk. Once the limit is reached, outbound calls will be blocked with a 503 signal and inbound calls will hear a BUSY tone. integer No
recording Object containing recording settings. object No
recording.setting If pre_connect all calls on this trunk will be recorded. If do_not_record, no calls on this trunk will be recorded. Options: pre_connect, do_not_record. string Conditional
recording.tracks Array containing the tracks of the recording array Conditional
inbound Object containing inbound information. object Conditional
inbound.destination DNS name or IP Address where Voxology will send SIP requests on inbound activity. string Yes
inbound.failover Object containing failover information. object No
inbound.failover.source Set a failover destination source should Voxology be unable to reach your inbound.destination IP Address or NDS name. You may fail over to another Voxology inbound SIP Trunk, phone number, SIP URI or the Programmable Voice API to control the calls programmatically. Accepts: trunk_id, phone_number, sip_uri, api paired with the inbound.failover.value below. string No
inbound.failover.value The value of the inbound.failover.source: trunk_id accepts the uuid of the alternative trunk, phone_number accepts the destination phone number in E.164 format (e.g. +19495551212), sip_uri accepts a sip uri, api accepts either CallFlows or ParkingLot which will enable the call to be controlled via Voxology’s Programmable Voice API. string Conditional
outbound Object containing outbound information. object Conditional
outbound.domain The unique url to which you will send your SIP requests. Voxology SIP domains must be alphanumeric (a-z, 0-9), may contain hyphens (-), and must end with: trunk.voxolo.gy string Conditional
outbound.authentication Array of Source/Value pairs array Conditional
outbound.authentication[i].source The source of the SIP invite. Options: twilio or other string Yes
outbound.authentication[i].value If the source is twilio, the value is the Account SID. If the source is other, the value is the IP Address or CIDR block string Yes
outbound.override_early_media Early media setting - defaults to null. Override early media with a localized ring from either the country of the to number or the from number. Or you may set it to a specific country’s ring. Accepts: to_country, from_country, an ISO Alpha-2 country code. string Conditional
outbound.fax_support The current status of fax support on this SIP Trunk. Includes: enabled or disabled. string No
outbound.max_post_dial_delay The maximum amount of “post dial delay” before Voxology cancels with a 503 error. NOTE: Post Dial Delay is the time between when a number is dialed and when the caller begins to hear ringing). Allowed range: 7-30 seconds. Default: null. integer No
sip Object containing the sip settings and information object
sip.transport The transport layer protocol of the trunk. Accecpts UDP, TCP and TLS Default: UDP. string
sip.media The media path of the trunk. Accecpts RTP and SRTP Default: RTP. string
stream The object containing media stream configuration details. object
stream.url The url to where the WebSocket connection will be initiated and audio will start streaming. Must begin with ws:// or wss://. string
stream.media_type The format media will be streamed in. Accepts base64 and binary. Defaults to base64. string
stream.tracks[] An array that lists which tracks will have media streamed. Accepts near (API) and far (caller). array
stream.stream_data A custom, stringified JSON object to include in the media stream Websocket message. string

Example Request of Inbound Trunk

curl -X POST \
  https://api.voxolo.gy/v1/Trunks \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "direction": "inbound",
    "simultaneous_call_limit": 1,
    "description": "some_inbound",
    "recording": {
      "setting": "do_not_record"
    },
    "inbound": {
      "destination": "www.xxx.yy.zz"
    },
    "stream": {
      "url": "ws://websocketurl.com",
      "media_type": "base64",
      "tracks": [
        "near",
        "far"
      ],
      "stream_data": "{\"k1\":\"v1\",\"k2\":2}"
    }
  }'

Example Request of Outbound Trunk

curl -X POST \
  https://api.voxolo.gy/v1/Trunks \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOU_API_KEY' \
  -d '{
    "direction": "outbound",
    "simultaneous_call_limit": 1,
    "description": "outbound trunk 7",
    "recording": {},
    "outbound": {
      "domain": null,
      "authentication": [
        {
          "source": "twilio",
          "value": "aaaaa-bbbbb-ccccc-ddddd-eeeee"
        },
        {
          "source": "other",
          "value": "000.000.00.00"
        },
        {
          "source": "other",
          "value": "000.000.00.00"
        }
      ],
      "override_early_media": "TO",
      "fax_support": "enabled",
      "max_post_dial_delay": 10,
    },
    "stream": {
      "url": "ws://websocketurl.com",
      "media_type": "base64",
      "tracks": [
        "near",
        "far"
      ],
      "stream_data": "{\"k1\":\"v1\",\"k2\":2}"
    }
  }'

Response

Property Description Type
trunk_id The unique ID of the SIP Trunk. string
created_on The date the SIP Trunk was created on. ISO date string
modified_on The date of the last update to the SIP Trunk. (Replaced by updated_on, scheduled to be deprecated Jan 2021) ISO date string
updated_on The date the subaccount was last updated on. ISO date string
app_id The Application ID for this Trunk. string
subaccount_id The Sub Account ID for this this Trunk (if applicable). string
direction Indicates whether if SIP Trunk is outbound or inbound. string
simultaneous_call_limit The number of concurrent channels to allow for either an outbound or inbound SIP Trunk. Set a limit on concurrent calls for either your outbound or inbound trunk. Once the limit is reached, outbound calls will be blocked with a 503 signal and inbound calls will hear a BUSY tone. integer
description User-definable description of the SIP Trunk. string
recording Object containing recording settings. object
recording.setting If pre_connect all calls on this trunk will be recorded. If do_not_record, no calls on this trunk will be recorded. Options: pre_connect, do_not_record. string
inbound Object containing inbound information. object
inbound.destination DNS name or IP Address where Voxology will send SIP requests on inbound activity. string
inbound.failover Object containing failover information. object
inbound.failover.source Set a failover destination source should Voxology be unable to reach your inbound.destination IP Address or NDS name. You may fail over to another Voxology inbound SIP Trunk, phone number, SIP URI or the Programmable Voice API to control the calls programmatically. Accepts: trunk_id, phone_number, sip_uri, api paired with the inbound.failover.value below. string
inbound.failover.value The value of the inbound.failover.source: trunk_id accepts the uuid of the alternative trunk, phone_number accepts the destination phone number in E.164 format (e.g. +19495551212), sip_uri accepts a sip uri, api accepts either CallFlows or ParkingLot which will enable the call to be controlled via Voxology’s Programmable Voice API. string
inbound.phone_numbers_uri The URI to see the list of provisioned numbers on the Trunk. string
outbound Object containing outbound information. object
outbound.domain The unique url to which you will send your SIP requests. Voxology SIP domains must be alphanumeric (a-z, 0-9), may contain hyphens (-), and must end with: trunk.voxolo.gy string
outbound.authentication Array of Source/Value pairs array
outbound.authentication[i].source The source of the SIP invite. Options: twilio or other string
outbound.authentication[i].value If the source is twilio, the value is the Account SID. If the source is other, the value is the IP Address or CIDR block string
outbound.override_early_media Early media setting - defaults to null. Override early media with a localized ring from either the country of the to number or the from number. Or you may set it to a specific country’s ring. Accepts: to_country, from_country, an ISO Alpha-2 country code. string
outbound.fax_support The current status of fax support on this SIP Trunk. Includes: enabled or disabled. string
outbound.max_post_dial_delay The maximum amount of “post dial delay” before Voxology cancels with a 503 error. NOTE: Post Dial Delay is the time between when a number is dialed and when the caller begins to hear ringing). Allowed range: 7-30 seconds. Default: null. integer
sip Object containing the sip settings and information object
sip.transport The transport layer protocol of the trunk. Accecpts UDP, TCP and TLS Default: UDP. string
sip.media The media path of the trunk. Accecpts RTP and SRTP Default: RTP. string
stream The object containing media stream configuration details. object
stream.url The url to where the WebSocket connection will be initiated and audio will start streaming. Must begin with ws:// or wss://. string
stream.media_type The format media will be streamed in. Accepts base64 and binary. Defaults to base64. string
stream.tracks[] An array that lists which tracks will have media streamed. Accepts near (API) and far (caller). array
stream.stream_data A custom, stringified JSON object to include in the media stream Websocket message. string

Example Response // Inbound

{
  "trunk_id": "952bfde1-8079-4c32-92c3-6339810e1be3",
  "created_on": "2018-07-30T11:23:21.000Z",
  "modified_on": "2018-07-30T11:23:21.000Z",
  "updated_on": "2019-01-29T16:24:21.000Z",
  "app_id": "aaaa-bbbb-cccc-dddd-eeee",
  "direction": "inbound",
  "sip": {
        "transport": "UDP",
        "media": "RTP"
  },
  "simultaneous_call_limit": 1,
  "description": null,
  "recording": {},
  "inbound": {
    "destination": "000.000.00.00",
    "failover": {
      "value": null
    },
    "phone_numbers_uri": "/v1/PhoneNumbers/Trunks/952bfde1-8079-4c32-92c3-6339810e1be3"
  },
  "stream": {
    "url": "ws://websocketurl.com",
    "media_type": "base64",
    "tracks": [
      "near",
      "far"
    ],
    "stream_data": "{\"k1\":\"v1\",\"k2\":2}"
  }
}

Example Response // Outbound

{
  "trunk_id": "952bfde1-8079-4c32-92c3-6339810e1be3",
  "created_on": "2018-07-30T15:12:41.000Z",
  "modified_on": "2018-07-30T15:12:41.000Z",
  "updated_on": "2019-01-29T16:24:21.000Z",
  "app_id": "aaaa-bbbb-cccc-dddd-eeee",
  "direction": "outbound",
  "sip": {
        "transport": "UDP",
        "media": "RTP"
  },
  "recording": {
                "setting": "pre_connect",
                "tracks": [
                    "far"
                ]
  },
  "simultaneous_call_limit": 1,
  "description": "outbound trunk 7",
  "recording": {},
  "outbound": {
    "domain": null,
    "authentication": [
      {
        "source": "twilio",
        "value": "aaaaa-bbbbb-ccccc-ddddd-eeeee"
      },
      {
        "source": "other",
        "value": "000.000.00.00"
      },
      {
        "source": "other",
        "value": "000.000.00.00"
      }
    ],
    "override_early_media": "TO",
    "fax_support": "enabled",
    "max_post_dial_delay": 10
  },
  "stream": {
    "url": "ws://websocketurl.com",
    "media_type": "base64",
    "tracks": [
      "near",
      "far"
    ],
    "stream_data": "{\"k1\":\"v1\",\"k2\":2}"
  }
}

Response Codes

Status Description
201 SIP Trunk created
4xx & 5xx General Error Codes

Update SIP Trunk

Updates the SIP Trunk configuration of a specified Trunk.

PUT /Trunks/{trunk_id}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
trunk_id The ID of the SIP Trunk. string (path) Yes
status The status of the SIP Trunk. Options: active or inactive. string No
description User-definable description of the SIP Trunk. string No
simultaneous_call_limit The number of concurrent channels to allow for either an outbound or inbound SIP Trunk. Set a limit on concurrent calls for either your outbound or inbound trunk. Once the limit is reached, outbound calls will be blocked with a 503 signal and inbound calls will hear a BUSY tone. integer No
recording Object containing recording settings. object No
recording.setting If pre_connect all calls on this trunk will be recorded. If do_not_record, no calls on this trunk will be recorded. Options: pre_connect, do_not_record. string Conditional
recording.tracks Array containing the tracks of the recording array Conditional
inbound Object containing inbound information. object Conditional
inbound.destination DNS name or IP Address where Voxology will send SIP requests on inbound activity. string Yes
inbound.failover Object containing failover information. object No
inbound.failover.source Set a failover destination source should Voxology be unable to reach your inbound.destination IP Address or NDS name. You may fail over to another Voxology inbound SIP Trunk, phone number, SIP URI or the Programmable Voice API to control the calls programmatically. Accepts: trunk_id, phone_number, sip_uri, api paired with the inbound.failover.value below. string No
inbound.failover.value The value of the inbound.failover.source: trunk_id accepts the uuid of the alternative trunk, phone_number accepts the destination phone number in E.164 format (e.g. +19495551212), sip_uri accepts a sip uri, api accepts either CallFlows or ParkingLot which will enable the call to be controlled via Voxology’s Programmable Voice API. string conditional
outbound Object containing outbound information. object Conditional
outbound.domain The unique url to which you will send your SIP requests. Voxology SIP domains must be alphanumeric (a-z, 0-9), may contain hyphens (-), and must end with: trunk.voxolo.gy string Conditional
outbound.authentication Array of Source/Value pairs array Conditional
outbound.authentication[i].source The source of the SIP invite. Options: twilio or other string Yes
outbound.authentication[i].value If the source is twilio, the value is the Account SID. If the source is other, the value is the IP Address or CIDR block string Yes
outbound.override_early_media Early media setting - defaults to null. Override early media with a localized ring from either the country of the to number or the from number. Or you may set it to a specific country’s ring. Accepts: to_country, from_country, an ISO Alpha-2 country code. string conditional
outbound.fax_support The current status of fax support on this SIP Trunk. Includes: enabled or disabled. string No
outbound.max_post_dial_delay The maximum amount of “post dial delay” before Voxology cancels with a 503 error. NOTE: Post Dial Delay is the time between when a number is dialed and when the caller begins to hear ringing). Allowed range: 7-30 seconds. Default: null. integer No
sip Object containing the sip settings and information object
sip.transport The transport layer protocol of the trunk. Accecpts UDP, TCP and TLS Default: UDP. string
sip.media The media path of the trunk. Accecpts RTP and SRTP Default: RTP. string
stream The object containing media stream configuration details. object
stream.url The url to where the WebSocket connection will be initiated and audio will start streaming. Must begin with ws:// or wss://. string
stream.media_type The format media will be streamed in. Accepts base64 and binary. Defaults to base64. string
stream.tracks[] An array that lists which tracks will have media streamed. Accepts near (API) and far (caller). array
stream.stream_data A custom, stringified JSON object to include in the media stream Websocket message. string

Example Request

curl -X PUT \
  https://api.voxolo.gy/v1/Trunks/952bfde1-8079-4c32-92c3-6339810e1be3 \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "description": "updated description"
  }'

Response

Property Description Type
trunk_id The unique ID of the SIP Trunk. string
created_on The date the SIP Trunk was created on. ISO date string
updated_on The date the subaccount was last updated on. ISO date string
app_id The Application ID for this Trunk. string
subaccount_id The Sub Account ID for this this Trunk (if applicable). string
direction Indicates whether SIP Trunk is outbound or inbound. string
simultaneous_call_limit The number of concurrent channels to allow for either an outbound or inbound SIP Trunk. Set a limit on concurrent calls for either your outbound or inbound trunk. Once the limit is reached, outbound calls will be blocked with a 503 signal and inbound calls will hear a BUSY tone. integer
description User-definable description of the SIP Trunk. string
recording Object containing recording settings. object
recording.setting If pre_connect all calls on this trunk will be recorded. If do_not_record, no calls on this trunk will be recorded. Options: pre_connect, do_not_record. string
inbound Object containing inbound information. object
inbound.destination DNS name or IP Address where Voxology will send SIP requests on inbound activity. string
inbound.failover Object containing failover information. object
inbound.failover.source Set a failover destination source should Voxology be unable to reach your inbound.destination IP Address or NDS name. You may fail over to another Voxology inbound SIP Trunk, phone number, SIP URI or the Programmable Voice API to control the calls programmatically. Accepts: trunk_id, phone_number, sip_uri, api paired with the inbound.failover.value below. string
inbound.failover.value The value of the inbound.failover.source: trunk_id accepts the uuid of the alternative trunk, phone_number accepts the destination phone number in E.164 format (e.g. +19495551212), sip_uri accepts a sip uri, api accepts either CallFlows or ParkingLot which will enable the call to be controlled via Voxology’s Programmable Voice API. string
inbound.phone_numbers_uri The URI to see the list of provisioned numbers on the Trunk. string
outbound Object containing outbound information. object
outbound.domain The unique url to which you will send your SIP requests. Voxology SIP domains must be alphanumeric (a-z, 0-9), may contain hyphens (-), and must end with: trunk.voxolo.gy string
outbound.authentication Array of Source/Value pairs array
outbound.authentication[i].source The source of the SIP invite. Options: twilio or other string
outbound.authentication[i].value If the source is twilio, the value is the Account SID. If the source is other, the value is the IP Address or CIDR block string
outbound.override_early_media Early media setting - defaults to null. Override early media with a localized ring from either the country of the to number or the from number. Or you may set it to a specific country’s ring. Accepts: to_country, from_country, an ISO Alpha-2 country code. string
outbound.fax_support The current status of fax support on this SIP Trunk. Includes: enabled or disabled. string
outbound.max_post_dial_delay The maximum amount of “post dial delay” before Voxology cancels with a 503 error. NOTE: Post Dial Delay is the time between when a number is dialed and when the caller begins to hear ringing). Allowed range: 7-30 seconds. Default: null. integer
sip Object containing the sip settings and information object
sip.transport The transport layer protocol of the trunk. Accecpts UDP, TCP and TLS Default: UDP. string
sip.media The media path of the trunk. Accecpts RTP and SRTP Default: RTP. string
stream The object containing media stream configuration details. object
stream.url The url to where the WebSocket connection will be initiated and audio will start streaming. Must begin with ws:// or wss://. string
stream.media_type The format media will be streamed in. Accepts base64 and binary. Defaults to base64. string
stream.tracks[] An array that lists which tracks will have media streamed. Accepts near (API) and far (caller). array
stream.stream_data A custom, stringified JSON object to include in the media stream Websocket message. string

Example Response

{
  "trunk_id": "952bfde1-8079-4c32-92c3-6339810e1be3",
  "created_on": "2018-07-30T15:12:41.000Z",
  "modified_on": "2018-07-30T15:12:41.000Z",
  "updated_on": "2018-07-30T15:12:41.000Z",
  "app_id": "aaaa-bbbb-cccc-dddd-eeee",
  "direction": "outbound",
  "sip": {
        "transport": "UDP",
        "media": "RTP"
  },
  "simultaneous_call_limit": 1,
  "description": "updated description",
  "recording": {},
  "outbound": {
    "domain": null,
    "authentication": [
      {
        "source": "twilio",
        "value": "aaaaa-bbbbb-ccccc-ddddd-eeeee"
      },
      {
        "source": "other",
        "value": "000.000.00.00"
      },
      {
        "source": "other",
        "value": "000.000.00.00"
      }
    ],
    "override_early_media": "TO",
    "fax_support": "enabled",
    "mac_post_dial_delay": 10
  },
  "stream": {
    "url": "ws://websocketurl.com",
    "media_type": "base64",
    "tracks": [
      "near",
      "far"
    ],
    "stream_data": "{\"k1\":\"v1\",\"k2\":2}"
  }
}

Response Codes

Status Description
200 Returns the Trunk Object
4xx & 5xx General Error Codes

Delete SIP Trunk

Deletes the specified SIP Trunk.

DELETE /Trunks/{trunk_id}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
trunk_id The ID of the SIP Trunk . string (path) Yes

Example Request

curl -X DELETE \
  https://api.voxolo.gy/v1/Trunks/952bfde1-8079-4c32-92c3-6339810e1be3 \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

No Response Body

Response Codes

Status Description
204 No content on success.
4xx & 5xx General Error Codes

SIP Users

SIP Users enable you to create and manage SIP Registration credentials through the Voxology API or Portal. SIP Users can be used to connect a variety of devices to one another or to the PSTN, including VoIP phones, softphones, SIP-enabled WebRTC clients, or a PBX.

List SIP Users

Returns a list of SIP Users on this application.

GET /Users

AUTHENTICATION TYPE

API Key (Application-level)

REQUEST

No Request Body

Example Request

curl -X GET \
  https://api.voxolo.gy/v1/Users \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

Property Description Type
users An array of User objects. array
users[i].created_on The date when the SIP User was created. ISO date string
users[i].updated_on The date of the last update to the SIP User. ISO date string
users[i].user_id The unique ID of the SIP User. string
users[i].status The current status of the SIP User. Includes: active or inactive string
users[i].description User-definable description of the SIP User. string
users[i].firstname User-definable first name of the User. string
users[i].lastname User-definable last name of the User. string
users[i].country The country of the User. string (ISO Alpha-2)
users[i].uri The URI to view the SIP User’s details. string
users[i].sip Object containing sip settings and information object
users[i].sip.authentication Object containing sip authentication credentials. object
users[i].sip.authentication.username. The SIP User’s username string
users[i].sip.authentication.password. The SIP User’s password string
users[i].sip.domain The unique SIP User URL. string
users[i].sip.outbound Object containing outbound information. object
users[i].sip.outbound.assigned_to The campaign or trunk to which the SIP user is assigned. string
users[i].sip.outbound.caller_id Object containing caller ID information. object
users[i].sip.outbound.caller_id.external_no The caller ID displayed when calling external numbers. string
users[i].sip.outbound.caller_id.internal_no The caller ID displayed when calling internal numbers or extentions. string
users[i].sip.outbound.caller_id.internal_cnam The caller name when calling internal numbers or extentions. string
users[i].sip.transport The type of signaling protocol. Includes: UDP, TCP or TLS string
users[i].sip.media The type of media stream protocol. Includes: RTP or SRTP string
users[i].sip.inbound Object containing the inbound information. object
users[i].sip.inbound.uri The unique SIP URI that calls to this user will be delivered to. string
users[i].app_id The Application ID for this SIP User. string
users[i].subaccount_id The Sub Account ID for this SIP User. (if applicable) string

Example Response

{
    "users": [
        {
            "created_on": "2021-08-13T14:23:37.000Z",
            "updated_on": "2022-08-29T21:39:03.000Z",
            "user_id": "952bfde1-8079-4c32-92c3-6339810e1be3",
            "status": "active",
            "description": "my sip user",
            "firstname": "Jane",
            "lastname": "Doe",
            "country": "US",
            "uri": "/v1/Users/952bfde1-8079-4c32-92c3-6339810e1be3",
            "sip": {
                "authentication": {
                    "username": "jane",
                    "password": null
                },
                "domain": "domain.sip.user.voxolo.gy",
                "outbound": {
                    "assigned_to": "Trunks/fa12345c-6d7a-890d-1c23-4dd56cfc7890",
                    "caller_id": {
                        "external_no": "+19495551234",
                        "internal_no": "123",
                        "internal_cnam": "JANEDOE"
                    }
                },
                "transport": "UDP",
                "media": "RTP",
                "inbound": {
                    "uri": "sip:jane@domain.sip.user.voxolo.gy"
                }
            },
            "app_id": "cc12c345-a67b-8901-23f4-56789fa0aef1",
            "subaccount_id": null
        }
    ]
}

Response Codes

Status Description
200 Returns array of user objects
4xx & 5xx General Error Codes

View SIP User

Returns the SIP User object of the specified SIP User.

GET Users/{user_id}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
user_id The ID of the SIP User string (path) Yes

Example Request

curl -X GET \
  'https://api.voxolo.gy/v1/Users/952bfde1-8079-4c32-92c3-6339810e1be3' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

Property Description Type
created_on The date when the SIP User was created. ISO date string
updated_on The date of the last update to the SIP User. ISO date string
user_id The unique ID of the SIP User. string
status The current status of the SIP User. Includes: active or inactive string
description User-definable description of the SIP User. string
firstname User-definable first name of the User. string
lastname User-definable last name of the User. string
country The country of the User. string (ISO Alpha-2)
uri The URI to view the SIP User’s details. string
sip Object containing sip settings and information object
sip.authentication Object containing sip authentication credentials. object
sip.authentication.username The SIP User’s username string
sip.authentication.password The SIP User’s password string
sip.domain The unique SIP User URL. string
sip.outbound Object containing outbound information. object
sip.outbound.assigned_to The campaign or trunk to which the SIP user is assigned. string
sip.outbound.caller_id Object containing caller ID information. object
sip.outbound.caller_id.external_no The caller ID displayed when calling external numbers. string
sip.outbound.caller_id.internal_no The caller ID displayed when calling internal numbers or extentions. string
sip.outbound.caller_id.internal_cnam The caller name when calling internal numbers or extentions. string
sip.transport The type of signaling protocol. Includes: UDP, TCP or TLS string
sip.media The type of media stream protocol. Includes: RTP or SRTP string
sip.inbound Object containing the inbound information. object
sip.inbound.uri The unique SIP URI that calls to this user will be delivered to. string
app_id The Application ID for this SIP User. string
subaccount_id The Sub Account ID for this SIP User. (if applicable) string

Example Response

 {
            "created_on": "2021-08-13T14:23:37.000Z",
            "updated_on": "2022-08-29T21:39:03.000Z",
            "user_id": "952bfde1-8079-4c32-92c3-6339810e1be3",
            "status": "active",
            "description": "my sip user",
            "firstname": "Jane",
            "lastname": "Doe",
            "country": "US",
            "uri": "/v1/Users/952bfde1-8079-4c32-92c3-6339810e1be3",
            "sip": {
                "authentication": {
                    "username": "jane",
                    "password": null
                },
                "domain": "domain.sip.user.voxolo.gy",
                "outbound": {
                    "assigned_to": "Trunks/fa12345c-6d7a-890d-1c23-4dd56cfc7890",
                    "caller_id": {
                        "external_no": "+19495551234",
                        "internal_no": "123",
                        "internal_cnam": "JANEDOE"
                    }
                },
                "transport": "UDP",
                "media": "RTP",
                "inbound": {
                    "uri": "sip:jane@domain.sip.user.voxolo.gy"
                }
            },
            "app_id": "cc12c345-a67b-8901-23f4-56789fa0aef1",
            "subaccount_id": null
        }

Response Codes

Status Description
200 Returns a SIP User object
4xx & 5xx General Error Codes

Create SIP User

Creates a SIP User.

POST /User

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
description User-definable description of the SIP User. string Yes
firstname User-definable first name of the User. string No
lastname User-definable last name of the User. string No
country The country of the User. string (ISO Alpha-2) No
subaccount_id The Sub Account ID for this SIP User. (if applicable) string No
sip Object containing sip settings and information object Yes
sip.authentication Object containing sip authentication credentials. object Yes
sip.authentication.username The SIP User’s username string Yes
sip.authentication.password The SIP User’s password string Yes
sip.domain The unique SIP User URL. string Yes
sip.outbound Object containing outbound information. object Yes
sip.outbound.assigned_to The campaign or trunk to which the SIP user is assigned. string Yes
sip.outbound.caller_id Object containing caller ID information. object No
sip.outbound.caller_id.external_no The caller ID displayed when calling external numbers. string No
sip.outbound.caller_id.internal_no The caller ID displayed when calling internal numbers or extentions. string No
sip.outbound.caller_id.internal_cnam The caller name when calling internal numbers or extentions. string No
sip.transport The type of signaling protocol. Includes: UDP, TCP or TLS string No
sip.media The type of media stream protocol. Includes: RTP or SRTP string No
sip.inbound Object containing the inbound information. object No
sip.inbound.uri The unique SIP URI that calls to this user will be delivered to. string No

Example Request of Inbound Trunk

curl -X POST \
  https://api.voxolo.gy/v1/Users \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "description": "my sip user",
    "firstname": "Jane",
    "lastname": "Doe",
    "country": "US",
        "sip": {
            "authentication": {
                "username": "jane",
                "password": null
            },
            "domain": "domain.sip.user.voxolo.gy",
            "outbound": {
                "assigned_to": "Trunks/fa12345c-6d7a-890d-1c23-4dd56cfc7890",
                "caller_id": {
                    "external_no": "+19495551234",
                    "internal_no": "123",
                    "internal_cnam": "JANEDOE"
                }
            },
            "transport": "UDP",
            "media": "RTP"
        },
    "app_id": "cc12c345-a67b-8901-23f4-56789fa0aef1"
  }'

Response

Property Description Type
created_on The date when the SIP User was created. ISO date string
updated_on The date of the last update to the SIP User. ISO date string
user_id The unique ID of the SIP User. string
status The current status of the SIP User. Includes: active or inactive string
description User-definable description of the SIP User. string
firstname User-definable first name of the User. string
lastname User-definable last name of the User. string
country The country of the User. string (ISO Alpha-2)
uri The URI to view the SIP User’s details. string
sip Object containing sip settings and information object
sip.authentication Object containing sip authentication credentials. object
sip.authentication.username The SIP User’s username string
sip.authentication.password The SIP User’s password string
sip.domain The unique SIP User URL. string
sip.outbound Object containing outbound information. object
sip.outbound.assigned_to The campaign or trunk to which the SIP user is assigned. string
sip.outbound.caller_id Object containing caller ID information. object
sip.outbound.caller_id.external_no The caller ID displayed when calling external numbers. string
sip.outbound.caller_id.internal_no The caller ID displayed when calling internal numbers or extentions. string
sip.outbound.caller_id.internal_cnam The caller name when calling internal numbers or extentions. string
sip.transport The type of signaling protocol. Includes: UDP, TCP or TLS string
sip.media The type of media stream protocol. Includes: RTP or SRTP string
sip.inbound Object containing the inbound information. object
sip.inbound.uri The unique SIP URI that calls to this user will be delivered to. string
app_id The Application ID for this SIP User. string
subaccount_id The Sub Account ID for this SIP User. (if applicable) string

Example Response

{
    "created_on": "2021-08-13T14:23:37.000Z",
    "updated_on": "2022-08-29T21:39:03.000Z",
    "user_id": "952bfde1-8079-4c32-92c3-6339810e1be3",
    "status": "active",
    "description": "my sip user",
    "firstname": "Jane",
    "lastname": "Doe",
    "country": "US",
    "uri": "/v1/Users/952bfde1-8079-4c32-92c3-6339810e1be3",
    "sip": {
        "authentication": {
            "username": "jane",
            "password": null
        },
        "domain": "domain.sip.user.voxolo.gy",
        "outbound": {
            "assigned_to": "Trunks/fa12345c-6d7a-890d-1c23-4dd56cfc7890",
            "caller_id": {
                "external_no": "+19495551234",
                "internal_no": "123",
                "internal_cnam": "JANEDOE"
            }
        },
        "transport": "UDP",
        "media": "RTP",
        "inbound": {
            "uri": "sip:jane@domain.sip.user.voxolo.gy"
        }
    },
    "app_id": "cc12c345-a67b-8901-23f4-56789fa0aef1",
    "subaccount_id": null
}

Response Codes

Status Description
201 SIP User created
4xx & 5xx General Error Codes

Update SIP User

Updates the SIP User configuration of a specified User.

PUT /Users/{user_id}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
user_id The unique ID of the SIP User. string Yes (path)
description User-definable description of the SIP User. string No
firstname User-definable first name of the User. string No
lastname User-definable last name of the User. string No
country The country of the User. string (ISO Alpha-2) No
subaccount_id The Sub Account ID for this SIP User. (if applicable) string No
sip Object containing sip settings and information object No
sip.authentication Object containing sip authentication credentials. object No
sip.authentication.username The SIP User’s username string No
sip.authentication.password The SIP User’s password string No
sip.domain The unique SIP User URL. string No
sip.outbound Object containing outbound information. object No
sip.outbound.assigned_to The campaign or trunk to which the SIP user is assigned. string No
sip.outbound.caller_id Object containing caller ID information. object No
sip.outbound.caller_id.external_no The caller ID displayed when calling external numbers. string No
sip.outbound.caller_id.internal_no The caller ID displayed when calling internal numbers or extentions. string No
sip.outbound.caller_id.internal_cnam The caller name when calling internal numbers or extentions. string No
sip.transport The type of signaling protocol. Includes: UDP, TCP or TLS string No
sip.media The type of media stream protocol. Includes: RTP or SRTP string No
sip.inbound Object containing the inbound information. object No
sip.inbound.uri The unique SIP URI that calls to this user will be delivered to. string No

Example Request

curl -X PUT \
  https://api.voxolo.gy/v1/Users/952bfde1-8079-4c32-92c3-6339810e1be3 \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "description": "updated description"
  }'

Response

Property Description Type
created_on The date when the SIP User was created. ISO date string
updated_on The date of the last update to the SIP User. ISO date string
user_id The unique ID of the SIP User. string
status The current status of the SIP User. Includes: active or inactive string
description User-definable description of the SIP User. string
firstname User-definable first name of the User. string
lastname User-definable last name of the User. string
country The country of the User. string (ISO Alpha-2)
uri The URI to view the SIP User’s details. string
sip Object containing sip settings and information object
sip.authentication Object containing sip authentication credentials. object
sip.authentication.username The SIP User’s username string
sip.authentication.password The SIP User’s password string
sip.domain The unique SIP User URL. string
sip.outbound Object containing outbound information. object
sip.outbound.assigned_to The campaign or trunk to which the SIP user is assigned. string
sip.outbound.caller_id Object containing caller ID information. object
sip.outbound.caller_id.external_no The caller ID displayed when calling external numbers. string
sip.outbound.caller_id.internal_no The caller ID displayed when calling internal numbers or extentions. string
sip.outbound.caller_id.internal_cnam The caller name when calling internal numbers or extentions. string
sip.transport The type of signaling protocol. Includes: UDP, TCP or TLS string
sip.media The type of media stream protocol. Includes: RTP or SRTP string
sip.inbound Object containing the inbound information. object
sip.inbound.uri The unique SIP URI that calls to this user will be delivered to. string
app_id The Application ID for this SIP User. string
subaccount_id The Sub Account ID for this SIP User. (if applicable) string

Example Response

{
    "created_on": "2021-08-13T14:23:37.000Z",
    "updated_on": "2022-08-29T21:39:03.000Z",
    "user_id": "952bfde1-8079-4c32-92c3-6339810e1be3",
    "status": "active",
    "description": "updated description",
    "firstname": "Jane",
    "lastname": "Doe",
    "country": "US",
    "uri": "/v1/Users/952bfde1-8079-4c32-92c3-6339810e1be3",
    "sip": {
        "authentication": {
            "username": "jane",
            "password": null
        },
        "domain": "domain.sip.user.voxolo.gy",
        "outbound": {
            "assigned_to": "Trunks/fa12345c-6d7a-890d-1c23-4dd56cfc7890",
            "caller_id": {
                "external_no": "+19495551234",
                "internal_no": "123",
                "internal_cnam": "JANEDOE"
            }
        },
        "transport": "UDP",
        "media": "RTP",
        "inbound": {
            "uri": "sip:jane@domain.sip.user.voxolo.gy"
        }
    },
    "app_id": "cc12c345-a67b-8901-23f4-56789fa0aef1",
    "subaccount_id": null
}

Response Codes

Status Description
200 Returns the User Object
4xx & 5xx General Error Codes

Delete SIP User

Deletes the specified SIP User.

DELETE /Users/{user_id}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
user_id The ID of the SIP User . string (path) Yes

Example Request

curl -X DELETE \
  https://api.voxolo.gy/v1/Users/952bfde1-8079-4c32-92c3-6339810e1be3 \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

No Response Body

Response Codes

Status Description
204 No content on success.
4xx & 5xx General Error Codes

Transcription

Start Transcription

Initiates speech-to-text transcription on a specified live call.

POST /LiveCalls/{call_id}/Actions/Transcription/Start

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
call_id ID of the call. string (path) Yes
tracks Defines which sides of the call to transcribe. Accepts caller (far end), transfer (near end). Default: caller. array No
hints An array of strings of known/possible words used on the call, that may be difficult to transcribe correctly, to help with accuracy. array No
live_transcript_webhook Object with configuration of where to send live transcription webhooks. If not provided, no live transcription webhooks are sent. object No
live_transcript_webhook.url The URL destination to send the webhooks to. string No
live_transcript_webhook.method The request method. Accepts GET and POST. Default: POST. string No
live_transcript_webhook.content_type The format of the payload posted to the endpoint. Accepts: application/json, application/xml, application/x-www-form-urlencoded. Default: application/json. string No
end_transcript_webhook Object with configuration of where to send the final transcription webhook at the end of the call. If not provided, transcript is sent to the URL in the default callback configuration. object No
end_transcript_webhook.url The URL destination to send the webhook to. string No
end_transcript_webhook.method The request method. Accepts GET and POST. Default: POST. string No
end_transcript_webhook.content_type The format of the payload posted to the endpoint. Accepts: application/json, application/xml, application/x-www-form-urlencoded. Default: application/json. string No
end_transcript_webhook_failover Object with configuration of where to send the final transcription webhook after the call if the request to the primary URL fails. object No
end_transcript_webhook_failover.url The URL destination to send the webhook to. string No
end_transcript_webhook_failover.method The request method. Accepts GET and POST. Default: POST. string No
end_transcript_webhook_failover.content_type The format of the payload posted to the endpoint. Accepts: application/json, application/xml, application/x-www-form-urlencoded. Default: application/json. string No

Example Request

curl -X POST \
  https://api.voxolo.gy/v1/LiveCalls/123456@7890/Actions/Transcription/Start \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "tracks": [
      "caller",
      "transfer"
    ],
    "hints": [
        "Voxology",
        "CPaaS",
        "API"
    ],
    "live_transcript_webhhok": {
        "url": "https://example.webhook.com/live_transcript",
    },
    "end_transcript_webhook": {
        "url": "https://example.webhook.com/end_transcript"
    },
    "end_transcript_failover": {
        "url": "https://example.webhhok.com/end_transcript_failover"
    }
    "
  }'

Response

No Response Body

Response Codes

Status Description
204 No content on success.
4xx & 5xx General Error Codes

Stop Transcription

Stops speech-to-text transcription on a specified live call.

POST /LiveCalls/{call_id}/Actions/Transcription/Stop

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
call_id ID of the call. string (path) Yes

Example Request

curl -X POST \
  https://api.voxolo.gy/v1/LiveCalls/123456@7890/Actions/Transcription/Stop \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \

Response

No Response Body

Response Codes

Status Description
204 No content on success.
4xx & 5xx General Error Codes

Variables

Voxology’s JSON Call Flow Actions support the use of variables much like traditional programming languages. In fact, our variables and expressions are evaluated by an ES5 JavaScript engine. All basic JavaScript data types (string, number, boolean, array and object) are supported. Expressions are evaluated as one would expect in JavaScript.

Here are some notable details to keep in mind:

Native Constants

For convenience, some constants are made available with data about the call. These are assigned to variables and are listed below. These variables are read-only and any attempts to change their values will fail silently.

Variable Name Type Description
$config object The callback configuration object set with the /CallFlows/Callbacks request.
$lastQueuePollConnectCall object The last call bridged with a QUEUE poll_connect. Includes properties id and no.
$direction string Indicates if the call is INBOUND or OUTBOUND
$iniatedBy string Indicates the origin of the current call. Possible values include api for outbound Make Call requests, sip_user and sip for inbound calls from SIP Users and SIP Interface, pstn for basic inbound calls, dial and transfer for outbound DIAL and TRANSFER action calls.
$keyPresses string The last key presses collected by the COLLECT action. To check for no keys pressed, use $keyPresses == "".
$extensionDialed string If the digits pressed in a COLLECT action match an existing extension on your application, that extension is stored here. The value will be stomped by any subsequent extensions entered.
$now integer The current timestamp in milliseconds.
$callTime integer The duration of the call in milliseconds.
$startTime integer The start timestamp of the call in milliseconds.
$numConferenceParticipants string The number of participants in the last conference referenced by the CONFERENCE action during the call. Do not use before a conference has been accessed by the action to avoid a terminal error.
$callId string The unique ID of the call.
$parentCallID string When using the DIAL action, this is the call_id of the originating call. The value is null if there is no originating call.
$appId string The unique ID of the application.
$collectAttempt integer This variable counts how many times a call has visited each COLLECT action, starting with 1. This counter makes it easy to retry a COLLECT with IF and GOTO actions.
$callerNo string The phone number of the connected (or far end) call (E.164 format: +17145551212).
$callerNoLatitude string The latitude of the connected call’s phone number. Possibly null.
$callerNoLongitude string The longitude of the connected call’s phone number. Possibly null.
$callerNoPostalCode string The postal code (zip) of the connected call’s phone number. Possibly null.
$callerNoCity string The city of the connected call’s phone number. Possibly null.
$callerNoRateCenter string The rate center of the connected call’s phone number, if applicable. Possibly null.
$callerNoLata string The lata of the connected call’s phone number, if applicable. Possibly null.
$callerNoRegion string The two-character region (state) code of the connected call’s phone number. Possibly null.
$callerNoCountry string The two-character country code of the connected call’s phone number. Possibly null.
$callerNoTimeZone string The time zone of the connected call’s phone number (America/Los_Angeles). Possibly null. Click here for list of time zones.
$apiNo string The provisioned (or near end) phone number of the API connected to the call (E.164 format: +17145551212).
$apiNoLatitude string The latitude of the API phone number. Possibly null.
$apiNoLongitude string The longitude of the API phone number. Possibly null.
$apiNoPostalCode string near phone number zip/postal code
$apiNoCity string The city of the API phone number. Possibly null.
$apiNoRateCenter string The rate center of the API phone number, if applicable. Possibly null.
$apiNoLata string The lata of the API phone number, if applicable. Possibly null.
$apiNoRegion string The two-character region (state) code of the API phone number. Possibly null.
$apiNoCountry string The two-character country code of the API phone number. Possibly null.
$apiNoTimeZone string The time zone of the API phone number (America/Los_Angeles). Possibly null. Click here for list of time zones.
$speechText string The last speech to text collected by the COLLECT action. To check for collected text, use $speechText == "hello".
$speechConfidenceScore float The confidence score from the last COLLECT action. Ranges from 0-1.
$stirShakenStatus string A status indicating the STIR/SHAKEN attestation level assigned to the call; includes number validation on inbound calls. See the STIR SHAKEN Status table for details.

User Defined Variables

In addition to the special writable variables $sessionData and $webhookData, you are free to create your own local variables using any of the supported data types (string, number, boolean, array and object).

Variable Name Type Description
$sessionData object The session_data set in the /Dials/Connect request and/or the DIAL and SESSIONDATA actions.
$webhookData object When a WEBHOOK action returns a JSON response, it is available via this variable. Default: undefined.
$userSipHeaders object If user_sip_headers are provided on a DIAL or TRANSFER, they are available via this variable. The key/value pairs will be flattened and converted to User-to-User and X-... SIP headers on the call. Default: undefined.

Variable Handling

Using variables in Voxology’s JSON Call Flow Actions is very straight-forward once you get the hang of it. Variable assignment is done with a “special” JSON Action. This action is simplified to make variable handling as pleasant as possible in JSON.

Tutorial

The JSON KEY is the name of the variable and the JSON VALUE is the expression to evaluate. The right-side JSON value MUST ALWAYS be a STRING.

Basically, take a regular JavaScript variable assignment:

Change the = to a : and wrap both sides in double-quotes (with the necessary escaping) to make it JSON-friendly:

String assignment as done in plain JavaScript:

String assignment as done in a JSON Action (notice the nested quoting):

While it is tempting (since it is legal JSON) to try assigning basic data types like this:

It will not work! Remember, the right-side value is actually an expression that is evaluated. This lets us do things like this:

In the above example, notice how multiple variables are handled in one JSON Action object. This is legal, however assignment order is NOT guaranteed. If assignment order is critical, separate the assignments into their own objects as array order is guaranteed:

Examples

Example User Defined Variables

{
  "actions": [
    {
      "type": "SAY",
      "params": {
        "text": "We're about to assign some variables."
      }
    },
    {
      "$conferenceName": "'MyConference'",
      "$counter": "0",
      "$myObj": "{}",
      "$myPets": "['Whiskers', 'Spot', 'Bubbles']",
      "$myPetsAgain": "{cat: 'Whiskers', dog: 'Spot', fish: 'Bubbles'}"
    },
    {
      "$conferenceName": "'MyConference' + $counter"
    },
    {
      "$sessionData.isInConference": "false"
    },
    {
      "$myObj.foo": "'bar'"
    },
    {
      "$counter": "$counter + 1"
    },
    {
      "$myDog": "$myPets[1]"
    },
    {
      "$myPetsAgain.bird": "'Tweety'"
    }
  ]
}
Variable:Expression Comment
“$conferenceName”: “‘MyConference’” Notice how the MyConference string must use inner single-quotes.
“$counter”: “0” Numbers, booleans, arrays and objects must be in quotes.
Variable:Expression Comment
“$conferenceName: ”'MyConference’ + $counter" Updates $conferenceName to “myConference0”.
“$sessionData.isInConference: "false” Updates $sessionData.isInConference to false.
“$myObj.foo”: “'bar’” Updates a previously initialized object.
“$counter”: “$counter + 1” Increments $counter by one.
“$myDog”; “$myPets[1]” Assigns value at index 1 (“Spot”) to $myDog.
“$myPetsAgain.bird”: “'Tweety’” Adds new key/value to $myPetsAgain.

Template Mapping

Template Mappings look like {{property}} and {{property|default}}, where property is the callback data property name (flattened) and default is an optional default value to use if no property name match is found.

Example Template Mapping

{
  "actions": [
    {
      "type": "SAY",
      "params": {
        "text": "Hello, {{session_data.firstName|guest}}. Welcome to our conference.",
        "loop": 1
      }
    },
    {
      "type": "CONFERENCE",
      "params": {
        "name": "{{session_data.conferenceName}}"
      }
    },
    {
      "type": "SAY",
      "params": {
        "text": "You have left the conference. This call lasted {{duration}} seconds."
      }
    }
  ]
}

String Interpolation

It is possible to dynamically use variables in select Action properties, like SAY’s “text” property.

Supported properties are marked with an asterisk (*) in our docs. These will be parsed live.

By adding the spread (...) operator before a variable name, you can have the SAY action say each character individually. This is useful for reading back numeric strings like key presses, phone number, zip code, SSN, credit card, etc.

Example String Interpolation

{
  "actions": [
    {
      "type": "SAY",
      "params": {
        "text": "Hello, ${sessionData.firstName}. Welcome to our conference.",
        "repeat": 1
      }
    },
    {
      "type": "CONFERENCE",
      "params": {
        "name": "myConference"
      }
    },
    {
      "type": "SAY",
      "params": {
        "text": "You have left the conference. Thank you for calling ${...callerNo}."
      }
    }
  ]
}

Errors

General Errors

Status Code Message Help User_message
400 400001 Validation Error [Custom Message with what failed validation] [Custom Message]
400 400010 Parsing Error [Custom Message] A 3rd party service could not understand our request.
400 400999 [Custom Message] It appears that the request was invalid. Check the ‘message’ property for more detail. A 3rd-party service could not understand your request. This could be due to submitting invalid data.
401 401001 Failed Authentication We are unable to authenticate your request. Your API Key may be inaccurate or missing. For all application or sub account requests, use the API Key found on the Application page in the portal: https://portal.voxolo.gy/. We are having trouble accessing a 3rd Party service.
401 401002 Failed Authentication We are unable to authenticate your request. Your auth string may be inaccurate or missing. For all account level requests, use the basic auth authorization header found on your Account page in the portal: https://portal.voxolo.gy/. We are having trouble accessing a 3rd Party service.
402 402001 Insufficient Funds Your account balance is too low. Please make a payment to resume service. A 3rd-party service could not complete the request. Report code 402001 to customer support.
403 403001 Forbidden Requests must be made through https://api.voxolo.gy. The specified phone number(s) were not assigned.
404 404001 Not Found The endpoint you are trying to access does not exist. Check your code for typos. Review our docs. We are having trouble accessing a 3rd Party service.
404 404002 Not Found The requested resource path or method is not supported. The resource we attempted to access no longer exists.
405 405001 Method Not Found This API does not support the X method.
429 400429 Too Many Requests You exceeded your maximum requests per minute. A 3rd-party service could not complete the request. Report code 400429 to customer support.
500 500990 [Custom Message] It appears that our upstream server threw an internal error. You will likely need to contact support to clear this up. A 3rd-party service could not process your request.
500 500991 Server Error [Custom Message] A 3rd party service failed to handle our request.
500 500999 Uncaught Error: [fault.name]; [fault.type]; [fault.category] This error occurred in our proxy layer. Check the 'message’ for details and contact support if the error continues. A 3rd-party service returned an unexpected error.
500 500911 Fatal System Error [Custom Message] Contact Support. [Custom Message]

Caller ID Errors

Status Code Message Help User_message
400 404254 1001: failed to insert caller-id: this caller-id already exists It appears that the request was invalid. Check the 'message’ property for more detail. A 3rd-party service could not understand your request. This could be due to submitting invalid data.
404 404254 Not Found The Call ID Number does not exist in your application. It may have been removed or never added. The Caller ID Number could not be found.

Call Flow Errors

Status Code Message Help User_message
404 404102 Not Found The Call ID Number does not exist in your application. It may have been removed or never added. The Caller ID Number could not be found.
500 500101 Storage Error [Custom Message] [Custom Message]
500 500102 Database Error [Custom Message] [Custom Message]

Conference Errors

Status Code Message Help User_message
404 404404 Not Found The Call ID is incorrect or the call ended and is longer available via LiveCalls. A live call could not be found with the ID provided.
404 404701 Not Found The conference may have been empty too long and destroyed. The requested conference participant was not found.
404 404702 Not Found The participant may not be in the conference any longer. The requested conference participant was not found.

Integration Errors

Status Code Message Help User_message
500 500501 Storage Error [Custom Message] [Custom Message]

Live Calls Errors

Status Code Message Help User_message
400 400999 The underlying audio file you are attempting to play on the call was not found. Check your audio file. It appears that the request was invalid. Check the 'message’ property for more detail. A 3rd-party service could not understand your request. This could be due to submitting invalid data.
404 404404 Not Found The Call ID is incorrect or the call ended and is longer available via LiveCalls. A live call could not be found with the ID provided.

Make Call Error

Status Code Message Help User_message
429 400378 Too many calls Failed to make call due to call throttle limit. A 3rd-party service could not complete the request. Report code 400378 to customer support.

Message Errors

Status Code Message Help User_message
403 403293 Unable to make call. Caller ID verification required. In order to make a call appear from this phone number, it must be a verified Caller ID on the application or sub account from which you are making the request. A 3rd-party service could not process your request.

Payment Errors

Status Code Message Help User_message
400 400300 Payment was not successful: [Reason] Please provide a valid payment method. Payment was not successful: [Reason]

Phone Number Errors

Status Code Message Help User_message
400 400200 Bad Request The numbers are already assigned to the API. The specified phone number(s) are already assigned to this API.
400 400201 Bad Request None of the numbers are assigned to this API. No phone numbers could be released. No numbers are assigned to this API.
400 400202 Bad Request The /PhoneNumbers/_ resource does not support phone number provisioning. A 3rd-party service could not understand your request. This could be due to submitting invalid data.
400 400203 Bad Request [Custom Message] The search was invalid. This is likely due to an invalid combination of search criteria.
404 400404 Phone number not found [provided phone number] not found A 3rd-party service could not understand your request. This could be due to submitting invalid data.
404 404214 Phone number not found The Phone Numbers(s) do not exist in your application. The Phone Number(s) could not be found.
423 423001 Concurrent Request Error Provisioning and releasing phone numbers does not support concurrent requests per API Key. On status 423, try again after a few seconds. Our service was busy modifying phone numbers. Please try again.
500 500200 Server Error Updating the phone numbers list failed. This likely means that nothing has changed. Verify by pulling the list to check for changes. The specified phone number(s) were not assigned.
500 500201 Database Error The numbers were updated, but DB syncing failed. This error will not affect your applications. The specified phone number(s) were updated with non-fatal errors.

Queue Errors

Status Code Message Help User_message
404 404711 Not Found The queue ID may be wrong or the queue could have been garbage collected. The requested queue was not found.
404 404712 Not Found The call is not in the queue. It may have left the queue already. The requested queued call was not found.
404 404713 Not Found The queue is empty. No call was found. The queue is empty. No call was found.

Sub Account Errors

Status Code Message Help User_message
403 403803 Forbidden You cannot delete due to usage on the Sub Account. If you want to deactivate this Sub Account you may update the “status” to “inactive” using the PUT method. This Sub Account cannot be deleted due to historical usage. You may, however, deactivate the Sub Account.
404 404801 Not Found The Sub Account ID is incorrect. A Sub Account by that ID never existed under this application. A 3rd-party service could not find the requested resource.
404 404802 Not Found The Sub Account ID references a Sub Account that no longer exists. A 3rd-party service reports that the requested resource is no longer available.

Call Flow Loop Errors

Code Direction When Phone Message Issue
1003 inbound post-connect This number is temporarily unavailable. Please try again later. ID [XXXXXX]. Error Code 1003. The Application or Sub Account belonging to this number has been deactivated - activate the Application or Sub Account.
2001 inbound post-connect This number is temporarily unavailable. Please try again later. ID [XXXXXX]. Error Code 2001. Your account balance is $0.00 - add money to your account.
4001 inbound/outbound pre-connect We’re sorry, all circuits are busy right now. Please try your call again later. Error code 4001. The request to your callback url timed out.
400900 inbound pre-connect n/a We received a non-2XX status code back from your callback url(s) - see call logs for more details.
400901 inbound post-connect We’re sorry, something went wrong. Error code 400901. Good bye. We received a non-2XX status code back from your callback url(s)- see call logs for more details.
400902 inbound pre-connect/post-connect We’re sorry, something went wrong. Error code 400902. Good bye. Your callback response did not contain JSON actions.
400910 outbound pre-connect n/a We received a non-2XX status code back from your callback url(s) - see call logs for more details.
400911 outbound post-connect on init_call callback response We’re sorry, something went wrong when trying to reach you. Error code 400911. Good bye. We received a non-2XX status code back from your callback url(s) - see call logs for more details.
400912 outbound post-connect after init_call callback response We’re sorry, something went wrong. Error code 400912. Good bye. We received a non-2XX status code back from your callback url(s) - see call logs for more details.
400913 outbound pre-connect/post-connect We’re sorry, something went wrong when trying to reach you. Error code 400913. Good bye. Your callback response did not contain JSON actions.
400931 inbound/outbound pre-connect/post-connect We’re sorry, something went wrong. Error code 400931. Good bye. Your callback response included a url that we were unable to fetch (for example: a PLAY audio file url that returned a 404) - see callback and call logs for more details.
413900 inbound pre-connect/post-connect We’re sorry, something went wrong. Error code 413900. Good bye. Your callback response exceeded the hard JSON callback limit of 81 KB.
413910 outbound pre-connect/post-connect We’re sorry, something went wrong when trying to reach you. Error code 413910. Good bye. Your callback response exceeded the hard JSON callback limit of 81 KB.
413901 inbound pre-connect/post-connect We’re sorry, something went wrong. Error code 413901. Good bye. Your callback response exceeded the compiled limit.
413911 outbound pre-connect/post-connect We’re sorry, something went wrong when trying to reach you. Error code 413911. Good bye. Your callback response exceeded the compiled limit.
cURL