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!
The collection comes with the Voxology REST API
environment. Be sure to update the X-API-KEY
and BASIC_AUTH
values after you complete your sign up.
Overview
Call Flow Loop
Example Response
{
"actions": [
{
"type": "SAY",
"params": {
"text": "Hello, Jill",
"loop": 1
}
},
{
"type": "CONFERENCE",
"params": {
"name": "test-conf"
}
},
{
"type": "SAY",
"params": {
"text": "You have left the conference. Please rate your experience from 1 to 5."
}
},
{
"name": "rating",
"type": "COLLECT",
"params": {
"num_digits": 1,
"finish_on_key": "pound",
"timeout": 3000
}
},
{
"type": "SAY",
"params": {
"text": "Thank you and good bye."
}
}
]
}
Voxology’s Call Flow Loop allows you to control phone calls using our set of Call Flow Actions. When a call is initiated or received, Voxology will make a request to the URL that you designate to fetch instructions from your server. Your response will determine what to do next with the call.
Multi-Action Processing
Responses can be as simple as a single action.
Example: SAY
“Hello, Jill”.
Or it can be an array of actions that lead the caller through a much more complicated call flow.
Example: SAY
“Hello, Jill”, put the caller in a CONFERENCE
, wait until the caller leaves the conference (press #), SAY
a question, COLLECT
a key press, and SAY
goodbye, HANGUP
.
This combined with our other tools like session data, conditionals, and variables may come as good news to those who have found themselves in ‘callback hell’ while using other services.
Phone Number Configuration
After purchasing and assigning one or more phone numbers to CallFlows via the REST API, you must configure the callback settings for the phone number(s) via Update Call Flow Configuration. Once configured, your server will get callback requests to control calls.
How it Works
To learn more about our call flow loop, visit our How It Works pages:
Action Types
All actions have type, params, name and comments properties and can be passed in an array.
Property | Description | Type | Required |
---|---|---|---|
type | Accepts: COLLECT , CONFERENCE , DETECT , DIAL , FOREACH , GOTO , HANGUP , IF , LABEL , PAUSE , PLAY , QUEUE , RECORD , RECORDMESSAGE , REDIRECT , REJECT , SAY , SESSIONDATA , SMS , STREAM ,STOP , TRANSFER and WEBHOOK . |
string | Yes |
params | The parameters for the action type. See below for each type. | object | No |
name | A name to give the action. | string | Conditional |
comments | An optional string of comments to document the action. | string | No |
Supported Actions By Service
Certain action types are not supported in all Voxology services. See the table below for which actions are available for Programmable Voice and Programmable Messaging.
Action | Description | Programmable Voice | Programmable Messaging |
---|---|---|---|
COLLECT | Collect key presses or speech from the caller. | Supported | Not Supported |
CONFFERENCE | Place a caller into a conference. | Supported | Not Supported |
DETECT | Detect whether the call was picked up by a live person or voicemail box. | Supported | Not Supported |
DIAL | Initiate an outbound call to another party. | Supported | Supported |
FOREACH | Loop through an array, object or a list of Actions. | Supported | Supported |
GOTO | Jumps the call flow to a specified LABEL Action. |
Supported | Supported |
HANGUP | Hang up a call. | Supported | Not Supported |
IF | Basic if-then-else conditional. | Supported | Supported |
LABEL | Sets the entry point for a GOTO Action. |
Supported | Supported |
PAUSE | Wait to process more actions. | Supported | Supported |
PLAY | Play an audio file (or DTMF) to the caller. | Supported | Not Supported |
QUEUE | Add a caller to a queue. | Supported | Not Supported |
RECORD | Record the call. | Supported | Not Supported |
RECORDMESSAGE | Create a voicemail system. | Supported | Not Supported |
REDIRECT | Direct the call to another call flow script. | Supported | Not Supported |
REJECT | Deny the call from being connected. | Supported | Not Supported |
SAY | Read text to the caller. | Supported | Not Supported |
SESSIONDATA | Insert session_data into the call. | Supported | Supported |
SMS | Send caller a text message. | Supported | Supported |
STOP | Stop executing actions. | Supported | Not Supported |
STREAM | Stream call audio via WebSocket Messages. | Supported | Not Supported |
TRANSCRIBE | Use Speech-To-Text to Transcribe a live phone call. | Supported | Not Supported |
TRANSFER | Connect to another caller. | Supported | Not Supported |
WEBHOOK | Trigger a webhook to a designated URL. | Supported | Supported |
Callback Request // Voice
When a phone call is received or initiated, Voxology will send a request to the URL that you designate in your callback configuration. The contents will include the information that we know about the phone call.
The request payload to your callback URL will be a JSON object by default. By setting the Content-Type
in the callback configuration, you can choose to receive JSON, XML, url-encoded form data, or a URL with a query string.
Example Request // Call
{
"service": "programmable_voice",
"type": "end_call",
"initiated_by": "pstn",
"is_webhook": "false",
"app_id": "29a471cc-4ada-4249-a7a5-5046464f9887",
"subaccount_id": 0,
"call_id": "12345@678",
"parent_call_id": "12345@677",
"external_id": "external_id_1234",
"external_group_id": "group_id_1234",
"start_time": "2016-09-20T21:32:28.471Z",
"direction": "inbound",
"duration": 9763,
"status": "completed",
"detection": "live_person",
"caller_no": "+19495551212",
"caller_no_latitude": "33.68248676492388",
"caller_no_longitude": "-117.7953997688318",
"caller_no_postal_code ": "92604",
"caller_no_city": "Irvine",
"caller_no_rate_center ": "IRVINE",
"caller_no_lata": "730",
"caller_no_region": "CA",
"caller_no_country": "US",
"caller_no_timezone": "America/Los_Angeles",
"api_no": "+17145551212",
"api_no_latitude": "33.83425593643128",
"api_no_longitude": "-117.9138737441611",
"api_no_postal_code": "92805",
"api_no_city": "Anaheim",
"api_no_lata": "730",
"api_no_rate_center": "ANAHEIM",
"api_no_region": "CA",
"api_no_country": "US",
"api_no_timezone": "America/Los_Angeles",
"key_presses": [
{
"name": "collectName",
"digits": "78",
"history": ["12", "23", "45", "56", "78"]
}
],
"extension_dialed": null,
"recordings": [{ "name": "recordingName", "id": "ABC123" }],
"streams": [{
"id": 775958172,
"tracks": [{
"name": "caller",
"status": "stopped",
"duration": 12482
}]
}],
"last_queue_poll_connect_call": null,
"custom_data": null,
"session_data": null,
"end_time": "2016-09-20T21:32:38.144Z",
"sip_domain": "1234-56789.accounts.sip.voxolo.gy",
"sip_forwarded_for": "192.168.1.1",
"speech": [
{
"name":"collectName",
"text":"detected speech",
"confidence_score":"0.91"
}
],
"stir_shaken_status":"TN-Validation-Passed-A",
"transfer":[
{
"call_id": "54321@123",
"no": "+15551234567",
"status": "completed",
"start_time": "2016-09-20T21:32:28.471Z",
"end_time": "2016-09-20T21:33:38.144Z"
}
]
}
Request
Property | Description | Type | When |
---|---|---|---|
service | The Voxology service that is initiating the callback request. Options: programmable_voice |
string | all |
type | Options: init_call , live_call , end_call , failed_call . |
string | all |
initiated_by | Indicates the origin of the call. Possible values include api for outbound Make Call requests, sip_user and sip for inbound calls from SIP Users and SIP Interface, pstn for basic inbound calls, dial and transfer for outbound DIAL and TRANSFER action calls. |
string | all |
app_id | The application ID for this request. | string | all |
subaccount_id | The Sub Account ID for this request. | integer | all |
call_id | The ID of the call. | string | all |
parent_call_id | When using the DIAL action, this is the call_id of the originating call. The value is null if there is no originating call. |
string | live_call, end_call |
external_id | A user-defined ID for the call. | string | all |
external_group_id | A user-defined ID for a group of calls. | string | all |
caller_no | The phone number of the connected (or far end) call (E.164 format: +17145551212). | string | all |
caller_no_latitude | The latitude of the connected call’s phone number. Possibly null. | string | all |
caller_no_longitude | The longitude of the connected call’s phone number. Possibly null. | string | all |
caller_no_postal_code | The postal code (zip) of the connected call’s phone number. Possibly null. | string | all |
caller_no_city | The city of the connected call’s phone number. Possibly null. | string | all |
caller_no_rate_center | The rate center of the connected call’s phone number, if applicable. Possibly null. | string | all |
caller_no_lata | The lata of the connected call’s phone number, if applicable. Possibly null. | string | all |
caller_no_region | The two-character region (state) code of the connected call’s phone number. Possibly null. | string | all |
caller_no_country | The two-character country code of the connected call’s phone number. Possibly null. | string | all |
caller_no_timezone | The time zone of the connected call’s phone number (America/Los_Angeles). Possibly null. Click here for list of time zones. | string | all |
api_no | The phone number provisioned to the API (E.164 format: +17145551212). | string | all |
api_no_latitude | The latitude of the API phone number. Possibly null. | string | all |
api_no_longitude | The longitude of the API phone number. Possibly null. | string | all |
api_no_postal_code | The postal code (zip) of the API phone number. Possibly null. | string | all |
api_no_city | The city of the API phone number. Possibly null. | string | all |
api_no_rate_center | The rate center of the API phone number, if applicable. Possibly null. | string | all |
api_no_lata | The lata of the API phone number, if applicable. Possibly null. | string | all |
api_no_region | The two-character region (state) code of the API phone number. Possibly null. | string | all |
api_no_country | The two-character country code of the API phone number. Possibly null. | string | all |
api_no_timezone | The time zone of the API phone number (America/Los_Angeles). Possibly null. Click here for list of time zones. | string | all |
start_time | The time the call started. | date | init_call, live_call, end_call, webhook |
end_time | The time the call ended. | date | end_call |
connect_time_sec | The length of the call in seconds from time of connect. The value is in-progress on live_call callbacks and is final on end_call callbacks. Also used for billing purposes. | integer | live_call, end_call |
direction | Specifies the direction of the call: inbound or outbound |
string | all |
duration | The length of the call in milliseconds. | long | all |
status | The current call state and progress. Codes: live-queued , live-ringing , live-in-progress , completed , busy , canceled , failed , no-answer . See the Call Status table for details on call status. |
string | all |
detection | The likely “caller” on the far end. Codes: fax , live_person , voicemail , unknown . |
string | all |
key_presses[i] | The keys pressed during the current CallFlow. | array (object) | live_call, end_call |
key_presses[i].name | The name of the COLLECT action that recorded these digits. Query string in a GET request converts to “key_presses.{name}={digits}”. |
string | live_call, end_call |
key_presses[i].digits | The last group of digits pressed during the COLLECT . |
string | live_call, end_call |
key_presses[i].history | The previous group or groups of digits pressed during the COLLECT action. This array is not returned in a callback query string. It is only returned in a callback POST body. |
array | live_call, end_call |
extension_dialed | If an extension was dialed from a COLLECT action, the most recent extension dialed is stored here. |
array | live_call, end_call |
recordings[i] | The recordings started with RECORD and/or saved with RECORDMESSAGE during the current CallFlow. |
array (object) | live_call, end_call |
recordings[i].name | The name of the RECORD or RECORDMESSAGE action. Query string converts to “recordings.{name}={digits}”. |
string | live_call, end_call |
recordings[i].id | The IDs of recordings from RECORD and RECORDMESSAGE . |
string | live_call, end_call |
streams[i] | The media streams started with STREAM during the current CallFlow. |
array (object) | live_call, end_call |
streams[i].name | The name of the STREAM action. Query string converts to “streams={streamObj}”. |
string | live_call, end_call |
streams[i].id | The IDs of streams from STREAM . |
string | live_call, end_call |
streams[i].tracks[i].name | The name of the track: caller . |
string | live_call, end_call |
streams[i].tracks[i].status | The status of the track: active , paused , stopped . |
string | live_call, end_call |
streams[i].tracks[i].duration | The length of the track in milliseconds. | integer | live_call, end_call |
streams[i].stream_data | The object containing data to be returned with the stream. | object | live_call, end_call |
speech[i] | The object containing data on the detected speech from a COLLECT action. | object | live_call, end_call |
speech[i].name | The name of the COLLECT action speech was detected for. | string | live_call, end_call |
speech[i].text | The detected speech from the COLLECT action. | string | live_call, end_call |
speech[i].confidence_score | A score from 0-1 indicating the estimated accuracy of the detected speech. This is assigned by the Google Speech API. | float | live_call, end_call |
transfer[i] | The object containing data on the second leg of a transferred call. | array (object) | live_call, end_call, webhook |
transfer[i].call_id | The ID of the call for the transfer leg. | string | live_call, end_call, webhook |
transfer[i].no | The number the call was transferred to. | string | live_call, end_call, webhook |
transfer[i].status | The current call state and progress of the transfer leg. Uses the same call status codes as all Voxology calls. See the Call Status table for details on call status | string | live_call, end_call, webhook |
transfer[i].start_time | The time the transfer leg started. | date | live_call, end_call, webhook |
transfer[i].end_time | The time the transfer leg ended. | date | live_call, end_call, webhook |
stir_shaken_status | A status indicating the STIR/SHAKEN attestation level assigned to the call; includes number validation on inbound calls. See the STIR SHAKEN Status table for details. | string | all |
last_queue_poll_connect_call | The last call bridged to this call via a QUEUE poll_connect. |
object | live_call, end_call |
last_queue_poll_connect_call.id | The bridged call’s ID. | string | live_call, end_call |
last_queue_poll_connect_call.no | The bridged call’s phone number. | string | live_call, end_call |
custom_data | The custom data set in the callback configuration. | object | all |
session_data | The session_data set in the /Dials/Connect request and/or the DIAL and SESSIONDATA actions. |
object | all |
event_name | The event_name set in the WEBHOOK action. If not a webhook request, this property is omitted. |
string | webhook |
webhook_data | The webhook_data set in the WEBHOOK action. If not a webhook request, this property is omitted. |
object | webhook |
is_webhook | The bool set to true if the callback response is coming from a WEBHOOK action, false otherwise |
boolean | all |
sip_domain | The SIP domain assigned to the application or sub-account. | string | all |
sip_forwarded_for | The origin IP address of the SIP request. | string | all |
error_code | An error code for any error that occurred while making or receiving a phone call. See Call Flow Loop errors for details. | integer | all |
error | An descriptive error message about any error that occurred while making or receiving a phone call. See Call Flow Loop errors for details. | string | all |
Callback Request // Message
When an inbound message is received, Voxology will send a callback request to the URL designated in the callback configuration of the phone number that received the message. The contents will include the information that Voxology knows about that message.
When an outbound message is sent using the Send Message Method, and a status_webhook
is 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 replacesession_data
on a specific call via your callback response in your JSON Actions during a live call;DIAL
Action // includesession_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 WEBHOOK s. |
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_no in 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 |
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 |
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 |
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 |
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 |
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 |
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 |
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. +194 |