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

• REST API
• Call Flow Loop // Callback Request/Response Loop

Tools Include

• Call Flow Actions // 23 unique actions to control phone calls including CONFERENCE, QUEUE, SAY, PLAY, DETECT, RECORD, etc.
• API Methods // Initiate and modify live phone calls and retrieve information
• Session Data // Insert meaningful data into a phone call to make programmatic decisions
• Conditionals // If-Then-Else Action evaluated like JavaScript
• Variables // Native and User Defined

Postman Collection

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

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

Click the link below to view and download our collection!

Open in Postman

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

Overview

Call Flow Loop

Example Response

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

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

Multi-Action Processing

Responses can be as simple as a single action.

Example: SAY “Hello, Jill”.

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

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

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

Phone Number Configuration

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

How it Works

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

• Programmable Voice
• Programmable SMS

Action Types

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

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

Supported Actions By Service

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

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

Callback Request // Voice

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

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

Example Request // Call

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

Request

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

Callback Request // Message

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

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

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

Example Request // Inbound SMS Callback

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

Example Request // Inbound MMS Callback

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

Request

Property	Description	Type	When
service	The name of the service. Returns: programmable_messaging.	string	all
type	The type of message. Returns: sms, mms	string	all
app_id	The Application ID for this request.	string	all
subaccount_id	The Sub Account ID for this request.	integer	all
api_no	The Voxology phone number (near end) that is provisioned to the API (E.164 format: +17145551212).	string	all
api_no_latitude	The latitude of the Voxology phone number (near end). Possibly null.	string	inbound
api_no_longitude	The longitude of the Voxology phone number (near end). Possibly null.	string	inbound
api_no_postal_code	The postal code (zip) of the Voxology phone number (near end). Possibly null.	string	inbound
api_no_city	The city of the Voxology phone number (near end). Possibly null.	string	inbound
api_no_rate_center	The rate center of the Voxology phone number (near end), if applicable. Possibly null.	string	inbound
api_no_lata	The lata of the Voxology phone number (near end), if applicable. Possibly null.	string	inbound
api_no_region	The two-character region (state) code of the Voxology phone number (near end). Possibly null.	string	inbound
api_no_country	The two-character country code of the Voxology phone number (near end). Possibly null.	string	inbound
api_no_timezone	The time zone of the Voxology phone number (near end) (America/Los_Angeles). Possibly null. Click here for list of time zones.	string	all
caller_no	The user’s phone number (far end) that interacted with the API (E.164 format: +19495551212).	string	all
caller_no_latitude	The latitude of the user’s phone number (far end). Possibly null.	string	inbound
caller_no_longitude	The longitude of the user’s phone number (far end). Possibly null.	string	inbound
caller_no_postal_code	The postal code (zip) of the user’s phone number (far end). Possibly null.	string	inbound
caller_no_city	The city of the user’s phone number (far end). Possibly null.	string	inbound
caller_no_rate_center	The rate center of the user’s phone number (far end), if applicable. Possibly null.	string	inbound
caller_no_lata	The lata of the user’s phone number (far end), if applicable. Possibly null.	string	inbound
caller_no_region	The two-character region (state) code of the user’s phone number (far end). Possibly null.	string	inbound
caller_no_country	The two-character country code of the user’s phone number (far end). Possibly null.	string	inbound
caller_no_timezone	The time zone of the user’s phone number (far end) (America/Los_Angeles). Possibly null. Click here for list of time zones.	string	inbound
group_nos	An array of numbers the message was sent to, if this message was part of a group MMS meesage. The first number in the list will also be assigned to the caller_no property. The value will be null if the message was sent to a single recipient.	array	all
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
auto_response	Boolean indicating if the Voxology Autoresponder responded to this message on your behalf.	string	inbound
keyword_detected	The detected keyword that triggered the autoresponse. Opt-in: START, SUBSCRIBE Opt-out: STOP, CANCEL, QUIT, UNSUBSCRIBE, END Help: HELP, INFO	string	inbound
keyword_type	The category of keyword detected that triggered the autoresponse: Opt-In, Opt-Out, Help	string	inbound
media_urls	An array of URLs pointing to the media included in an MMS message.	array	inbound mms
media_urls[i].url	The URL pointed to the provided media.	string	inbound mms
media_urls[i].content_type	The file type of the provided media.	string	inbound mms

Example Request // Outbound Message Status Webhook

{
  "service": "programmable_messaging",
  "type": "sms",
  "app_id": "aaaa-bbbb-cccc-dddd-eeee",
  "subaccount_id": 0,
  "api_no": "+19495551212",
  "caller_no": "+17145551212",
  "group_nos": null,
  "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:

• POST // Create
• GET // Read
• PUT // Update
• DELETE // Delete

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

Response

All responses will return JSON.

Any 2xx status codes are considered a success.

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

Error Handling

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

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

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

Response

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

Example Response:

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

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

Media Stream

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

WebSocket Messages

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

Message Types

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

Stream Messages

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

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

Track Messages

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

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

Statuses

Call Status

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

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

Message Status

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

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

Phone Number Status

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

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

STIR SHAKEN Status

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

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

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

Verify Status

Verifications for two-factor authentication, created through the Verify API, are assigned a status describing the current state of the Verification. Verification statuses can be in an 'In Progress’ or 'Final’ state and they can found in various responses to Verify API Requests.

Status	Description	State
pending	Verification has been created. Verifications will stay in pending until the correct code is asserted, the max number of assert attempts is reached, the time-to-live expires, or the Verification is canceled.	In Progress
verified	The correct code was successfully asserted against this Verification.	Final
failed	The max assert attempts was reached for this Verification without a successful assertion.	Final
timed-out	The Verification’s time-to-live expired before a successful assertion was made.	Final
canceled	The Verification was canceled by the Cancel Verification API method.	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:

• Make Call REST Request // include session_data when initiating a phone call via a REST request;
• Modify Session Data REST Request // insert or replace session_data during a live call via a REST request;
• SESSIONDATA Action // insert or replace session_data on a specific call via your callback response in your JSON Actions during a live call;
• DIAL Action // include session_data when initiating a phone call via a Call Flows JSON script via a callback response.

Example Callback Response // Call Flow using Session Data

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

Cut Back On Callbacks

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

Transcription

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

Transcript Webhooks

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

Webhook Types

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

Request

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

Actions

COLLECT

Record Key Presses and Speech from Callers.

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

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

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

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

Request

View standard request details HERE

Response

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

Example Response // Key Presses

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

Example Response // Speech

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

Example Response // Advanced

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

CONFERENCE

Initiates a conference event.

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

Request

View standard request details HERE.

Response

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

Example Response

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

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

Events

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

DETECT

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

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

Request

View standard request details HERE

Response

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

Example Response

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

Detect Events

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

DIAL

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

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

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

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

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

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

Request

View standard request details HERE

Response

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

Example Responses

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

Events

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

FOREACH

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

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

Request

View standard request details HERE

Response

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

Example Response

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

GOTO

Jump to a LABEL.

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

Request

View standard request details HERE

Response

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

Example Response

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

HANGUP

Ends the call.

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

Request

View standard request details HERE

Response

See Example Body

Example Response

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

IF

Basic if-then-else conditional.

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

Response

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

Example Response

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

LABEL

Target of GOTO.

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

Request

View standard request details HERE

Response

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

Example Response

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

PAUSE

Pauses the call.

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

Request

View standard request details HERE

Response

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

Example Response

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

PLAY

Plays an audio file or DTMF.

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

DTMF will play an out-of-band tone.

Request

View standard request details HERE

Response

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

Example Response // Audio

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

Example Response // DTMF

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

QUEUE

Controls Call Queues.

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

Request

View standard request details HERE

Response

Parameter	Description	Default	Type	Required
name	A unique name to identify the queue. Using the same name will put callers into the same queue. Accepts: alpha-numeric, underscores, and dashes.		string*	Yes
event	Accepts: offer, poll, poll_connect, remove. offer puts this call into a queue. poll releases the next queued call from a queue (and has a limited use case as an Action). poll_connect takes the next call from the queue and bridges it to this call. remove takes this call (regardless of position) from the queue.	offer	string	No
async	If true, this action will not block and the call flow will continue executing actions and/or callbacks. Be careful as async may cause hard to reason behaviors. Only offer can be asynchronous.	false	boolean	No
max_calls	At the moment of offering, if the number of queued calls exceeds this amount, the offer will error. Calls that attempt to exceed the limit can be handled with an error handler.	infinity*	integer	No

Example Response // Simple

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

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

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

Queue Events

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

Example Response // Advance

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

RECORD

Control call recording.

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

There are two tracks available to record on each call. The default track is caller, representing the person that called, or was called by, your API number. Use the transfer track to record both sides of a call that was transferred from your API number to a second destination.

Request

View standard request details HERE

Response

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

Example Response

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

RECORDMESSAGE

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

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

Request

View standard request details HERE

Response

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

Example Response

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

RecordMessage Events

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

REDIRECT

Changes the callback URL, etc.

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

Request

View standard request details HERE

Response

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

Example Response

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

Example Response // Relative URL

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

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

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

Example Response // Relative URL

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

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

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

REDIRECTEXTENSION

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

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

Request

View standard request details HERE

Response

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

Example Response

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

Events

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

REJECT

Does not answer the call.

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

Request

View standard request details HERE

Response

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

Example Response

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

SAY

Convert text to speech (TTS).

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

Request

View standard request details HERE

Response

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

Example Response

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

SESSIONDATA

Sets a call’s session data.

Sets a call’s session_data property.

To learn more about session data, click here.

Request

View standard request details HERE

Response

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

Example Response

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

SMS

Sends an SMS message.

This action sends an SMS message.

Response

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

Example Response

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

STOP

Stops Running Actions.

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

Request

View standard request details HERE

Response

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

Example Response

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

STREAM

Initiate a Media Stream during a live phone call.

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

Request

View standard request details HERE

Response

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

Example Response

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

TRANSCRIBE

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

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

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

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

Request

View standard request details HERE

Response

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

Example Response

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

TRANSFER

Transfers the call.

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

Request

View standard request details HERE

Response

Parameter	Description	Default	Type	Required
no	The phone number or SIP destination to call. Phone numbers are in E.164 format (example: +19495551212). SIP destinations are formatted as abc123@sip.mypbx.com.		string*	Yes
caller_id_no	The phone number that will appear as the Caller ID. Phone numbers are in E.164 format (example: +19495551212). Defaults to the number of the caller that dialed your inbound number (caller_id_noin your callbacks)	caller_no	string*	No
user_sip_headers	The key/value pair(s) in this object will be flattened and converted to User-to-User and X-... SIP headers to be included when transferring to a SIP address. This allows you to pass along custom data on transfer. The key(s) must be: User-to-User OR must start with an X-.		string	No
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
max_call_time	The maximum length of the call in seconds. Valid: 60 to 172800.	86400	integer	No
timeout	The maximum time to wait during ringing in seconds. Valid: 20 to 240.	50	integer	No
external_id	A user-defined ID for the call.	false	string	No
external_group_id	A user-defined ID for a group of calls.	false	string	No

Example Response // Phone Number

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

Example Response // SIP Address

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

Example Response // Async Transfer

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

Events

Event	Description
on_error	This handler will run when the call transfer is unable to connect to the B-leg in any way. To handle specific scenarios, use the handlers listed below.
on_error_busy	This handler will run when the B-leg of the transfer ends with a busy disposition.
on_error_no-answer	This handler will run when the B-leg of the transfer ends with a no-answer disposition.
on_error_failed	This handler will run when the B-leg of the transfer ends with a failed disposition.
on_error_validation	This handler will run when the B-leg of the transfer is unable to be dialed for validation reasons such as an invalid destination.
on_error_restricted	This handler will run when the B-leg of the transfer is unable to be dialed. Possible reasons include: Do Not Call, Call Guards on your Application, or your Application is blocked.

ß

WEBHOOK

HTTP Request.

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

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

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

Request

View standard request details HERE

Response

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

Example Response // Simple

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

Example Response // Advanced // Object

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

Events

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

Example Response // Simple // String

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

Example Response // Advanced // String

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

Methods

Account

View Account Detail

Returns account owner’s information.

GET /Account

Authentication Type

Basic Authentication (Account-level)

Request

No Request Body

Example Request

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

Response

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

Example Response

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

Response Codes

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

Create Alert

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

POST /Account/Alerts

Authentication Type

Basic Authentication (Account-level)

Request

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

Example Request

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

Response

No Response Body

Response Codes

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

List Alerts

Returns all alerts created for a specific account.

GET  /Account/Alerts

Authentication Type

Basic Authentication (Account-level)

Request

No Request Body

Example Request

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

Response

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

Example Response

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

Response Codes

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

Delete Alert

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

DELETE /Account/Alerts/{id}

Authentication Type

Basic Authentication (Account-level)

Request

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

Example Request

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

Response

No Response Body

Response Codes

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

Create End User Profile

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

POST /Account/EndUserProfiles

Authentication Type

Basic Authentication (Account-level)

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

List End User Profiles

Returns all end user profiles created for a specific account.

GET  /Account/EndUserProfiles

Authentication Type

Basic Authentication (Account-level)

Request

No Request Body

Example Request

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

Response

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

Example Response

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

Response Codes

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

View End User Profile Detail

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

GET /Account/EndUserProfiles/{id}

Authentication Type

Basic Authentication (Account-level)

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

Update End User Profile

Updates existing end user profile information.

PUT /Account/EndUserProfiles/{id}

Request

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

Example Request

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

Example Response

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

Response Codes

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

Delete End User Profile

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

DELETE /Account/EndUserProfiles/{id}

Authentication Type

Basic Authentication (Account-level)

Request

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

Example Request

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

Response

No Response Body

Response Codes

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

View Balance

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

GET /Account/Billings/Balance

Authentication Type

Basic Authentication (Account-level)

Request

No Request Body

Example Request

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

Response

Property	Description	Type
balance	Current account balance in USD.	integer

Example Response

{
  "balance": 100.0
}

Response Codes

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

Make Payment

Make a credit card payment to increase your balance.

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

POST /Account/Payments

Authentication Type

Basic Authentication (Account-level)

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

List Payment Methods

Returns the available payment methods assigned to an account.

GET /Account/Payments/Methods

Authentication Type

Basic Authentication (Account-level)

Request

No Request Body

Example Request

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

Response

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

Example Response

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

Response Codes

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

List Payment History

Returns payments history by date range.

GET /Account/Payments?{query_string}

Authentication Type

Basic Authentication (Account-level)

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

Application Sub Accounts

Create Sub Accounts

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

POST /SubAccounts

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

List Sub Accounts

Returns a list of all Sub Accounts under your application.

GET /SubAccounts?{query_string}

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

View Sub Account Detail

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

GET /SubAccounts/{id}

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

Update Sub Account

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

PUT /SubAccounts/{id}

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

Delete Sub Account

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

DELETE /SubAccounts/{id}

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

No Response Body

Response Codes

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

Caller IDs

Create Caller ID

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

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

POST /CallerIDs/{caller_id}

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

List Caller IDs

Returns a list of Caller IDs.

GET /CallerIDs?{query_string}

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

View Caller ID

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

GET /CallerIDs/{caller_id}

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

Update Caller ID

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

PUT /CallerIDs/{caller_id}

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

Delete Caller ID

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

DELETE /CallerIDs/{caller_id}

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

No Response Body

Response Codes

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

Verify Caller ID

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

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

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

POST /CallerIDs/{caller_id}/Verify

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

Call Flows (Callback Configuration)

Update Call Flow Configuration

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

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

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

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

Default Configuration

PUT /CallFlows/Configurations/Default

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

Phone Number Configuration

PUT /CallFlows/Configurations/PhoneNumbers/{phone_number}

Extensions Default Configuration

PUT /CallFlows/Configurations/Extensions/Default

Extension Configuration

PUT /CallFlows/Configurations/Extensions/{extension}

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

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

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Example Request // Minimal Callback Config

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

Example // Extension Callback Config

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

Response

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

Example Response // Default update

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

Example Response // Number update

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

Example Response // Extensions Default update

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

Example Response // Extension update

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

Response Codes

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

List Call Flow Configurations

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

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

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

Authentication Type

API Key (Application-level)

Request

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

Example Request // Phone Numbers

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

Example Request // Extensions

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

Response

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

Example Response // Phone Numbers

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

Example Response // Extensions

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

Response Codes

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

View Call Flow Configuration

Default Configuration

GET /CallFlows/Configurations/Default

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

Phone Number Configuration

GET /CallFlows/Configurations/PhoneNumbers/{phone_number}

Extensions Default Configuration

GET /CallFlows/Configurations/Extensions/Default

Extension Configuration

GET /CallFlows/Configurations/Extensions/{extension}

Authentication Type

API Key (Application-level)

Request

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

Example Request // Phone Number

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

Example Request // Extension

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

Response

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

Example Response // Phone Number

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

Example Response // Extension

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

Response Codes

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

Delete Call Flow Configuration

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

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

Default Configuration

DELETE /CallFlows/Configurations/Default

Phone Number Configuration

DELETE /CallFlows/Configurations/PhoneNumbers/{phone_number}

Extensions Default Configuration

DELETE /CallFlows/Configurations/Extensions/Default

Extension Configuration

DELETE /CallFlows/Configurations/Extensions/{extension}

Authentication Type

API Key (Application-level)

Request

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

Example Request // Phone Number

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

Example Request // Extension

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

Response

No Response Body

Response Codes

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

Calls

Make Call

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

POST /Dials/Connect

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

Example Response

Property	Description	Type
call	The call object to connect.	string
call.id	The ID of the call.	string
call.no	The phone number dialed.	string
call.caller_id_no	The from phone number appearing as the caller ID.	string
inbound_api	The inbound CallFlow type the call.caller_id_no is assigned to.	string

{
  "call": {
    "id": "1234@56",
    "no": "+17145551212",
    "caller_id_no": "+19495551212"
  },
  "inbound_api": "CallFlows"
}

Response Codes

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

List Live Calls

Returns a list of all live calls.

GET /LiveCalls?{query_string}

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

View Live Call Detail

Returns the details of a call by ID.

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

GET /LiveCalls/{call_id}

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

List Call Logs

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

GET /History/Logs/Calls?{query_string}

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

View Call Log

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

GET  /History/Logs/Calls/{call_id}

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

End Call

Deletes the specified call by ID.

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

DELETE /LiveCalls/{call_id}

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

No Response Body

Response Codes

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

Hang Up

Creates a request to end the call by ID.

Includes the option of leaving an exit message.

POST /LiveCalls/{call_id}/Actions/HangUp

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

No Response Body

Response Codes

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

Collect Digits

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

An optional message can be played.

POST /LiveCalls/{call_id}/Actions/Collect

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

No Response Body

Response Codes

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

Stop Actions

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

POST /LiveCalls/{call_id}/Actions/Stop

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

No Response Body

Response Codes

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

Leave Voicemail

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

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

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

POST /LiveCalls/{call_id}/Actions/LeaveVoiceMail

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

No Response Body

Response Codes

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

Tell

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

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

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

POST /LiveCalls/{call_id}/Actions/Tell

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

No Response Body

Response Codes

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

Call Transfer

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

POST /LiveCalls/{call_id}/Actions/Transfer

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

No Response Body

Response Codes

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

Inject Actions List

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

POST /LiveCalls/{call_id}/Actions

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

No Response Body

Response Codes

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

Modify Session Data

Write/overwrite session_data on a live call by ID.

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

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

POST /LiveCalls/{call_id}/Actions/SessionData

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

No Response Body

Response Codes

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

Conferences

List Conferences

Returns the list of live conferences for this application.

GET /LiveCalls/Conferences

Authentication Type

API Key (Application-level)

Request

No Request Body

Example Request

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

Response

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

Example Response

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

Response Codes

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

View Conference Detail

Returns details about the specified conference.

GET /LiveCalls/Conferences/{conf_id}

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

View Participant Detail

Returns information about the specified participant of the specified conference.

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

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

Join Conference

Places a caller into the specified conference.

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

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

No Response Body

Response Codes

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

Join Conference to Whisper

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

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

Authentication Type

API Key (Application-level)

REQUEST

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

Example Request

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

Response

No Response Body

Response codes

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

Leave Conference

Forces the specified conference participant to leave a conference.

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

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

No Response Body

Response Codes

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

Mute Participant

Mutes the specified conference participant during a conference.

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

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

No Response Body

Response Codes

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

Unmute Participant

Unmutes the specified conference participant during a conference.

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

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

No Response Body

Response Codes

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

Hold Participant

Places the specified conference participant on hold.

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

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

No Response Body

Response Codes

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

Resume Participant

Remove the specified conference participant from hold.

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

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

No Response Body

Response Codes

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

Emergency Address

Validate Emergency Address

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

POST /ValidateEmergencyAddress

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

Update a number’s Emergency Address

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

PUT /EmergencyAddresses/{phone_number}

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

View Emergency Address

Returns an emergency address assigned to a specific phone number.

GET /EmergencyAddresses/{phone_number}

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

Delete Emergency Address

Deletes an emergency address from a phone number.

DELETE /EmergencyAddresses/{phone_number}

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

No Response Body

Response Codes

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

Extensions

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

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

List Extensions

Returns a list of Extensions on this application.

GET /Extensions

AUTHENTICATION TYPE

API Key (Application-level)

REQUEST

No Request Body

Example Request

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

Response

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

Example Response

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

Response Codes

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

View Extension

Returns the Extensions object for a specific Extension.

GET /Extensions/{extension}

AUTHENTICATION TYPE

API Key (Application-level)

REQUEST

No Request Body

Example Request

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

Response

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

Example Response

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

Response Codes

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

Create Extension

Creates an Extension.

POST /Extensions

AUTHENTICATION TYPE

API Key (Application-level)

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

Updates Extension

Updates a specified Extension.

PUT /Extensions/{extension}

AUTHENTICATION TYPE

API Key (Application-level)

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

Delete Extension

Deletes the specified Extension.

DELETE /Extensions/{extension}

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

No Response Body

Response Codes

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

Integrations

Update AWS S3 Authentication

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

PUT /Integrations/RecordingStorage/AWS

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

View AWS S3 Authentication

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

GET /Integrations/RecordingStorage/AWS

Authentication Type

API Key (Application-level)

Request

No Request Body

Example Request

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

Response

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

Example Response

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

Response codes

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

Delete AWS S3 Authentication

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

DELETE /Integrations/RecordingStorage/AWS

Authentication Type

API Key (Application-level)

Request

No Request Body

Example Request

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

Response

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

Example Response

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

Response Codes

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

Update Watson Authentication

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

PUT /Integrations/TTS/Watson

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

View Watson Authentication

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

GET /Integrations/TTS/Watson

Authentication Type

API Key (Application-level)

Request

No Request Body

Example Request

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

Response

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

Example Response

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

Response codes

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

Delete Watson Authentication

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

DELETE /Integrations/TTS/Watson

Authentication Type

API Key (Application-level)

Request

No Request Body

Example Request

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

Response

No Response Body

Response codes

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

Messages

Send Message

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

POST /Messages

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

Send Messages Batch

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

POST /Messages/Batch

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

List Messages

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

GET /Messages?{query_string}

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

View Message

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

GET /Messages/{message_id}

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

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

Example Response // Inbound

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

Example Response // Outbound

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

Response Codes

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

Messaging Registration

List 10DLC Brands

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

GET /10DLCRegistration/Brands

AUTHENTICATION TYPE

API Key (Application-level)

REQUEST

No Request Body

Example Request

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

Response

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

Example Response

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

Response Codes

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

View 10DLC Brand Details

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

GET /10DLCRegistration/Brands/{brand_id}

AUTHENTICATION TYPE

API Key (Application-level)

REQUEST

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

Create 10DLC Brand

Creates a 10DLC Brand.

POST /10DLCRegistration/Brands

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

Update 10DLC Brand

Updates a 10DLC Brand.

PUT /10DLCRegistration/Brands/{brand_id}

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

Delete 10DLC Brand

Deletes a specified 10DLC Brand by its Brand ID.

DELETE /10DLCRegistration/Brands/{brand_id}

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

No Response Body

Response Codes

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

Order External 10DLC Brand Vetting

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

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

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

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

Import External 10DLC Brand Vetting

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

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

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

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

List 10DLC Campaigns

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

GET /10DLCRegistration/Campaigns

AUTHENTICATION TYPE

API Key (Application-level)

REQUEST

No Request Body

Example Request

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

Response

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

Example Response

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

Response Codes

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

View 10DLC Campaign Details

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

GET /10DLCRegistration/Campaigns/{campaign_id}

AUTHENTICATION TYPE

API Key (Application-level)

REQUEST

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

Create 10DLC Campaign

Creates a 10DLC Campaign.

POST /10DLCRegistration/Campaigns

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

Update 10DLC Campaign

Updates an existing 10DLC Campaign.

PUT /10DLCRegistration/Campaigns/{campaign_id}

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

Delete 10DLC Campaign

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

DELETE /10DLCRegistration/Campaigns/{campaign_id}

Authentication Type

API Key (Application-level)

REQUEST

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

Example Request

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

Response

No Response Body

Response Codes

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

Phone Numbers

List Available Inbound Numbers

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

GET /PhoneNumbers/Available?{query_string}

Authentication Type

API Key (Application-level)

Request

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

Search Details

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

Example Request

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

Example Request // Toll-free vanity number search

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

Response

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

Example Response

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

Example Response // Toll-free vanity number search

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

Response Codes

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

List Provisioned Numbers

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

GET /PhoneNumbers/{assigned_to}?{query_string}

Authentication Type

API Key (Application-level)

Request

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

Search Details

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

View Provisioned Number

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

GET /PhoneNumbers/{phone_number}

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

Provision Phone Numbers

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

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

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

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

POST /PhoneNumbers/{assigned_to}

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

Update Phone Numbers

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

PUT /PhoneNumbers/{phone_number}

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

Move Phone Numbers

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

PUT /PhoneNumbers/Move/{assigned_to}

Authentication Type

API Key (Application-level)

Request

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

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

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

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

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

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

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

Response

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

Example Response

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

Response Codes

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

Release Phone Numbers

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

DELETE /PhoneNumbers/{assigned_to}

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

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

Response

No content.

Response Codes

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

Phone Number Information

Phone Number Information Lookup

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

GET /PhoneNumberInformation/{phone_number}?{query_string}

Authentication Type

API Key (Application-level)

Request

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

INTEGRATIONS DETAILS

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

Port Requests

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

Create Hosted SMS Port Request

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

POST /PortRequests/HostedSMS

AUTHENTICATION TYPE

API Key (Application-level)

REQUEST

Parameter	Description	Type	Required
description	A description to add more details to the port request, if desired.	string	No
contact_name	The name of the point of contact for this request.	string	No
contact_email	The email of the point of contact for this request, should our CX team need to reach out with any issues.	string	Yes
desired_due_date	Requested date for the port to complete. This is passed on to the losing vendor in the port request, but they are not beholden to it.	string	Yes
loa_file	Base64 encoded string of an uploaded Letter of Authorization stating you have authority to transfer one or multiple phone numbers to a new vendor.	string	Yes
phone_numbers	An array of phone numbers to be included in the request to port messaging capabilities to Voxology.	array	Yes
phone_numbers[i].no	A phone number to port messaging in E164 format.	string	Yes

Example Request

curl -X POST \
  https://api.voxolo.gy/v1/PortRequests/HostedSMS \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
   -d '{
    "description": "An example port request for hosted SMS.",
    "contact_name": "Mary Jane",
    "contact_email": "maryjane@example.com",
    "desired_due_date": "2024-01-01",
    "loa_file": "YWtqaHNkamZoc2Fka2puZ2ZhLGt...",
    "phone_numbers": [
        {
            "no": "+15551234567"
        }
    ]
}'

Response

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

Example Response

{
    "id": "00001112222",
    "description": "An example port request for hosted SMS.",
    "contact_name": "Mary Jane",
    "contact_email": "maryjane@example.com",
    "desired_due_date": "2024-01-01",
    "loa_file": "YWtqaHNkamZoc2Fka2puZ2ZhLGt...",
    "created_on": "2023-01-01T22:25:39.000Z",
    "updated_on": "2023-01-01T22:25:39.000Z",
    "phone_numbers": [
        {
            "no": "+15551234567",
            "status": "pending",
            "reject_reason": ""
        }
    ]
}

Response Codes

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

Create Local Port Request

Initiates a request to port local phone numbers into Voxology.

POST /PortRequests/Local

AUTHENTICATION TYPE

API Key (Application-level)

REQUEST

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

Example Request

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

Response

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

Example Response

{
    "description": "An example port request for local numbers.",
    "contact_name": "Mary Jane",
    "contact_email": "maryjane@example.com",
    "desired_due_date": "2024-01-01",
    "loa_file": "YWtqaHNkamZoc2Fka2puZ2ZhLGt...",
    "bill_file": "VGhpcyBpcyByYW5kb20gd29yZtH...",
    "phone_numbers": [
        {
            "no": "+15551234567",
            "account_name": "John Smith",
            "account_password": "not_my_password",
            "account_telephone_number": "+15559876543",
            "account_number": "000111222",
            "account_pin": "1234",
            "address": {
                "name": "Good Business Inc",
                "street": "123 Main St.",
                "city": "Los Angeles",
                "region": "CA",
                "postal_code": "90001",
                "country": "US"
            },
            "desired_capabilities": [ "SMS", "MMS" ],
            "status": "pending",
            "reject_reason": "",
            "foc_date": "2024-01-08"
        }
    ]
}

Response Codes

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

Queues

List Queues

Returns a list of Call Queues.

GET /LiveCalls/Queues

Authentication Type

API Key (Application-level)

Request

No Request Body

Example Request

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

Response

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

Example Response

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

Response Codes

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

View Queue Details

Returns the details of a queue.

GET /LiveCalls/Queues/{queue_name}

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

List Queued Calls

Returns all of the calls in the specified queue.

GET /LiveCalls/Queues/{queue_name}/Calls

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

View Queued Call Detail

Returns the details of a queued call.

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

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

Peek at Queue

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

GET /LiveCalls/Queues/{queue_name}/Peek

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

Poll Queue

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

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

GET /LiveCalls/Queues/{queue_name}/Poll

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

Remove Queued Call

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

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

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

No Response Body

Response Codes

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

Delete Queue

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

DELETE /LiveCalls/Queues/{queue_name}

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

Recordings

Start Recording

Creates a call recording. Initiates the call recording type.

There are two tracks available to record on each call. The default track is caller, representing the person that called, or was called by, your API number. Use the transfer track to record both sides of a call that was transferred from your API number to a second destination.

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

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

No Response Body

Response Codes

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

Pause Recording

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

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

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

No Response Body

Response Codes

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

Resume Recording

This method allows developers to resume a paused call recording.

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

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

No Response Body

Response Codes

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

Stop Recording

This method allows developers to stop a call recording.

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

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

No Response Body

Response Codes

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

List Recordings

Returns a filtered list of recordings across all applications.

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

Authentication Type

API Key (Application-level)

GET /History/Recordings?{query_string}

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

View Recordings

Returns a filtered list of recordings per a single call.

Authentication Type

API Key (Application-level)

GET /History/Recordings/{call_id}

Request

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

Example Request

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

Response

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

Example Response

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

Response Codes

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

Download Recording

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

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

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

Audio File

Response Codes

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

Delete Recording

Deletes a call recording.

DELETE /History/Recordings/{id}

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

No Response Body

Response Codes

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

SIP Trunks

List SIP Trunks

Returns a list of SIP Trunks on this application.

GET /Trunks

AUTHENTICATION TYPE

API Key (Application-level)

REQUEST

No Request Body

Example Request

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

Response

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

Example Response

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

Response Codes

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

View SIP Trunk

Returns the SIP Trunk object of the specified SIP Trunk.

GET Trunks/{trunk_id}

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

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

Example Response // Inbound

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

Example Response // Outbound

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

Response Codes

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

Create SIP Trunk

Creates a SIP Trunk.

POST /Trunks

Authentication Type

API Key (Application-level)

Request

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

Example Request of Inbound Trunk

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

Example Request of Outbound Trunk

curl -X POST \
  https://api.voxolo.gy/v1/Trunks \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOU_API_KEY' \
  -d '{
    "direction": "outbound",
    "simultaneous_call_limit": 1,
    "description": "outbound trunk 7",
    "recording": {},
    "outbound": {
      "domain": null,
      "authentication": [
        {
          "source": "twilio",
          "value": "aaaaa-bbbbb-ccccc-ddddd-eeeee"
        },
        {
          "source": "other",
          "value": "000.000.00.00"
        },
        {
          "source": "other",
          "value": "000.000.00.00"
        }
      ],
      "override_early_media": "TO",
      "fax_support": "enabled",
      "max_post_dial_delay": 10,
    },
    "stream": {
      "url": "ws://websocketurl.com",
      "media_type": "base64",
      "tracks": [
        "near",
        "far"
      ],
      "stream_data": "{\"k1\":\"v1\",\"k2\":2}"
    }
  }'

Response

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

Example Response // Inbound

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

Example Response // Outbound

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

Response Codes

Status	Description
201	SIP Trunk created
4xx & 5xx	General Error Codes

Update SIP Trunk

Updates the SIP Trunk configuration of a specified Trunk.

PUT /Trunks/{trunk_id}

Authentication Type

API Key (Application-level)

Request

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

Example Request

curl -X PUT \
  https://api.voxolo.gy/v1/Trunks/952bfde1-8079-4c32-92c3-6339810e1be3 \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "description": "updated description"
  }'

Response

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

Example Response

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

Response Codes

Status	Description
200	Returns the Trunk Object
4xx & 5xx	General Error Codes

Delete SIP Trunk

Deletes the specified SIP Trunk.

DELETE /Trunks/{trunk_id}

Authentication Type

API Key (Application-level)

Request

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

Example Request

curl -X DELETE \
  https://api.voxolo.gy/v1/Trunks/952bfde1-8079-4c32-92c3-6339810e1be3 \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

No Response Body

Response Codes

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

SIP Users

SIP Users enable you to create and manage SIP Registration credentials through the Voxology API or Portal. SIP Users can be used to connect a variety of devices to one another or to the PSTN, including VoIP phones, softphones, SIP-enabled WebRTC clients, or a PBX.

List SIP Users

Returns a list of SIP Users on this application.

GET /Users

AUTHENTICATION TYPE

API Key (Application-level)

REQUEST

No Request Body

Example Request

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

Response

Property	Description	Type
users	An array of User objects.	array
users[i].created_on	The date when the SIP User was created.	ISO date string
users[i].updated_on	The date of the last update to the SIP User.	ISO date string
users[i].user_id	The unique ID of the SIP User.	string
users[i].status	The current status of the SIP User. Includes: active or inactive	string
users[i].description	User-definable description of the SIP User.	string
users[i].firstname	User-definable first name of the User.	string
users[i].lastname	User-definable last name of the User.	string
users[i].country	The country of the User.	string (ISO Alpha-2)
users[i].uri	The URI to view the SIP User’s details.	string
users[i].sip	Object containing sip settings and information	object
users[i].sip.authentication	Object containing sip authentication credentials.	object
users[i].sip.authentication.username.	The SIP User’s username	string
users[i].sip.authentication.password.	The SIP User’s password	string
users[i].sip.domain	The unique SIP User URL.	string
users[i].sip.outbound	Object containing outbound information.	object
users[i].sip.outbound.assigned_to	The campaign or trunk to which the SIP user is assigned.	string
users[i].sip.outbound.caller_id	Object containing caller ID information.	object
users[i].sip.outbound.caller_id.external_no	The caller ID displayed when calling external numbers.	string
users[i].sip.outbound.caller_id.internal_no	The caller ID displayed when calling internal numbers or extentions.	string
users[i].sip.outbound.caller_id.internal_cnam	The caller name when calling internal numbers or extentions.	string
users[i].sip.transport	The type of signaling protocol. Includes: UDP, TCP or TLS	string
users[i].sip.media	The type of media stream protocol. Includes: RTP or SRTP	string
users[i].sip.inbound	Object containing the inbound information.	object
users[i].sip.inbound.uri	The unique SIP URI that calls to this user will be delivered to.	string
users[i].app_id	The Application ID for this SIP User.	string
users[i].subaccount_id	The Sub Account ID for this SIP User. (if applicable)	string

Example Response

{
    "users": [
        {
            "created_on": "2021-08-13T14:23:37.000Z",
            "updated_on": "2022-08-29T21:39:03.000Z",
            "user_id": "952bfde1-8079-4c32-92c3-6339810e1be3",
            "status": "active",
            "description": "my sip user",
            "firstname": "Jane",
            "lastname": "Doe",
            "country": "US",
            "uri": "/v1/Users/952bfde1-8079-4c32-92c3-6339810e1be3",
            "sip": {
                "authentication": {
                    "username": "jane",
                    "password": null
                },
                "domain": "domain.sip.user.voxolo.gy",
                "outbound": {
                    "assigned_to": "Trunks/fa12345c-6d7a-890d-1c23-4dd56cfc7890",
                    "caller_id": {
                        "external_no": "+19495551234",
                        "internal_no": "123",
                        "internal_cnam": "JANEDOE"
                    }
                },
                "transport": "UDP",
                "media": "RTP",
                "inbound": {
                    "uri": "sip:jane@domain.sip.user.voxolo.gy"
                }
            },
            "app_id": "cc12c345-a67b-8901-23f4-56789fa0aef1",
            "subaccount_id": null
        }
    ]
}

Response Codes

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

View SIP User

Returns the SIP User object of the specified SIP User.

GET Users/{user_id}

Authentication Type

API Key (Application-level)

Request

Parameter	Description	Type	Required
user_id	The ID of the SIP User	string (path)	Yes

Example Request

curl -X GET \
  'https://api.voxolo.gy/v1/Users/952bfde1-8079-4c32-92c3-6339810e1be3' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

Property	Description	Type
created_on	The date when the SIP User was created.	ISO date string
updated_on	The date of the last update to the SIP User.	ISO date string
user_id	The unique ID of the SIP User.	string
status	The current status of the SIP User. Includes: active or inactive	string
description	User-definable description of the SIP User.	string
firstname	User-definable first name of the User.	string
lastname	User-definable last name of the User.	string
country	The country of the User.	string (ISO Alpha-2)
uri	The URI to view the SIP User’s details.	string
sip	Object containing sip settings and information	object
sip.authentication	Object containing sip authentication credentials.	object
sip.authentication.username	The SIP User’s username	string
sip.authentication.password	The SIP User’s password	string
sip.domain	The unique SIP User URL.	string
sip.outbound	Object containing outbound information.	object
sip.outbound.assigned_to	The campaign or trunk to which the SIP user is assigned.	string
sip.outbound.caller_id	Object containing caller ID information.	object
sip.outbound.caller_id.external_no	The caller ID displayed when calling external numbers.	string
sip.outbound.caller_id.internal_no	The caller ID displayed when calling internal numbers or extentions.	string
sip.outbound.caller_id.internal_cnam	The caller name when calling internal numbers or extentions.	string
sip.transport	The type of signaling protocol. Includes: UDP, TCP or TLS	string
sip.media	The type of media stream protocol. Includes: RTP or SRTP	string
sip.inbound	Object containing the inbound information.	object
sip.inbound.uri	The unique SIP URI that calls to this user will be delivered to.	string
app_id	The Application ID for this SIP User.	string
subaccount_id	The Sub Account ID for this SIP User. (if applicable)	string

Example Response

 {
            "created_on": "2021-08-13T14:23:37.000Z",
            "updated_on": "2022-08-29T21:39:03.000Z",
            "user_id": "952bfde1-8079-4c32-92c3-6339810e1be3",
            "status": "active",
            "description": "my sip user",
            "firstname": "Jane",
            "lastname": "Doe",
            "country": "US",
            "uri": "/v1/Users/952bfde1-8079-4c32-92c3-6339810e1be3",
            "sip": {
                "authentication": {
                    "username": "jane",
                    "password": null
                },
                "domain": "domain.sip.user.voxolo.gy",
                "outbound": {
                    "assigned_to": "Trunks/fa12345c-6d7a-890d-1c23-4dd56cfc7890",
                    "caller_id": {
                        "external_no": "+19495551234",
                        "internal_no": "123",
                        "internal_cnam": "JANEDOE"
                    }
                },
                "transport": "UDP",
                "media": "RTP",
                "inbound": {
                    "uri": "sip:jane@domain.sip.user.voxolo.gy"
                }
            },
            "app_id": "cc12c345-a67b-8901-23f4-56789fa0aef1",
            "subaccount_id": null
        }

Response Codes

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

Create SIP User

Creates a SIP User.

POST /User

Authentication Type

API Key (Application-level)

Request

Parameter	Description	Type	Required
description	User-definable description of the SIP User.	string	Yes
firstname	User-definable first name of the User.	string	No
lastname	User-definable last name of the User.	string	No
country	The country of the User.	string (ISO Alpha-2)	No
subaccount_id	The Sub Account ID for this SIP User. (if applicable)	string	No
sip	Object containing sip settings and information	object	Yes
sip.authentication	Object containing sip authentication credentials.	object	Yes
sip.authentication.username	The SIP User’s username	string	Yes
sip.authentication.password	The SIP User’s password	string	Yes
sip.domain	The unique SIP User URL.	string	Yes
sip.outbound	Object containing outbound information.	object	Yes
sip.outbound.assigned_to	The campaign or trunk to which the SIP user is assigned.	string	Yes
sip.outbound.caller_id	Object containing caller ID information.	object	No
sip.outbound.caller_id.external_no	The caller ID displayed when calling external numbers.	string	No
sip.outbound.caller_id.internal_no	The caller ID displayed when calling internal numbers or extentions.	string	No
sip.outbound.caller_id.internal_cnam	The caller name when calling internal numbers or extentions.	string	No
sip.transport	The type of signaling protocol. Includes: UDP, TCP or TLS	string	No
sip.media	The type of media stream protocol. Includes: RTP or SRTP	string	No
sip.inbound	Object containing the inbound information.	object	No
sip.inbound.uri	The unique SIP URI that calls to this user will be delivered to.	string	No

Example Request of Inbound Trunk

curl -X POST \
  https://api.voxolo.gy/v1/Users \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "description": "my sip user",
    "firstname": "Jane",
    "lastname": "Doe",
    "country": "US",
        "sip": {
            "authentication": {
                "username": "jane",
                "password": null
            },
            "domain": "domain.sip.user.voxolo.gy",
            "outbound": {
                "assigned_to": "Trunks/fa12345c-6d7a-890d-1c23-4dd56cfc7890",
                "caller_id": {
                    "external_no": "+19495551234",
                    "internal_no": "123",
                    "internal_cnam": "JANEDOE"
                }
            },
            "transport": "UDP",
            "media": "RTP"
        },
    "app_id": "cc12c345-a67b-8901-23f4-56789fa0aef1"
  }'

Response

Property	Description	Type
created_on	The date when the SIP User was created.	ISO date string
updated_on	The date of the last update to the SIP User.	ISO date string
user_id	The unique ID of the SIP User.	string
status	The current status of the SIP User. Includes: active or inactive	string
description	User-definable description of the SIP User.	string
firstname	User-definable first name of the User.	string
lastname	User-definable last name of the User.	string
country	The country of the User.	string (ISO Alpha-2)
uri	The URI to view the SIP User’s details.	string
sip	Object containing sip settings and information	object
sip.authentication	Object containing sip authentication credentials.	object
sip.authentication.username	The SIP User’s username	string
sip.authentication.password	The SIP User’s password	string
sip.domain	The unique SIP User URL.	string
sip.outbound	Object containing outbound information.	object
sip.outbound.assigned_to	The campaign or trunk to which the SIP user is assigned.	string
sip.outbound.caller_id	Object containing caller ID information.	object
sip.outbound.caller_id.external_no	The caller ID displayed when calling external numbers.	string
sip.outbound.caller_id.internal_no	The caller ID displayed when calling internal numbers or extentions.	string
sip.outbound.caller_id.internal_cnam	The caller name when calling internal numbers or extentions.	string
sip.transport	The type of signaling protocol. Includes: UDP, TCP or TLS	string
sip.media	The type of media stream protocol. Includes: RTP or SRTP	string
sip.inbound	Object containing the inbound information.	object
sip.inbound.uri	The unique SIP URI that calls to this user will be delivered to.	string
app_id	The Application ID for this SIP User.	string
subaccount_id	The Sub Account ID for this SIP User. (if applicable)	string

Example Response

{
    "created_on": "2021-08-13T14:23:37.000Z",
    "updated_on": "2022-08-29T21:39:03.000Z",
    "user_id": "952bfde1-8079-4c32-92c3-6339810e1be3",
    "status": "active",
    "description": "my sip user",
    "firstname": "Jane",
    "lastname": "Doe",
    "country": "US",
    "uri": "/v1/Users/952bfde1-8079-4c32-92c3-6339810e1be3",
    "sip": {
        "authentication": {
            "username": "jane",
            "password": null
        },
        "domain": "domain.sip.user.voxolo.gy",
        "outbound": {
            "assigned_to": "Trunks/fa12345c-6d7a-890d-1c23-4dd56cfc7890",
            "caller_id": {
                "external_no": "+19495551234",
                "internal_no": "123",
                "internal_cnam": "JANEDOE"
            }
        },
        "transport": "UDP",
        "media": "RTP",
        "inbound": {
            "uri": "sip:jane@domain.sip.user.voxolo.gy"
        }
    },
    "app_id": "cc12c345-a67b-8901-23f4-56789fa0aef1",
    "subaccount_id": null
}

Response Codes

Status	Description
201	SIP User created
4xx & 5xx	General Error Codes

Update SIP User

Updates the SIP User configuration of a specified User.

PUT /Users/{user_id}

Authentication Type

API Key (Application-level)

Request

Parameter	Description	Type	Required
user_id	The unique ID of the SIP User.	string	Yes (path)
description	User-definable description of the SIP User.	string	No
firstname	User-definable first name of the User.	string	No
lastname	User-definable last name of the User.	string	No
country	The country of the User.	string (ISO Alpha-2)	No
subaccount_id	The Sub Account ID for this SIP User. (if applicable)	string	No
sip	Object containing sip settings and information	object	No
sip.authentication	Object containing sip authentication credentials.	object	No
sip.authentication.username	The SIP User’s username	string	No
sip.authentication.password	The SIP User’s password	string	No
sip.domain	The unique SIP User URL.	string	No
sip.outbound	Object containing outbound information.	object	No
sip.outbound.assigned_to	The campaign or trunk to which the SIP user is assigned.	string	No
sip.outbound.caller_id	Object containing caller ID information.	object	No
sip.outbound.caller_id.external_no	The caller ID displayed when calling external numbers.	string	No
sip.outbound.caller_id.internal_no	The caller ID displayed when calling internal numbers or extentions.	string	No
sip.outbound.caller_id.internal_cnam	The caller name when calling internal numbers or extentions.	string	No
sip.transport	The type of signaling protocol. Includes: UDP, TCP or TLS	string	No
sip.media	The type of media stream protocol. Includes: RTP or SRTP	string	No
sip.inbound	Object containing the inbound information.	object	No
sip.inbound.uri	The unique SIP URI that calls to this user will be delivered to.	string	No

Example Request

curl -X PUT \
  https://api.voxolo.gy/v1/Users/952bfde1-8079-4c32-92c3-6339810e1be3 \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "description": "updated description"
  }'

Response

Property	Description	Type
created_on	The date when the SIP User was created.	ISO date string
updated_on	The date of the last update to the SIP User.	ISO date string
user_id	The unique ID of the SIP User.	string
status	The current status of the SIP User. Includes: active or inactive	string
description	User-definable description of the SIP User.	string
firstname	User-definable first name of the User.	string
lastname	User-definable last name of the User.	string
country	The country of the User.	string (ISO Alpha-2)
uri	The URI to view the SIP User’s details.	string
sip	Object containing sip settings and information	object
sip.authentication	Object containing sip authentication credentials.	object
sip.authentication.username	The SIP User’s username	string
sip.authentication.password	The SIP User’s password	string
sip.domain	The unique SIP User URL.	string
sip.outbound	Object containing outbound information.	object
sip.outbound.assigned_to	The campaign or trunk to which the SIP user is assigned.	string
sip.outbound.caller_id	Object containing caller ID information.	object
sip.outbound.caller_id.external_no	The caller ID displayed when calling external numbers.	string
sip.outbound.caller_id.internal_no	The caller ID displayed when calling internal numbers or extentions.	string
sip.outbound.caller_id.internal_cnam	The caller name when calling internal numbers or extentions.	string
sip.transport	The type of signaling protocol. Includes: UDP, TCP or TLS	string
sip.media	The type of media stream protocol. Includes: RTP or SRTP	string
sip.inbound	Object containing the inbound information.	object
sip.inbound.uri	The unique SIP URI that calls to this user will be delivered to.	string
app_id	The Application ID for this SIP User.	string
subaccount_id	The Sub Account ID for this SIP User. (if applicable)	string

Example Response

{
    "created_on": "2021-08-13T14:23:37.000Z",
    "updated_on": "2022-08-29T21:39:03.000Z",
    "user_id": "952bfde1-8079-4c32-92c3-6339810e1be3",
    "status": "active",
    "description": "updated description",
    "firstname": "Jane",
    "lastname": "Doe",
    "country": "US",
    "uri": "/v1/Users/952bfde1-8079-4c32-92c3-6339810e1be3",
    "sip": {
        "authentication": {
            "username": "jane",
            "password": null
        },
        "domain": "domain.sip.user.voxolo.gy",
        "outbound": {
            "assigned_to": "Trunks/fa12345c-6d7a-890d-1c23-4dd56cfc7890",
            "caller_id": {
                "external_no": "+19495551234",
                "internal_no": "123",
                "internal_cnam": "JANEDOE"
            }
        },
        "transport": "UDP",
        "media": "RTP",
        "inbound": {
            "uri": "sip:jane@domain.sip.user.voxolo.gy"
        }
    },
    "app_id": "cc12c345-a67b-8901-23f4-56789fa0aef1",
    "subaccount_id": null
}

Response Codes

Status	Description
200	Returns the User Object
4xx & 5xx	General Error Codes

Delete SIP User

Deletes the specified SIP User.

DELETE /Users/{user_id}

Authentication Type

API Key (Application-level)

Request

Parameter	Description	Type	Required
user_id	The ID of the SIP User .	string (path)	Yes

Example Request

curl -X DELETE \
  https://api.voxolo.gy/v1/Users/952bfde1-8079-4c32-92c3-6339810e1be3 \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

No Response Body

Response Codes

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

Transcription

Start Transcription

Initiates speech-to-text transcription on a specified live call.

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

Authentication Type

API Key (Application-level)

Request

Parameter	Description	Type	Required
call_id	ID of the call.	string (path)	Yes
tracks	Defines which sides of the call to transcribe. Accepts caller (far end), transfer (near end). Default: caller.	array	No
hints	An array of strings of known/possible words used on the call, that may be difficult to transcribe correctly, to help with accuracy.	array	No
live_transcript_webhook	Object with configuration of where to send live transcription webhooks. If not provided, no live transcription webhooks are sent.	object	No
live_transcript_webhook.url	The URL destination to send the webhooks to.	string	No
live_transcript_webhook.method	The request method. Accepts GET and POST. Default: POST.	string	No
live_transcript_webhook.content_type	The format of the payload posted to the endpoint. Accepts: application/json, application/xml, application/x-www-form-urlencoded. Default: application/json.	string	No
end_transcript_webhook	Object with configuration of where to send the final transcription webhook at the end of the call. If not provided, transcript is sent to the URL in the default callback configuration.	object	No
end_transcript_webhook.url	The URL destination to send the webhook to.	string	No
end_transcript_webhook.method	The request method. Accepts GET and POST. Default: POST.	string	No
end_transcript_webhook.content_type	The format of the payload posted to the endpoint. Accepts: application/json, application/xml, application/x-www-form-urlencoded. Default: application/json.	string	No
end_transcript_webhook_failover	Object with configuration of where to send the final transcription webhook after the call if the request to the primary URL fails.	object	No
end_transcript_webhook_failover.url	The URL destination to send the webhook to.	string	No
end_transcript_webhook_failover.method	The request method. Accepts GET and POST. Default: POST.	string	No
end_transcript_webhook_failover.content_type	The format of the payload posted to the endpoint. Accepts: application/json, application/xml, application/x-www-form-urlencoded. Default: application/json.	string	No

Example Request

curl -X POST \
  https://api.voxolo.gy/v1/LiveCalls/123456@7890/Actions/Transcription/Start \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "tracks": [
      "caller",
      "transfer"
    ],
    "hints": [
        "Voxology",
        "CPaaS",
        "API"
    ],
    "live_transcript_webhhok": {
        "url": "https://example.webhook.com/live_transcript",
    },
    "end_transcript_webhook": {
        "url": "https://example.webhook.com/end_transcript"
    },
    "end_transcript_failover": {
        "url": "https://example.webhhok.com/end_transcript_failover"
    }
    "
  }'

Response

No Response Body

Response Codes

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

Stop Transcription

Stops speech-to-text transcription on a specified live call.

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

Authentication Type

API Key (Application-level)

Request

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

Example Request

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

Response

No Response Body

Response Codes

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

Verify API

Initiate Verification

Initiates a Verification to a provided phone number using either SMS or Voice. SMS message and Voice calls use a default script to provide a unique code to the user being verified.

Verifications will have a status of pending until a code is verified, the max assert attempts is reached, the time-to-live expires, or the Verification is canceled.

SMS Default Message: {Brand}: Your one time passcode is {code}.

Voice Default Message: This is a verification call {from Brand}. Your one time passcode is {code}.

POST /Verifications

AUTHENTICATION TYPE

API Key (Application-level)

REQUEST

Parameter	Description	Type	Required
verify_no	The phone number, in E.164 format, the Verification will be sent to.	string	Yes
api_no	The phone number, in E.164 format, the Verification will be sent from. The phone number must be provisioned to your Voxology application.	string	Yes
channel	The channel to use for the Verification. Accepts sms or voice. Defaults to sms.	string	No
brand	Brand prefix to insert at the start of the SMS message or text-to-speech script for voice calls.	string	No
code_length	The number of characters to use for the code. Default is 6 characters.	integer	No
time_to_live	The time in minutes before a Verification times out. Valid: 1 to 30. Default is 10.	integer	No

Example Request

curl -X POST \
  https://api.voxolo.gy/v1/Verifications \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
   -d '{
    "verify_no": "+15558701034",
    "api_no": "+15553246897",
    "channel": "sms",
    "brand": "Company Name",
    "code_length": 6
    "time_to_live": 10
}'

Response

Property	Description	Type
verification_id	ID for this Verification.	string
verify_no	The phone number, in E.164 format, the Verification will be sent to.	string
api_no	The phone number, in E.164 format, the Verification will be sent from.	string
channel	The channel used for the Verification. Includes sms and voice.	string
brand	Brand prefix inserted at the start of the SMS message or text-to-speech script for voice calls.	string
status	The status of the Verification. All Verifications will have status pending upon creation.	string
reason	A descriptive reason for status of the Verification. Null while pending.	string
code_length	The number of characters used for the code.	string
time_to_live	The time in minutes before a Verification times out.	string
assert_attempts	The number of times a code was asserted against this Verification. Max 3 attempts before failure.	integer
created_on	The date and time the Verification was initiated.	ISO date
updated_on	The date and time the Verification was last updated.	ISO date

Example Response

{
   "verification_id": "ce66e293-c921-46ea-a085-e186f681d24c",
   "verify_no": "+15558701034",
   "api_no": "+15553246897",
   "channel": "sms",
   "brand": "Company Name",
   "status": "pending",
   "reason": null,
   "code_length": 6, 
   "time_to_live": 10,
   "assert_attempts": 0,
   "created_on": "2024-01-01T00:00:00.000Z",
   "updated_on": "2024-01-01T00:00:00.000Z",
}

Response Codes

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

Assert Verification

Asserts a user-provided code against a Verification. If the correct code is asserted, the Verification status will update to verified. Otherwise, the status will remain in pending until the max assert attempts (3) is reached. After 3 unsuccessful attempts, the Verification status will update to failed.

POST /Verifications/:verification_id/Assert

AUTHENTICATION TYPE

API Key (Application-level)

REQUEST

Parameter	Description	Type	Required
verification_id	ID of the Verification to assert.	string (path)	Yes
code	User-provided code to assert against the Verification.	string	Yes

Example Request

curl -X POST \
  https://api.voxolo.gy/v1/Verifications/ce66e293-c921-46ea-a085-e186f681d24c/Assert \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
   -d '{
    "code": "123456"
}'

Response

Property	Description	Type
verification_id	ID for this Verification.	string
status	The status of the assert attempt. Includes verified and failed.	string
attempts_remaining	The number of assert attempts remaining for this Verification.	string

Example Response

{
   "verification_id": "ce66e293-c921-46ea-a085-e186f681d24c",
   "status": "verified",
   "attempts_remaining": 2
}

Response Codes

Status	Description
200	Returns Verification ID and verification status
4xx & 5xx	General Error Codes

View Verification

Returns the Verification object of the specified Verification.

GET /Verifications/{verification_id}

AUTHENTICATION TYPE

API Key (Application-level)

REQUEST

No Request Body

Example Request

curl -X GET \
  https://api.voxolo.gy/v1/Verifications/ce66e293-c921-46ea-a085-e186f681d24c \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

Property	Description	Type
verification_id	ID for this Verification.	string
verify_no	The phone number, in E.164 format, the Verification will be sent to	string
api_no	The phone number, in E.164 format, the Verification will be sent from.	string
channel	The channel to use for the Verification. Includes sms and voice.	string
brand	Brand prefix inserted at the start of the SMS message or text-to-speech script for voice calls.	string
status	The status of the Verification. Includes pending, verified, canceled, failed and timed-out.	string
reason	A descriptive reason for status of the Verification. Null while pending.	string
code_length	The number of characters used for the code.	string
time_to_live	The time in minutes before a Verification times out. å	string
assert_attempts	The number of times a code was asserted against this Verification. Max 3 attempts before failure.	integer
created_on	The date and time the Verification was initiated.	ISO date
updated_on	The date and time the verification status was last updated.	ISO date

Example Response

{
   "verification_id": "ce66e293-c921-46ea-a085-e186f681d24c",
   "verify_no": "+15558701034",
   "api_no": "+15553246897",
   "channel": "sms",
   "brand": "Company Name",
   "status": "pending",
   "reason": null,
   "code_length": 6, 
   "time_to_live": 10,
   "created_on": "2024-01-01T00:00:00.000Z",
   "updated_on": "2024-01-01T00:00:00.000Z"
}

Response Codes

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

List Verifications

Returns a list of Verifications according to the filters provided in the request.

GET /Verifications

AUTHENTICATION TYPE

API Key (Application-level)

Request

Name	Description	Type	Required
begin_date	Date of earliest Verificaiton to fetch. Default is one hour before now.	ISO date (query)	No
end_date	Date of latest Verification to fetch. Default is now.	ISO date (query)	No
status	The status of the Verification. Accepts pending, verified, canceled, failed, and time-out.	string (query)	No
channel	The channel used on the Verification. Accepts sms and voice.	string (query)	No
verify_no	The number, in E.164 format, the Verification was sent to.	string (query)	No
api_no	The number, in E.164 format, the Verification was sent from.	string (query)	No

Example Request

curl -X GET \
  https://api.voxolo.gy/v1/Verifications?begin_date=2024-01-01T00:00:00.000Z&end_date=2024-01-01T23:59:59.999Z \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY'

Response ADD VERIFICATIONS ARRAY

Property	Description	Type
verifications	An array of Verification objects.	string
verifications[i].verification_id	ID for this Verification.	string
verifications[i].verify_no	The phone number, in E.164 format, the Verification will be sent to	string
verifications[i].api_no	The phone number, in E.164 format, the Verification will be sent from.	string
verifications[i].channel	The channel used for the Verification. Includes sms and voice.	string
verifications[i].brand	Brand prefix inserted at the start of the SMS message or text-to-speech script for voice calls.	string
verifications[i].status	The status of the Verification. Includes pending, canceled, verified, failed and timed-out.	string
verifications[i].reason	A descriptive reason for status of the Verification. Null while pending.	string
verifications[i].code_length	The number of characters used for the code.	string
verifications[i].time_to_live	The time in minutes before a Verification times out.	string
verifications[i].assert_attempts	The number of times a code was asserted against this Verification. Max 3 attempts before failure.	integer
verifications[i].created_on	The date and time the Verification was initiated.	ISO date
verifications[i].updated_on	The date and time the Verification status was last updated.	ISO date

Example Response

{
  "verifications":[
    {
      "verification_id": "ce66e293-c921-46ea-a085-e186f681d24c",
      "verify_no": "+15558701034",
      "api_no": "+15553246897",
      "channel": "sms",
      "brand": "Company Name",
      "status": "pending",
      "reason": null,
      "code_length": 6, 
      "time_to_live": 10,
      "assert_attempts": 1, 
      "created_on": "2024-01-01T00:00:00.000Z",
      "updated_on": "2024-01-01T00:00:00.000Z",
    },
    {
      "verification_id": "c0bd9e38-46c8-4af9-9036-49ececc63868",
      "verify_no": "+15555469532",
      "api_no": "+15553246897",
      "channel": "voice",
      "brand": "Company Name",
      "status": "pending",
      "reason": null,
      "code_length": 6, 
      "time_to_live": 10,
      "assert_attempts": 0, 
      "created_on": "2024-01-01T00:00:00.000Z",
      "updated_on": "2024-01-01T00:00:00.000Z",
    }

  ]
}

Response Codes

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

Cancel Verification

Cancels the specified Verification and updates its status to canceled. Only Verifications with status pending can be canceled.

DELETE /Verifications/{verification_id}

Authentication Type

API Key (Application-level)

Request

Parameter	Description	Type	Required
verification_id	The ID of the Verification.	string (path)	Yes

Example Request

curl -X DELETE \
  https://api.voxolo.gy/v1/Verifications/c0bd9e38-46c8-4af9-9036-49ececc63868 \
  -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:

• All variable names must begin with a dollar sign $ and only contain a-z, A-Z, 0-9, _ characters;
• All variables are scoped to the call;
• Avoid handling null and undefined values. Our JS engine makes their behaviors non-obvious;
• JavaScript’s ‘truthy’ and ‘type casting’ behaviors are in full effect.

Native Constants

For convenience, some constants are made available with data about the call. These are assigned to variables and are listed below. These variables are read-only and any attempts to change their values will fail silently.

Variable Name	Type	Description
$config	object	The callback configuration object set with the /CallFlows/Callbacks request.
$lastQueuePollConnectCall	object	The last call bridged with a QUEUE poll_connect. Includes properties id and no.
$direction	string	Indicates if the call is INBOUND or OUTBOUND
$iniatedBy	string	Indicates the origin of the current call. Possible values include api for outbound Make Call requests, sip_user and sip for inbound calls from SIP Users and SIP Interface, pstn for basic inbound calls, dial and transfer for outbound DIAL and TRANSFER action calls.
$keyPresses	string	The last key presses collected by the COLLECT action. To check for no keys pressed, use $keyPresses == "".
$extensionDialed	string	If the digits pressed in a COLLECT action match an existing extension on your application, that extension is stored here. The value will be stomped by any subsequent extensions entered.
$now	integer	The current timestamp in milliseconds.
$callTime	integer	The duration of the call in milliseconds.
$startTime	integer	The start timestamp of the call in milliseconds.
$numConferenceParticipants	string	The number of participants in the last conference referenced by the CONFERENCE action during the call. Do not use before a conference has been accessed by the action to avoid a terminal error.
$callId	string	The unique ID of the call.
$parentCallID	string	When using the DIAL action, this is the call_id of the originating call. The value is null if there is no originating call.
$appId	string	The unique ID of the application.
$collectAttempt	integer	This variable counts how many times a call has visited each COLLECT action, starting with 1. This counter makes it easy to retry a COLLECT with IF and GOTO actions.
$callerNo	string	The phone number of the connected (or far end) call (E.164 format: +17145551212).
$callerNoLatitude	string	The latitude of the connected call’s phone number. Possibly null.
$callerNoLongitude	string	The longitude of the connected call’s phone number. Possibly null.
$callerNoPostalCode	string	The postal code (zip) of the connected call’s phone number. Possibly null.
$callerNoCity	string	The city of the connected call’s phone number. Possibly null.
$callerNoRateCenter	string	The rate center of the connected call’s phone number, if applicable. Possibly null.
$callerNoLata	string	The lata of the connected call’s phone number, if applicable. Possibly null.
$callerNoRegion	string	The two-character region (state) code of the connected call’s phone number. Possibly null.
$callerNoCountry	string	The two-character country code of the connected call’s phone number. Possibly null.
$callerNoTimeZone	string	The time zone of the connected call’s phone number (America/Los_Angeles). Possibly null. Click here for list of time zones.
$apiNo	string	The provisioned (or near end) phone number of the API connected to the call (E.164 format: +17145551212).
$apiNoLatitude	string	The latitude of the API phone number. Possibly null.
$apiNoLongitude	string	The longitude of the API phone number. Possibly null.
$apiNoPostalCode	string	near phone number zip/postal code
$apiNoCity	string	The city of the API phone number. Possibly null.
$apiNoRateCenter	string	The rate center of the API phone number, if applicable. Possibly null.
$apiNoLata	string	The lata of the API phone number, if applicable. Possibly null.
$apiNoRegion	string	The two-character region (state) code of the API phone number. Possibly null.
$apiNoCountry	string	The two-character country code of the API phone number. Possibly null.
$apiNoTimeZone	string	The time zone of the API phone number (America/Los_Angeles). Possibly null. Click here for list of time zones.
$speechText	string	The last speech to text collected by the COLLECT action. To check for collected text, use $speechText == "hello".
$speechConfidenceScore	float	The confidence score from the last COLLECT action. Ranges from 0-1.
$stirShakenStatus	string	A status indicating the STIR/SHAKEN attestation level assigned to the call; includes number validation on inbound calls. See the STIR SHAKEN Status table for details.

User Defined Variables

In addition to the special writable variables $sessionData and $webhookData, you are free to create your own local variables using any of the supported data types (string, number, boolean, array and object).

Variable Name	Type	Description
$sessionData	object	The session_data set in the /Dials/Connect request and/or the DIAL and SESSIONDATA actions.
$webhookData	object	When a WEBHOOK action returns a JSON response, it is available via this variable. Default: undefined.
$userSipHeaders	object	If user_sip_headers are provided on a DIAL or TRANSFER, they are available via this variable. The key/value pairs will be flattened and converted to User-to-User and X-... SIP headers on the call. Default: undefined.

Variable Handling

Using variables in Voxology’s JSON Call Flow Actions is very straight-forward once you get the hang of it. Variable assignment is done with a “special” JSON Action. This action is simplified to make variable handling as pleasant as possible in JSON.

Tutorial

The JSON KEY is the name of the variable and the JSON VALUE is the expression to evaluate. The right-side JSON value MUST ALWAYS be a STRING.

Basically, take a regular JavaScript variable assignment:

Change the = to a : and wrap both sides in double-quotes (with the necessary escaping) to make it JSON-friendly:

String assignment as done in plain JavaScript:

String assignment as done in a JSON Action (notice the nested quoting):

While it is tempting (since it is legal JSON) to try assigning basic data types like this:

It will not work! Remember, the right-side value is actually an expression that is evaluated. This lets us do things like this:

In the above example, notice how multiple variables are handled in one JSON Action object. This is legal, however assignment order is NOT guaranteed. If assignment order is critical, separate the assignments into their own objects as array order is guaranteed:

Examples

Example User Defined Variables

{
  "actions": [
    {
      "type": "SAY",
      "params": {
        "text": "We're about to assign some variables."
      }
    },
    {
      "$conferenceName": "'MyConference'",
      "$counter": "0",
      "$myObj": "{}",
      "$myPets": "['Whiskers', 'Spot', 'Bubbles']",
      "$myPetsAgain": "{cat: 'Whiskers', dog: 'Spot', fish: 'Bubbles'}"
    },
    {
      "$conferenceName": "'MyConference' + $counter"
    },
    {
      "$sessionData.isInConference": "false"
    },
    {
      "$myObj.foo": "'bar'"
    },
    {
      "$counter": "$counter + 1"
    },
    {
      "$myDog": "$myPets[1]"
    },
    {
      "$myPetsAgain.bird": "'Tweety'"
    }
  ]
}

Variable:Expression	Comment
“$conferenceName”: “‘MyConference’”	Notice how the MyConference string must use inner single-quotes.
“$counter”: “0”	Numbers, booleans, arrays and objects must be in quotes.

Variable:Expression	Comment
“$conferenceName: ”'MyConference’ + $counter"	Updates $conferenceName to “myConference0”.
“$sessionData.isInConference: "false”	Updates $sessionData.isInConference to false.
“$myObj.foo”: “'bar’”	Updates a previously initialized object.
“$counter”: “$counter + 1”	Increments $counter by one.
“$myDog”; “$myPets[1]”	Assigns value at index 1 (“Spot”) to $myDog.
“$myPetsAgain.bird”: “'Tweety’”	Adds new key/value to $myPetsAgain.

Template Mapping

Template Mappings look like {{property}} and {{property|default}}, where property is the callback data property name (flattened) and default is an optional default value to use if no property name match is found.

Example Template Mapping

{
  "actions": [
    {
      "type": "SAY",
      "params": {
        "text": "Hello, {{session_data.firstName|guest}}. Welcome to our conference.",
        "loop": 1
      }
    },
    {
      "type": "CONFERENCE",
      "params": {
        "name": "{{session_data.conferenceName}}"
      }
    },
    {
      "type": "SAY",
      "params": {
        "text": "You have left the conference. This call lasted {{duration}} seconds."
      }
    }
  ]
}

String Interpolation

It is possible to dynamically use variables in select Action properties, like SAY’s “text” property.

Supported properties are marked with an asterisk (*) in our docs. These will be parsed live.

By adding the spread (...) operator before a variable name, you can have the SAY action say each character individually. This is useful for reading back numeric strings like key presses, phone number, zip code, SSN, credit card, etc.

Example String Interpolation

{
  "actions": [
    {
      "type": "SAY",
      "params": {
        "text": "Hello, ${sessionData.firstName}. Welcome to our conference.",
        "repeat": 1
      }
    },
    {
      "type": "CONFERENCE",
      "params": {
        "name": "myConference"
      }
    },
    {
      "type": "SAY",
      "params": {
        "text": "You have left the conference. Thank you for calling ${...callerNo}."
      }
    }
  ]
}

Errors

General Errors

Status	Code	Message	Help	User_message
400	400001	Validation Error	[Custom Message with what failed validation]	[Custom Message]
400	400010	Parsing Error	[Custom Message]	A 3rd party service could not understand our request.
400	400999	[Custom Message]	It appears that the request was invalid. Check the ‘message’ property for more detail.	A 3rd-party service could not understand your request. This could be due to submitting invalid data.
401	401001	Failed Authentication	We are unable to authenticate your request. Your API Key may be inaccurate or missing. For all application or sub account requests, use the API Key found on the Application page in the portal: https://portal.voxolo.gy/.	We are having trouble accessing a 3rd Party service.
401	401002	Failed Authentication	We are unable to authenticate your request. Your auth string may be inaccurate or missing. For all account level requests, use the basic auth authorization header found on your Account page in the portal: https://portal.voxolo.gy/.	We are having trouble accessing a 3rd Party service.
402	402001	Insufficient Funds	Your account balance is too low. Please make a payment to resume service.	A 3rd-party service could not complete the request. Report code 402001 to customer support.
403	403001	Forbidden	Requests must be made through https://api.voxolo.gy.	The specified phone number(s) were not assigned.
404	404001	Not Found	The endpoint you are trying to access does not exist. Check your code for typos. Review our docs.	We are having trouble accessing a 3rd Party service.
404	404002	Not Found	The requested resource path or method is not supported.	The resource we attempted to access no longer exists.
405	405001	Method Not Found	This API does not support the X method.
429	400429	Too Many Requests	You exceeded your maximum requests per minute.	A 3rd-party service could not complete the request. Report code 400429 to customer support.
500	500990	[Custom Message]	It appears that our upstream server threw an internal error. You will likely need to contact support to clear this up.	A 3rd-party service could not process your request.
500	500991	Server Error	[Custom Message]	A 3rd party service failed to handle our request.
500	500999	Uncaught Error: [fault.name]; [fault.type]; [fault.category]	This error occurred in our proxy layer. Check the 'message’ for details and contact support if the error continues.	A 3rd-party service returned an unexpected error.
500	500911	Fatal System Error	[Custom Message] Contact Support.	[Custom Message]

Caller ID Errors

Status	Code	Message	Help	User_message
400	404254	1001: failed to insert caller-id: this caller-id already exists	It appears that the request was invalid. Check the 'message’ property for more detail.	A 3rd-party service could not understand your request. This could be due to submitting invalid data.
404	404254	Not Found	The Call ID Number does not exist in your application. It may have been removed or never added.	The Caller ID Number could not be found.

Call Flow Errors

Status	Code	Message	Help	User_message
404	404102	Not Found	The Call ID Number does not exist in your application. It may have been removed or never added.	The Caller ID Number could not be found.
500	500101	Storage Error	[Custom Message]	[Custom Message]
500	500102	Database Error	[Custom Message]	[Custom Message]

Conference Errors

Status	Code	Message	Help	User_message
404	404404	Not Found	The Call ID is incorrect or the call ended and is longer available via LiveCalls.	A live call could not be found with the ID provided.
404	404701	Not Found	The conference may have been empty too long and destroyed.	The requested conference participant was not found.
404	404702	Not Found	The participant may not be in the conference any longer.	The requested conference participant was not found.

Integration Errors

Status	Code	Message	Help	User_message
500	500501	Storage Error	[Custom Message]	[Custom Message]

Live Calls Errors

Status	Code	Message	Help	User_message
400	400999	The underlying audio file you are attempting to play on the call was not found. Check your audio file.	It appears that the request was invalid. Check the 'message’ property for more detail.	A 3rd-party service could not understand your request. This could be due to submitting invalid data.
404	404404	Not Found	The Call ID is incorrect or the call ended and is longer available via LiveCalls.	A live call could not be found with the ID provided.

Make Call Error

Status	Code	Message	Help	User_message
429	400378	Too many calls	Failed to make call due to call throttle limit.	A 3rd-party service could not complete the request. Report code 400378 to customer support.

Message Errors

Status	Code	Message	Help	User_message
403	403293	Unable to make call. Caller ID verification required.	In order to make a call appear from this phone number, it must be a verified Caller ID on the application or sub account from which you are making the request.	A 3rd-party service could not process your request.

Message Status Errors

Status	Code	Message	Help
Undelivered	3001	Destination is invalid or not SMS enabled	The number you are messaging is incapable of receiving SMS/MMS messages.
Undelivered	3002	Subscriber is opted out or blocked	The number you are messaging has previously opted out of, or blocked, messages from either the sending number or the 10DLC campaign it’s associated with.
Undelivered	3003	Message expired	The message was unable to be processed before it’s time to live expired.
Undelivered	3004	Message rejected by SMS provider	Voxology’s underlying SMS provider rejected the message for an unstated reason.
Undelivered	3005	Attachment exceeds maximum size	The file being sent is too large, reduce your file size.
Undelivered	3006	Too many recipients	There are too many recieving numbers in this message. Split the recipients into multiple messages to send.
Undelivered	3007	Message contains invalid character	An unsupported character was used in this message.
Undelivered	3008	Message throttled by provider, reduce sending speed	You have exceeded the Message Per Second rate the sending number, or the 10DLC Brand it’s associated with, is approved for.
Undelivered	3009	Error accessing media URL	Voxology’s underlying SMS provider is unable to access the media URL provided in this message.
Undelivered	3010	Exceeded sending limit	You have exceeded the sending limit for this number, or the 10DLC Brand it’s associated with.
Undelivered	3011	Message content refused	Your message may contain content, images, or keywords that fall under unacceptable use cases for SMS.
Undelivered	3012	Message contains invalid URL	The URL in the message has been flagged as invalid and Voxology’s underlying SMS provider rejected the message.
Undelivered	3013	Message too big to send	You have exceeded the character limit for this message. Shorten the content of your message before sending.
Undelivered	3014	Message filtered as Spam	Either Voxology’s underlying SMS provider or one of the mobile carriers has flagged this message as spam.
Undelivered	3015	Daily message quota exceeded	You have exceeded the daily message volume limit for this number, or the 10DLC Brand it’s associated with.
Undelivered	3016	Short Code verification error	The SMS Short Code you are sending from has not finished the verification process and is unable to send messages at this time.
Undelivered	3098	Message could not be delivered	The message was sent from Voxology and failed with one of our underlying SMS providers for an unstated reason.
Failed	3099	SMS provider is unreachable	Voxology’s underlying SMS provider is temporarily unreachable. Messages with this failure reason are not charged.

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.