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 created a Postman collection which can be used to test the various API methods.

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

Click the button below to download our collection and have fun! Last Updated on December 04, 2019.

Run in Postman

The collection comes with 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, 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

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",
  "is_webhook": "false",
  "app_id": "29a471cc-4ada-4249-a7a5-5046464f9887",
  "subaccount_id": 0,
  "call_id": "12345@678",
  "parent_call_id": "12345@677",
  "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"]}],
  "recordings": [{ "name": "recordingName", "id": "ABC123" }],
  "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"
}

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
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
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
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
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 Message 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 message",
  "status": "received"
}

Request

Property Description Type When
service The name of the service. Returns: programmable_messaging. string all
type The type of message. Returns: sms 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

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.

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

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.

Actions

COLLECT

Record Keypresses from Callers.

A loop can contain one or more COLLECT action. 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 in the COLLECT action will be returned in the callback request.

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

Example Response

{
  "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 // Advanced

{
  "actions": [
    {
      "$nextUrl": "'operator.json'"
    },
    {
      "type": "LABEL",
      "name": "PROMPT_MENU_CHOICE"
    },
    {
      "type": "COLLECT",
      "actions": [
        {
          "type": "SAY",
          "params": {
            "text": "Press1forsales.Press2forservice."
          }
        }
      ],
      "params": {
        "num_digits": 1
      }
    },
    {
      "type": "IF",
      "condition": "! $keyPresses && $collectAttempt < 3",
      "then": [
        {
          "type": "GOTO",
          "params": {
            "label": "PROMPT_MENU_CHOICE"
          }
        }
      ]
    },
    {
      "type": "IF",
      "condition": "$keyPresses=='1'",
      "then": [
        {
          "$nextUrl": "'sales.json'"
        }
      ]
    },
    {
      "type": "IF",
      "condition": "$keyPresses=='2'",
      "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 and WAV. 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** number 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
detection How to identify a connection. Accepts: preconnect, full, none. 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 number No
timeout The maximum time to wait during ringing in seconds. Valid: 20 to 240. 50 number 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",
        "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 and WAV. 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 number No
dtmf_dash_delay The delay represented by each dash - in milliseconds (for DTMF only). 250 number No
repeat How many times to repeat the audio or DTMF. 1 number 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* number 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. 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
group A name that is queryable in the recordings lookup resource. caller_no string No

Example Response

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

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. 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 number No
timeout The maximum amount of silence before a recording is stopped in seconds. Valid: 1 to 60. 5 number No

Example Response

{
  "actions": [
    {
      "type": "RECORDMESSAGE",
      "params": {
        "group": "support_technical",
        "action": "start"
      }
    }
  ]
}

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"

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 number 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

Example Response

{
  "actions": [
    {
      "type": "SMS",
      "params": {
        "no": "+19495551111",
        "caller_id_no": "+17145552222",
        "message": "Hello, world!"
      }
    }
  ]
}

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

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_ no in 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
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

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

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

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. number (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. number
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

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.00
}

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. number (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 number
transaction_id Transaction ID (from payment processor) number
submitted_on Datetime of transaction. ISO Date string
amount Amount of payment. number
description User-definable description of payment. string

Example Response

{
  "id": 123,
  "transaction_id": 12345,
  "submitted_on": "2016-09-07T17:27:23.486Z",
  "amount": 20.00,
  "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 number
payments[i].transaction_id Transaction ID (from payment processor) number
payments[i].submitted_on Datetime of transaction. ISO Date string
payments[i].amount Amount of payment. number
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"
    },
    "sip_domains": {
      "callflows": "0000-0000.accounts.sip.voxolo.gy"
    }
  }'

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

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

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
app_id The ID of the App string
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

{
  "app_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "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
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"
  }
}

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) Yes
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 (body) No
status The current status of the subaccount. Accepts: active or inactive. string (body) 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 (body) Conditional
service_address.address_2 Address line 2 (Suite/Unit/Apartment) string (body) Conditional
service_address.city City/Town/Village/District string (body) Conditional
service_address.region Region/State/Province string (body) Conditional
service_address.postal_code The postal or zip code string (body) Conditional
service_address.country The service address country code. The country code must be given in ISO Alpha-2 format string (body) Conditional
service_address.type_of_service The type of service address. Accepts: business or residence string (body) Conditional

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",
    "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
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",
  "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 (body) No

Example Request

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

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. number

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
}

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

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. number

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
    }
  ],
    "pagination": {
      "current_page": 0,
      "total_pages": 1,
      "total_items": 1,
      "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. number

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
}

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

Example Request

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

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. number

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
}

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/%2B19495551212' \
  -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. After the message, the PIN in the response must be entered to allow the Caller ID to be used in outbound dialing.

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/%2B19495551212/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. string

Example Response

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

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

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}

You may assign unique Call Flow Configurations to any Inbound Phone Number or Verified Outbound Caller ID, or you may assign a Default Call Flow Configuration on the Application or on any Application’s Sub Account, which 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.

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) Yes
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. 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. number (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. 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. 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. For example, a private key to verify requests. 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 // Callback Config with SMS and Failover Endpoints

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"
      }
    },
    "callback_failover": {
      "method": "GET",
      "url": "https://s3.amazonaws.com/com.mydomain.actions/failover_actions.json",
      "content_type": "application/json"
    },
    "callback_sms": {
      "method": "POST",
      "url": "https://myserver.com/ivr_app/callback-sms-handler",
      "content_type": "application/json"
    },
    "callback_sms_failover": {
      "method": "POST",
      "url": "https://myserver.com/ivr_app/callback-sms-handler-failover",
      "content_type": "application/json"
    },
    "custom_data": {
      "foo": "bar"
    }
  }'

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. 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. 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. number
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. 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. 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
last_set_on The datetime the Call Flow configuration was last updated (Will be replaced by updated_on). string
updated_on The date/time the Call Flow configuration was last updated. string
custom_data Any data you want included in every request. For example, a private key to verify requests. object

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,
  "last_set_on": "2019-01-29T16:24:21-08:00",
  "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"
}

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,
  "last_set_on": "2019-01-29T16:24:21-08:00",
  "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"
}

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.

GET /CallFlows/Configurations/PhoneNumbers?{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

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'

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. 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. 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. 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].last_set_on The date/time the Call Flow configuration was last updated (Will be replaced by updated_on). 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. For example, a private key to verify requests. object

Example Response

{
  "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,
      "last_set_on": "2019-01-29T16:24:21-08:00",
      "updated_on": "2019-01-29T16:24:21-08:00",
      "created_on": "2018-04-16T13:43:32-07:00",
      "custom_data": null
    }
  ],
    "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 or the callback configuration of a specific phone number. Phone number must be in E.164 format. (example: +17145551212)

Phone Number Configuration

GET /CallFlows/Configurations/PhoneNumbers/{phone_number}

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

Example Request

curl -X GET \
  'https://api.voxolo.gy/v1/CallFlows/Configurations/PhoneNumbers/%2B17145551212' \
  -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. 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. number
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. 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. 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. For example, a private key to verify requests. object
created_on The date/time the Call Flow configuration was first created. string
last_set_on The date/time the Call Flow configuration was last updated (Will be replaced by updated_on). string
updated_on The date/time the Call Flow configuration was last updated. string

Example Response

{
  "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,
  "last_set_on": "2019-01-29T16:24:21-08:00",
  "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. Phone number must be in E.164 format. (example: +17145551212)

This method does not release the phone number.

Default Configuration

DELETE /CallFlows/Configurations/Default

Phone Number Configuration

DELETE /CallFlows/Configurations/PhoneNumbers/{phone_number}

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

Example Request

curl -X DELETE \
  'https://api.voxolo.gy/v1/CallFlows/Configurations/PhoneNumbers/%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 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
inbound_api Defaults to CallFlows. string (body) No
timeout The maximum time to wait during ringing in seconds. Valid: 20 to 240. number (body) No
max_call_time The maximum length of the call in seconds. Valid: 60 to 172800. number (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",
    "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
filter_on_apis A comma-separated list of APIs to filter on. Accepts: CallFlows 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. This will default to voice after Feb 28, 2019. 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&connectTime=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].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
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",
      "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",
        "last_set_on": "2019-01-29T16:24:21-08:00",
        "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"
    }
  ],
  "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
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

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",
    "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",
      "last_set_on": "2019-01-29T16:24:21-08:00",
      "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",
    "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, 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, 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.

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, 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 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 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, 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/conferenceId/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, 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, 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, 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, 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, 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, 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, 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, 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

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 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) were the message will be sent. Phone numbers are in E.164 format (example: +19495551212). string Yes
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 Yes
text_message The text body of the message. NOTE: While SMS messages may be batched up to 1600 characters, they are billed in parts based on the type of characters used. 7-bit character messages are batched into parts with a maximum of 152 characters/part, and Unicode character messages are batched into parts with a maximum of 66 characters/part. Message parts will be indicated in the num_parts property in the messages logs. string Yes
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. 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 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",
    "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) were the message will be sent. Phone numbers are in E.164 format (example: +19495551212). string
text_message The text body of the message. NOTE: While SMS messages may be batched up to 1600 characters, they are billed in parts based on the type of characters used. 7-bit character messages are batched into parts with a maximum of 152 characters/part, and Unicode character messages are batched into parts with a maximum of 66 characters/part. Message parts will be indicated in the num_parts property in the messages logs. string
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. string
message_id The message ID of the outbound message. string
status The status of the message. Includes: accepted 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",
  "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

List Messages

Returns a list of messages which may be filtered by date, phone numbers, direction, external ID, and 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. 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

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 \
  -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].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].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. 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. 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",
      "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": "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",
      "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",
        "last_set_on": "2019-01-29T16:24:21-08:00",
        "updated_on": "2019-01-29T16:24:21-08:00",
        "created_on": "2018-04-16T13:43:32-07:00",
      },
      "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
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
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",
  "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",
    "last_set_on": "2019-01-29T16:24:21-08:00",
    "updated_on": "2019-01-29T16:24:21-08:00",
    "created_on": "2018-04-16T13:43:32-07:00",
  },
  "status_webhook": null
}

Example Response // Outbound

{
  "service": "programmable_messaging",
  "type": "sms",
  "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",
  "api_no": "+17145551212",
  "direction": "outbound",
  "status": "sent",
  "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: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

Phone Numbers

List Available Inbound Numbers

Returns a list of phone numbers available for provisioning and purchase.

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 and sms. 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, 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&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[] Capabilities supported by the phone number. Returns: voice_inbound, voice_outbound, sms_inbound, sms_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

Example Response

{
  "phone_numbers": [
    {
      "no": "+19495551212",
      "formatted": "(949) 555-1212",
      "type": "local",
      "capabilities": [
        "sms_inbound",
        "sms_outbound",
        "voice_inbound",
        "voice_outbound"
      ],
      "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-07:00",
      "estimated_active_date_user_message": "immediately"
    },
    {
      "no": "+19495551213",
      "formatted": "(949) 555-1213",
      "type": "local",
      "capabilities": [
        "voice_inbound",
        "voice_outbound"
      ],
      "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-07:00",
      "estimated_active_date_user_message": "immediately"
    },
    {
      "no": "+19495551214",
      "formatted": "(949) 555-1214",
      "type": "local",
      "capabilities": [
        "voice_inbound",
        "voice_outbound"
      ],
      "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-07:00",
      "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"
      ],
      "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-07:00",
      "estimated_active_date_user_message": "less than a day"
    },
    {
      "no": "+18339741022",
      "formatted": "(833) 974-1022",
      "type": "tollfree",
      "capabilities": [
        "voice_inbound",
        "voice_outbound"
      ],
      "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-07:00",
      "estimated_active_date_user_message": "less than a day"
    },
    {
      "no": "+18339741026",
      "formatted": "(833) 974-1066",
      "type": "tollfree",
      "capabilities": [
        "voice_inbound",
        "voice_outbound"
      ],
      "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-07:00",
      "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) Yes
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
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[] Capabilities supported by the phone number. Returns: voice_inbound, voice_outbound, sms_inbound, sms_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. number
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].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

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"
      ],
      "caller_id_name": "Bob Jones",
      "status": "routed",
      "usage": 100,
      "price": 1,
      "price_period": "day",
      "created_on": "2019-03-08T13:15:33-08:00",
      "updated_on": "2019-12-03T16:20:42-08:00",
      "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"
      },
      "estimated_active_date": "2018-08-22T14:55:52-07:00",
      "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 numbers 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[] Capabilities supported by the phone number. Returns: voice_inbound, voice_outbound, sms_inbound, sms_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
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

Example Response

{
  "no": "+19495551212",
  "formatted": "(949) 555-1212",
  "assigned_to": "CallFlows",
  "description": "Office Desk Phone",
  "capabilities": [
    "sms_inbound",
    "sms_outbound",
    "voice_inbound",
    "voice_outbound"
  ],
  "caller_id_name": "Bob Jones",
  "status": "routed",
  "usage": 100,
  "price": 1,
  "price_period": "day",
  "created_on": "2019-03-08T13:15:33-08:00",
  "updated_on": "2019-12-03T16:20:42-08:00",
  "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"
  },
  "estimated_active_date": "2018-08-22T14:55:52-07:00",
  "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}.

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

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"
      },
      {
        "no": "+19495551213"
      },
      {
        "no": "+19495551214"
      }
    ]
  }'

Note: The API will except the complete phone_numbers object returned by GET /PhoneNumbers/Available. However, only no is required.

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[] Capabilities supported by the phone number. Returns: voice_inbound, voice_outbound, sms_inbound, sms_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. number
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].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

Example Response

{
  "assigned_to": "CallFlows",

  "phone_numbers": [
    {
      "no": "+19495551212",
      "formatted": "(949) 555-1212",
      "assigned_to": "CallFlows",
      "description": "",
      "capabilities": [
        "sms_inbound",
        "sms_outbound",
        "voice_inbound",
        "voice_outbound"
      ],
      "caller_id_name": "Bob Jones",
      "status": "routed",
      "usage": 0,
      "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"
      },
      "estimated_active_date": "2019-04-10T10:01:56-07:00"
    },
    {
      "no": "+19495551213",
      "formatted": "(949) 555-1213",
      "assigned_to": "CallFlows",
      "description": "",
      "capabilities": [
        "cnam",
        "voice_inbound",
        "voice_outbound"
      ],
      "caller_id_name": "TRABUCO      CA",
      "status": "routed",
      "usage": 0,
      "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"
      },
      "estimated_active_date": "2019-04-10T10:01:56-07:00"
    },
    {
      "no": "+19495551214",
      "formatted": "(949) 555-1214",
      "assigned_to": "CallFlows",
      "description": "",
      "capabilities": [
        "cnam",
        "voice_inbound",
        "voice_outbound"
      ],
      "caller_id_name": "TRABUCO      CA",
      "status": "routed",
      "usage": 0,
      "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"
      },
      "estimated_active_date": "2019-04-10T10:01:56-07:00"
    }
  ]
}

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/{no}

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
no Phone number in E.164 format. string (path) Yes
description User-definable description of the phone number. string (body) No
caller_id_name If cnam capable, the name of the phone number’s owner. Max 15 characters. string (body) 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 (body) 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"
  }'

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, 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
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

Example Response

{
  "no": "+19495551212",
  "formatted": "(949) 555-1212",
  "assigned_to": "CallFlows",
  "description": "Office Desk Phone",
  "capabilities": [
    "sms_inbound",
    "sms_outbound",
    "voice_inbound",
    "voice_outbound"
  ],
  "caller_id_name": "Bob Jones",
  "status": "routed",
  "usage": 100,
  "price": 1,
  "price_period": "day",
  "created_on": "2019-03-08T13:15:33-08:00",
  "updated_on": "2019-12-03T16:20:42-08:00",
  "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
  },
  "estimated_active_date": "2019-04-10T10:01:56-07:00"
}

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 (path) Yes
integrations 3rd party lookups that each have a charge associated with them. See our pricing page for details. Accepts: ekata_reverse_phone string (path) No

INTEGRATIONS DETAILS

Integration Parameter Description Provider
ekata_reverse_phone Ekata 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 Ekata

Example Request

curl -X GET \
  'https://api.voxolo.gy/v1/PhoneNumberInformation/+1323214321?include=cnam,carrier,location&integrations=ekata_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": {
    "ekata_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

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. number
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. number
hold_times.least The lowest current hold time. number
hold_times.greatest The highest current hold time. number

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. number
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. number
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. number
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/callId \
  -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/myQueue \
  -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": "myQueue",
  "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.

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

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

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

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

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

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].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

Example Response

{
  "recordings": [
    {
      "id": "MTMwMDE1QDQ2OjViOTyMzY3YjRkMDdjNHwx",
      "app_id": "eaffd4-1234-4a95-9876-9c0b8",
      "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
    }
  ],
  "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].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

Example Response

{
  "recordings": [
    {
      "id": "MTMwMDE1QDQ2OjViOTyMzY3YjRkMDdjNHwx",
      "app_id": "eaffd4-1234-4a95-9876-9c0b8",
      "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
    }
  ],
  "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. 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. integer

Example Response

{
  "trunks": [
    {
      "trunk_id": "952bfde1-8079-4c32-92c3-6339810e1be3",
      "status": "active",
      "created_on": "2018-07-30T15:12:41-07:00",
      "modified_on": "2018-07-30T15:12:41-07:00",
      "updated_on": "2018-07-30T15:12:41-07:00",
      "app_id": "aaaa-bbbb-cccc-dddd-eeee",
      "subaccount_id": 12345,
      "direction": "outbound",
      "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-07:00",
      "modified_on": "2018-07-30T15:12:41-07:00",
      "updated_on": "2018-07-30T15:12:41-07:00",
      "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"
      }
    }
  ]
}

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. integer

Example Response // Inbound

{
  "trunk_id": "952bfde1-8079-4c32-92c3-6339810e1be3",
  "status": "active",
  "created_on": "2018-07-30T11:23:21-07:00",
  "updated_on": "2019-01-29T16:24:21-08:00",
  "modified_on": "2018-07-30T11:23:21-07:00",
  "app_id": "aaaa-bbbb-cccc-dddd-eeee",
  "direction": "inbound",
  "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"
  }
}

Example Response // Outbound

{
  "trunk_id": "952bfde1-8079-4c32-92c3-6339810e1be3",
  "status": "active",
  "created_on": "2018-07-30T15:12:41-07:00",
  "modified_on": "2018-07-30T15:12:41-07:00",
  "updated_on": "2019-01-29T16:24:21-08:00",
  "app_id": "aaaa-bbbb-cccc-dddd-eeee",
  "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
  }
}

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
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. integer No

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

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

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. integer

Example Response // Inbound

{
  "trunk_id": "952bfde1-8079-4c32-92c3-6339810e1be3",
  "created_on": "2018-07-30T11:23:21-07:00",
  "modified_on": "2018-07-30T11:23:21-07:00",
  "updated_on": "2019-01-29T16:24:21-08:00",
  "app_id": "aaaa-bbbb-cccc-dddd-eeee",
  "direction": "inbound",
  "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"
  }
}

Example Response // Outbound

{
  "trunk_id": "952bfde1-8079-4c32-92c3-6339810e1be3",
  "created_on": "2018-07-30T15:12:41-07:00",
  "modified_on": "2018-07-30T15:12:41-07:00",
  "updated_on": "2019-01-29T16:24:21-08:00",
  "app_id": "aaaa-bbbb-cccc-dddd-eeee",
  "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
  }
}

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
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. integer No

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
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 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. integer

Example Response

{
  "trunk_id": "952bfde1-8079-4c32-92c3-6339810e1be3",
  "created_on": "2018-07-30T15:12:41-07:00",
  "modified_on": "2018-07-30T15:12:41-07:00",
  "updated_on": "2018-07-30T15:12:41-07:00",
  "app_id": "aaaa-bbbb-cccc-dddd-eeee",
  "direction": "outbound",
  "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
  }
}

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

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
$keyPresses string The last key presses collected by the COLLECT action. To check for no keys pressed, use $keyPresses == ''.
$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.

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.

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 400429 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.

Deprecated

Call Flows Callbacks (Deprecated)

As of March 1, 2018, the methods below have been deprecated in favor of the new CallFlows Configurations methods.

Create Call Flow Callback

Creates 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).

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.

POST /CallFlows/Callbacks

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
no The phone number in E.164 format (example: +17145551212) string Yes
callback An object that describes the callback parameters. object Yes
callback.url The endpoint URL where the request will be sent. string Yes
callback.method The request method. Accepts: POST, GET. Default: POST. string 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 No
callback.headers An associative array of header names and values to include in every request. object 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. number No
callback.answer_on_ring The number of allowed rings before the call is answered. Allowed range: 1 - 10. Default: 1. integer 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 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. object 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. object No
is_template If true, Template Mapping. will be found and replaced. Default: true. boolean No
custom_data Any data you want included in every request. For example, a private key to verify requests. object No

Example Request // Phone Number

curl -X POST \
  https://api.voxolo.gy/v1/CallFlows/Callbacks \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '[  
    {  
      "no":"+17145551213",
      "callback":{    
        "method":"POST",
        "url":"https://myserver.com/ivr_app/callback-handler",
        "content_type":"application/json",
        "headers":{  
          "X-Custom-Name":"custom header value"
        }
      },
      "is_template": true,
      "custom_data":{  
        "foo":"bar"
      }
    }
]'

Example Request // Minimal Callback Config

curl -X POST \
  https://api.voxolo.gy/v1/CallFlows/Callbacks \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '[  
    {  
      "no": {
        "value": "+17145551213",
        "type": "US"
      },
      "callback": {    
        "method": "POST",
        "url": "https://myserver.com/ivr_app/callback-handler",
        "content_type": "application/json"
      }
    }
]'

Example // Callback Config POST with SMS and Failover Endpoints

curl -X POST \
  https://api.voxolo.gy/v1/CallFlows/Callbacks \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '[  
    {  
      "no": {
        "value": "+17145551213",
        "type": "US"
      },
      "callback": {    
        "method": "POST",
        "url": "https://myserver.com/ivr_app/callback-handler",
        "content_type": "application/json",
        "headers": {  
          "X-Custom-Name": "custom header value"
        }
      },
      "callback_failover": {    
        "method": "GET",
        "url": "https://s3.amazonaws.com/com.mydomain.actions/failover_actions.json",
        "content_type": "application/json"
      },
      "callback_sms": {    
        "method": "POST",
        "url": "https://myserver.com/ivr_app/callback-sms-handler",
        "content_type": "application/json"
      },
      "callback_sms_failover": {    
        "method": "POST",
        "url": "https://myserver.com/ivr_app/callback-sms-handler-failover",
        "content_type": "application/json"
      },
      "is_template": true,
      "custom_data": {  
        "foo": "bar"
      }
    }
]'

Response

No Response Body

Response Codes

Status Description
201 List of updated configs.
4xx & 5xx General Error Codes
4xx & 5xx Call Flow Error Codes

List Callback Configurations

Returns current callback configurations.

GET /CallFlows/Callbacks

Authentication Type

API Key (Application-level)

Request

No Request Body

Example Request

curl -X GET \
  https://api.voxolo.gy/v1/CallFlows/Callbacks \
  -H 'cache-control: no-cache' \
  -H 'x-api-key: YOUR_API_KEY'

Response

Parameter Description Type
no JSON object with value and type parameters object
no.value The phone number in E.164 format (example: +17145551212) or SIP_DOMAIN (example: 1234-56789.accounts.sip.voxolo.gy). string
no.type The country code of the phone number (ISO Alpha-2 Code) or SIP_DOMAIN. string
callback An object that describes the callback parameters. object
callback.url The endpoint where the request will be sent. string
callback.method The request method. Returns: POST or 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. object
is_template If true, Template Mapping. will be found and replaced. Default: false. boolean
custom_data Any data you want included in every request. For example, a private key to verify requests. string

Example Response

[  
   {  
      "no":"+17145551212",
      "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":1,
      "last_set_on":"2016-08-08T15:23:01.968Z",
      "custom_data":null,
      "is_template":false,
      "google_analytics":{  
         "tracking_id":"X-12345678-9",
         "source":"CallFlows"
      }
   }
]

Response Codes

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

View Callback Configuration

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

GET /CallFlows/Callbacks/{phone_number}

Authentication Type

API Key (Application-level)

Request

No Request Body

Example Request

curl -X GET \
  'https://api.voxolo.gy/v1/CallFlows/Callbacks/+17145551212' \
  -H 'cache-control: no-cache' \
  -H 'x-api-key: YOUR_API_KEY'

Response

Parameter Description Type
no JSON object with value and type parameters object
no.value The phone number in E.164 format (example: +17145551212) or SIP_DOMAIN (example: 1234-56789.accounts.sip.voxolo.gy). string
no.type The country code of the phone number (ISO Alpha-2 Code) or SIP_DOMAIN. string
callback An object that describes the callback parameters. object
callback.url The endpoint where the request will be sent. string
callback.method The request method. Returns: POST or 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. object
is_template If true, Template Mapping. will be found and replaced. Default: false. boolean
custom_data Any data you want included in every request. For example, a private key to verify requests. string

Example Response

{  
   "no":"+17145551212",
   "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":1,
   "last_set_on":"2016-08-08T15:23:01.968Z",
   "custom_data":null,
   "is_template":false,
   "google_analytics":{  
      "tracking_id":"X-12345678-9",
      "source":"CallFlows"
   }
}

Response Codes

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

Delete Callback Configurations

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

DELETE /CallFlows/Callbacks

Authentication Type

API Key (Application-level)

Request

Parameter Description Type
no The phone number to delete. Accepts: E.164 format. (example: +17145551212) string

Example Request

curl -X DELETE \
  https://api.voxolo.gy/v1/CallFlows/Callbacks \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '[
    {
        "no": "+17145551212"
    }
]'

Response

Parameter Description Type
no JSON object with value and type parameters object
no.value The phone number in E.164 format (example: +17145551212) or SIP_DOMAIN (example: 1234-56789.accounts.sip.voxolo.gy). string
no.type The country code of the phone number (ISO Alpha-2 Code) or SIP_DOMAIN. string
callback An object that describes the callback parameters. object
callback.url The endpoint where the request will be sent. string
callback.method The request method. Returns: POST or 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. object
is_template If true, Template Mapping. will be found and replaced. Default: false. boolean
custom_data Any data you want included in every request. For example, a private key to verify requests. string

Example Response

{  
   "no":"+17145551212",
   "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":1,
   "last_set_on":"2016-08-08T15:23:01.968Z",
   "custom_data":null,
   "is_template":false,
   "google_analytics":{  
      "tracking_id":"X-12345678-9",
      "source":"CallFlows"
   }
}

Response Codes

Status Description
200 Success returns the phone numbers of the configurations removed.
4xx & 5xx General Error Codes
4xx & 5xx Call Flow Error Codes

Dials SMS

Creates and sends a single SMS message to a specified phone number.

The call.caller_id_no must be a SMS-enabled number that is assigned to an inbound API.

Note: Errors will cause a call to be placed with an error message. Errors are likely due to an illegal call.caller_id_no.

POST /Dials/SMS

Authentication Type

API Key (Application-level)

Request

Parameter Description Type Required
call The SMS call object. object Yes
call.no The phone number to send the message to. string Yes
call.caller_id_no The phone number the message is from. Must be an assigned number. string Yes
message The SMS message. string Yes

Example Request

curl -X POST \
  https://api.voxolo.gy/v1/Dials/SMS \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{  
    "call":{  
      "no":"+17145551212",
      "caller_id_no":"+15625551212"
    },
    "message":"Hello World"
}'

Response

Property Description Type
call The SMS call object. object
call.id The ID of the message. string
call.no The phone number to send the message to. string
call.caller_id_no The phone number the message is from. Must be an assigned number. string

Example Response

{
    "call": {
        "id": "123456@789",
        "no": "+17145551212",
        "caller_id_no": "+15625551212"
    }
}

Response Codes

Status Description
201 Returns a call object.
4xx & 5xx General Error Codes