NAV Navbar
Fs
cURL Javascript Python PHP

Introduction

Welcome to FoneStorm™, the communications API platform powered by FracTEL!

FoneStorm is compliant with the OpenAPI Specification. You can view code examples in the right column and you can switch the programming language of the examples with the tabs in the top right.

The FoneStorm API is organized around REST. We utilize built-in HTTP features, such as HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. JSON is returned by all API responses, including errors.

Using FoneStorm

You will need an active FracTEL account with API access enabled to use the FoneStorm API. Call us at (321) 499-1000 or email sales@fonestorm.com to get set up.

All operations are scoped to the FracTEL account being used to authenticate. Whenever this documentation makes reference to “the account” or “your account”, it is referring to the account that was used to obtain the API key.

Base URL

All URLs referenced in the documentation have the following base:

https://api.fonestorm.com/v2

FoneNumbers

A FoneNumber™ is an all-purpose communication service routing handle provided by FracTEL. A FoneNumber is an actual telephone number and it can be called or messaged from any landline or mobile telephone. It can be configured to route voice calls, faxes and SMS/MMS messages to another telephone. However, a FoneNumber is capable of much more – and this power is exposed through the FoneStorm API platform.

Dates and Times

Representation of dates and times are in Coordinated Universal Time (UTC). The FoneStorm API accepts and returns dates and times that are represented using ISO 8601 formats.

Rate limiting

Standard FoneStorm accounts are limited to 10 requests per second. Some services impose additional rate limits; please check the documentation carefully. Requests that exceed these limits will be rejected. Contact us if your project requires a higher transaction rate.

Sample Code and API Clients

FoneStorm clients are available in a variety of languages and environments at the client repository:

These clients are auto-generated with swagger-codegen.

Code examples throughout this documentation, with the exception of cURL examples, are based on the use of these clients.

Terms and Conditions

Your use of the FoneStorm API is subject to certain Terms and Conditions, and some API calls will allocate resources or perform tasks that incur usage fees and/or charges. You are responsible for understanding these Terms and Conditions and any and all costs associated with use or misuse of the FoneStorm API.

Authentication

Example Request

# Obtain an authentication token that is valid for two hours.
$ curl --request POST
--url 'https://api.fonestorm.com/v2/auth'
--header 'Content-Type: application/json'
--header 'Accept: application/json'
--data '{"username": "xxxxxxxxxx", "password": "xxxxxxxxxx", "expires": 7200}'
// Obtain an authentication token that is valid for two hours.
var FoneStormApi220 = require('fone_storm_api_220');
var apiInstance = new FracTelApi.AuthApi();
var username = "xxxxxxxxxx";
var password = "xxxxxxxxxx";
var opts = {
  'expires': 7200
};

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.postAuth(username, password, opts, callback);
<?php
# Obtain an authentication token that is valid for two hours.
require_once(__DIR__ . '/vendor/autoload.php');

$api_instance = new Swagger\Client\Api\AuthApi();
$username = "xxxxxxxxxx";
$password = "xxxxxxxxxx";
$expires = 7200;

try {
    $result = $api_instance->postAuth($username, $password, $expires);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling AuthApi->postAuth: ', $e->getMessage(), PHP_EOL;
}
?>
# Obtain an authentication token that is valid for two hours.
from __future__ import print_function
import time
import swagger_client
from swagger_client.rest import ApiException
from pprint import pprint

# Create an instance of the API class
api_instance = swagger_client.AuthApi()
username = 'xxxxxxxxxx'
password = 'xxxxxxxxxx'
expires = 7200

try:
    # Obtain a FracTEL Auth token
    api_response = api_instance.post_auth(username, password, expires=expires)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling AuthApi->post_auth: %s\n" % e)

Example Response

{
  "auth": {
    "token": "1825a1831d69218d474d6829501ac644",
  }
}

FoneStorm uses an API key to allow access to the API. FoneStorm expects the API key (also called a “token”) to be included in all API requests to the server, in a header that looks like the following:

token: key

The authentication endpoint allows you to obtain an authentication token that can be used to make authenticated requests to protected endpoints.

HTTP Request

Method Route
POST /auth

Body Parameters

Parameter Type Default Description
username string FracTEL username.
password string FracTEL password.
expires
optional
integer 3600 Token time to live in seconds. The maximum allowed time is 24 hours.

Response Properties

Property Type Description
auth object Authorization object.

Calls

Create Call

Example Request

# Make a voice call that plays
# a text-to-speech message
# from FoneNumber 3215551081
# to a recipient 3215551802
curl --request POST
--url 'https://api.fonestorm.com/v2/calls'
--header 'Content-Type: application/json'
--header 'Accept: application/json'
--header 'token: key'
--data '{"fonenumber":"3215551081", "to":"3215551802", "tts":"Hi, Jane this is a reminder about your appointment scheduled for tomorrow at 12:30pm."}'
// Make a voice call that plays
// a text-to-speech message
// from FoneNumber 3215551081
// to a recipient 3215551802
var FoneStormApi220 = require('fone_storm_api_220');
var apiInstance = new FoneStormApi220.CallsApi();
var fonenumber = "3215551081";
var to = "3215551802";
var opts = {
  'tts': "Hi, Jane this is a reminder about your appointment scheduled for tomorrow at 12:30pm."
};
var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.postCalls(fonenumber, to, opts, callback);
<?php
// Make a voice call that plays
// a text-to-speech message
// from FoneNumber 3215551081
// to a recipient 3215551802
require_once(__DIR__ . '/vendor/autoload.php');

$api_instance = new Swagger\Client\Api\CallsApi();
$fonenumber = "3215551081";
$to = "3215551802";
$tts = "Hi, Jane this is a reminder about your appointment scheduled for tomorrow at 12:30pm.";

try {
    $result = $api_instance->postCalls($fonenumber, $to, $tts);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling CallsApi->postCalls: ', $e->getMessage(), PHP_EOL;
}
?>
# Make a voice call that plays
# a text-to-speech message
# from FoneNumber 3215551081
# to a recipient 3215551802
from __future__ import print_function
import time
import swagger_client
from swagger_client.rest import ApiException
from pprint import pprint

# create an instance of the API class
api_instance = swagger_client.CallsApi()
fonenumber = '3215551081'
to = '3215551802'
tts = 'Hi, Jane this is a reminder about your appointment scheduled for tomorrow at 12:30pm.'

try:
    # Create a new call under the account.
    api_response = api_instance.post_calls(fonenumber, to, tts=tts)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling CallsApi->post_calls: %s\n" % e)

Example Response

{
  "call": {
    "id": "ce20fe86-b5ce-11e7-9eec-cf0ab03fdb06"
  }
}

HTTP Request

Method Route
POST /calls

Body Parameters

Parameter Type Default Description
fonenumber string FoneNumber to use as caller.
to string Phone number to call.
tts
optional
string Text to speech message.

Response Properties

Property Type Description
call object Call object.

Send Notify

Example Request

# Configure FoneNumber 3215551111 to receive a callback with
# POST data (application/x-www-form-urlencoded) to url https://requestb.in/1h8v9c01
# when a voice call is made.
curl --request POST
--url 'https://api.fonestorm.com/v2/calls/send_notify'
--header 'Content-Type: application/json'
--header 'Accept: application/json'
--header 'token: key'
--data '{"fonenumber":"3215551111", "method":"JSON", "url":"https://requestb.in/1h8v9c01"}'
// Configure FoneNumber 3215551111 to receive a callback with
// POST data (application/x-www-form-urlencoded) to url https://requestb.in/1h8v9c01
// when a voice call is made.
var FoneStormApi220 = require('fone_storm_api_220');
var apiInstance = new FoneStormApi220.CallsApi();
var fonenumber = "3215551111"; // String | Your FracTEL phone number
var method = "JSON"; // String | Callback URL method.
var url = "https://requestb.in/1h8v9c01"; // String | Callback URL.
var opts = {};

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.postCallsSendNotify(fonenumber, method, url, opts, callback);
<?php
// Configure FoneNumber 3215551111 to receive a callback with
// POST data (application/x-www-form-urlencoded) to url https://requestb.in/1h8v9c01
// when a voice call is made.
require_once(__DIR__ . '/vendor/autoload.php');

$api_instance = new Swagger\Client\Api\CallsApi();
$fonenumber = "3215551111";
$method = "JSON";
$url = "https://requestb.in/1h8v9c01";

try {
    $result = $api_instance->postCallsSendNotify($fonenumber, $method, $url);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling CallsApi->postCallsSendNotify: ', $e->getMessage(), PHP_EOL;
}
?>
# Configure FoneNumber 3215551111 to receive a callback with
# POST data (application/x-www-form-urlencoded) to url https://requestb.in/1h8v9c01
# when a voice call is made.
from __future__ import print_function
import time
import swagger_client
from swagger_client.rest import ApiException
from pprint import pprint

# create an instance of the API class
api_instance = swagger_client.CallsApi()
fonenumber = '3215551111'
method = 'JSON'
url = 'https://requestb.in/1h8v9c01'

try:
    # Configure the callback URL to notify when a call is made.
    api_response = api_instance.post_calls_send_notify(fonenumber, method, url)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling CallsApi->post_calls_send_notify: %s\n" % e)

Example Response

{
  "fonenumber": {
    "fonenumber": "3215551111",
    "state": "FL",
    "rate_center": "ORLANDO",
    "is_active": "yes",
    "sms_options": {
      "receive": {
        "type": "",
        "email": "",
        "device": "",
        "forward": "",
        "url": "",
        "url_method": ""
      },
      "receive_notify": {
        "url": "",
        "method": ""
      },
      "send_notify": {
        "url": "",
        "method": ""
      },
      "sms_enabled": "no",
      "mms_enabled": "no"
    },
    "voice_options": {
      "receive_notify": {
        "url": "",
        "method": ""
      },
      "send_notify": {
        "url": "https://requestb.in/1h8v9c01",
        "method": "JSON"
      }
    },
    "fax_options": {
      "receive_notify": {
        "url": "",
        "method": ""
      },
      "send_notify": {
        "url": "",
        "method": ""
      }
    }
  }
}

Configure the callback URL to notify when an outbound call is made. Each FoneNumber can be configured to use its own callback URL for handling send notifications.

HTTP Request

Method Route
POST /calls/send_notify

Body Parameters

Parameter Type Default Description
fonenumber string A FoneNumber associated with the account.
method string Allowed values are GET,POST, or JSON. See Notes for additional information.
url string Callback URL. See Notes for additional information.
url_username
optional
string Callback URL username.
url_username
optional
string Callback URL password.

Response Properties

Property Type Description
fonenumber object FoneNumber object.

Notes

url

This is a valid HTTP or HTTPS URL that will accept callback data when an outbound call is made from the FoneNumber specified in fonenumber.

method

One of three available methods must be specified for the callback execution.

Callback Data

Parameter Type Default Description
uid string Unique identifier for the call.
account_code string FoneStorm account code.
direction string Call direction (OUTBOUND)
status string Call status (BEGIN or END)
from string FoneNumber of sender.
to string Phone number of recipient.
type string Call type (VOICE)
disposition string Call disposition (ANSWERED, NO_ANSWER, BUSY, CANCEL, REJECTED, FAILED:XXX) if status is END
billable_seconds number Billable seconds for the call if status is END

Callback URLs using the GET method use token replacements to place callback data values in query string parameters. For example, the following partial query string maps each callback data value to parameters in the query string: recipient={{to}}&caller={{from}}&account={{account_code}}&id={{uid}}

Receive Notify

Example Request

# Configure FoneNumber 3215551111 to receive a callback with
# JSON payload data (application/json) to url https://requestb.in/1h8v9c01
# when a voice call is received.
curl --request POST
--url 'https://api.fonestorm.com/v2/calls/receive_notify'
--header 'Content-Type: application/json'
--header 'Accept: application/json'
--header 'token: key'
--data '{"fonenumber":"3215551111", "method":"JSON", "url":"https://requestb.in/1h8v9c01"}'
// Configure FoneNumber 3215551111 to receive a callback with
// JSON payload data (application/json) to url https://requestb.in/1h8v9c01
// when a voice call is received.
var FoneStormApi220 = require('fone_storm_api_220');
var apiInstance = new FoneStormApi220.CallsApi();
var fonenumber = "3215551111";
var method = "JSON";
var url = "https://requestb.in/1h8v9c01";
var opts = {};

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.postCallsReceiveNotify(fonenumber, method, url, opts, callback);
<?php
// Configure FoneNumber 3215551111 to receive a callback with
// JSON payload data (application/json) to url https://requestb.in/1h8v9c01
// when a voice call is received.
require_once(__DIR__ . '/vendor/autoload.php');

$api_instance = new Swagger\Client\Api\CallsApi();
$fonenumber = "3215551111";
$method = "method_example";
$url = "https://requestb.in/1h8v9c01";

try {
    $result = $api_instance->postCallsReceiveNotify($fonenumber, $method, $url);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling CallsApi->postCallsReceiveNotify: ', $e->getMessage(), PHP_EOL;
}
?>
# Configure FoneNumber 3215551111 to receive a callback with
# JSON payload data (application/json) to url https://requestb.in/1h8v9c01
# when a voice call is received.
from __future__ import print_function
import time
import swagger_client
from swagger_client.rest import ApiException
from pprint import pprint

# create an instance of the API class
api_instance = swagger_client.CallsApi()
fonenumber = '3215551111'
method = 'JSON'
url = 'https://requestb.in/1h8v9c01'

try:
    # Configure the callback URL to notify when a call is received.
    api_response = api_instance.post_calls_receive_notify(fonenumber, method, url)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling CallsApi->post_calls_receive_notify: %s\n" % e)

Example Response

{
  "fonenumber": {
    "fonenumber": "3215551111",
    "state": "FL",
    "rate_center": "ORLANDO",
    "is_active": "yes",
    "sms_options": {
      "receive": {
        "type": "",
        "email": "",
        "device": "",
        "forward": "",
        "url": "",
        "url_method": ""
      },
      "receive_notify": {
        "url": "",
        "method": ""
      },
      "send_notify": {
        "url": "",
        "method": ""
      },
      "sms_enabled": "no",
      "mms_enabled": "no"
    },
    "voice_options": {
      "receive_notify": {
        "url": "https://requestb.in/1h8v9c01",
        "method": "JSON"
      },
      "send_notify": {
        "url": "",
        "method": ""
      }
    },
    "fax_options": {
      "receive_notify": {
        "url": "",
        "method": ""
      },
      "send_notify": {
        "url": "",
        "method": ""
      }
    }
  }
}

Configure the callback URL to notify when a call is received. Each FoneNumber can be configured to use its own callback URL for handling receive notifications.

HTTP Request

Method Route
POST /calls/receive_notify

Body Parameters

Parameter Type Default Description
fonenumber string A FoneNumber associated with the account.
url string Callback URL. See Notes for additional information.
method string Allowed values are GET,POST, or JSON. See Notes for additional information.
url_username
optional
string Callback URL username.
url_username
optional
string Callback URL password.

Response Properties

Property Type Description
fonenumber object FoneNumber object.

Notes

url

This is a valid HTTP or HTTPS URL that will accept callback data when an inbound call is received to the FoneNumber specified in fonenumber.

method

One of three available methods must be specified for the callback execution.

Callback Data

Parameter Type Default Description
uid string Unique identifier for the call.
account_code string FoneStorm account code.
direction string Call direction (INBOUND)
status string Call status (BEGIN or END)
from string FoneNumber of sender.
to string Phone number of recipient.
type string Call type (VOICE)
disposition string Call disposition (ANSWERED, NO_ANSWER, BUSY, CANCEL, REJECTED, FAILED:XXX) if status is END
billable_seconds number Billable seconds for the call if status is END

Callback URLs using the GET method use token replacements to place callback data values in query string parameters. For example, the following partial query string maps each callback data value to parameters in the query string: recipient={{to}}&caller={{from}}&account={{account_code}}&id={{uid}}

Faxes

Send Fax

Example Request

curl --request POST 
--url 'https://api.fonestorm.com/v2/faxes'
--header 'Content-Type: application/json'
--header 'Accept: application/json' 
--header 'token: key' 
--data '{"fonenumber":"3215551081", "to":"3215551810", "message":"Your order has been confirmed. As requested, we've attached the PDF to this fax.", "url":"https://domain.com/invoices/e4a38358-5044-4f79-8bb8-518c02b38839.pdf"}'

Example Response

{
  "fax": {
    "id": "cca3a989-8942-462d-b7fa-878d47687d63"
  }
}

HTTP Request

Method Route
POST /faxes

Body Parameters

Parameter Type Default Description
fonenumber string FracTEL fonenumber to use for fax.
to string Phone number to fax.
message string Message to fax.
pdf
optional
string URL of a PDF file to send with fax.

Response Properties

Property Type Description
fax object Fax object.

Send Notify

Example Request

curl --request POST 
--url 'https://api.fonestorm.com/v2/faxes/send_notify'
--header 'Content-Type: application/json'
--header 'Accept: application/json' 
--header 'token: key' 
--data '{"fonenumber":"3215551111", "method":"JSON", "url":"https://requestb.in/1h8v9c01"}'

Example Response

{
  "fonenumber": {
    "fonenumber": "3215551111",
    "state": "FL",
    "rate_center": "ORLANDO",
    "is_active": "yes",
    "sms_options": {
      "receive": {
        "type": "",
        "email": "",
        "device": "",
        "forward": "",
        "url": "",
        "url_method": ""
      },
      "receive_notify": {
        "url": "",
        "method": ""
      },
      "send_notify": {
        "url": "",
        "method": ""
      },
      "sms_enabled": "no",
      "mms_enabled": "no"
    },
    "voice_options": {
      "receive_notify": {
        "url": "",
        "method": ""
      },
      "send_notify": {
        "url": "",
        "method": ""
      }
    },
    "fax_options": {
      "receive_notify": {
        "url": "",
        "method": ""
      },
      "send_notify": {
        "url": "https://requestb.in/1h8v9c01",
        "method": "JSON"
      }
    }
  }
}

Configure the callback URL to notify when an outbound fax is made. Each FoneNumber can be configured to use its own callback URL for handling send notifications.

HTTP Request

Method Route
POST /faxes/send_notify

Body Parameters

Parameter Type Default Description
fonenumber string A FoneNumber associated with the account.
url string Callback URL. See Notes for additional information.
method string Allowed values are GET,POST, or JSON. See Notes for additional information.
url_username
optional
string Callback URL username.
url_username
optional
string Callback URL password.

Response Properties

Property Type Description
fonenumber object FoneNumber object.

Notes

url

This is a valid HTTP or HTTPS URL that will accept callback data when an outbound fax is sent from the FoneNumber specified in fonenumber.

method

One of three available methods must be specified for the callback execution.

Callback Data

Parameter Type Default Description
uid string Unique identifier for the fax.
account_code string FoneStorm account code.
status string Fax status (SUCCESS or FAILED)
from string FoneNumber of sender.
to string Phone number of recipient.
timestamp string Time stamp.
file string Fax file URL.
type string Call type (VOICE)
attempts number Number of fax attempts.
pages number Number of total pages.
pages_transmitted number Number of transmitted pages.

Callback URLs using the GET method use token replacements to place callback data values in query string parameters. For example, the following partial query string maps each callback data value to parameters in the query string: recipient={{to}}&sender={{from}}&id={{uid}}

Receive Notify

Example Request

curl --request POST 
--url 'https://api.fonestorm.com/v2/faxes/receive_notify'
--header 'Content-Type: application/json'
--header 'Accept: application/json' 
--header 'token: key' 
--data '{"fonenumber":"3215551111", "method":"JSON", "url":"https://requestb.in/1h8v9c01"}'

Example Response

{
  "fonenumber": {
    "fonenumber": "3215551111",
    "state": "FL",
    "rate_center": "ORLANDO",
    "is_active": "yes",
    "sms_options": {
      "receive": {
        "type": "",
        "email": "",
        "device": "",
        "forward": "",
        "url": "",
        "url_method": ""
      },
      "receive_notify": {
        "url": "",
        "method": ""
      },
      "send_notify": {
        "url": "",
        "method": ""
      },
      "sms_enabled": "no",
      "mms_enabled": "no"
    },
    "voice_options": {
      "receive_notify": {
        "url": "",
        "method": ""
      },
      "send_notify": {
        "url": "",
        "method": ""
      }
    },
    "fax_options": {
      "receive_notify": {
        "url": "https://requestb.in/1h8v9c01",
        "method": "JSON"
      },
      "send_notify": {
        "url": "",
        "method": ""
      }
    }
  }
}

Configure the callback URL to notify when an inbound fax is received. Each FoneNumber can be configured to use its own callback URL for handling receive notifications.

HTTP Request

Method Route
POST /faxes/receive_notify

Body Parameters

Parameter Type Default Description
fonenumber string A FoneNumber associated with the account.
url string Callback URL. See Notes for additional information.
method string Allowed values are GET,POST, or JSON. See Notes for additional information.
url_username
optional
string Callback URL username.
url_username
optional
string Callback URL password.

Response Properties

Property Type Description
fonenumber object FoneNumber object.

Notes

url

This is a valid HTTP or HTTPS URL that will accept callback data when a fax is sent to the FoneNumber specified in fonenumber.

method

One of three available methods must be specified for the callback execution.

Callback Data

Parameter Type Default Description
uid string Unique identifier for the fax.
account_code string FoneStorm account code.
status string Fax status (SUCCESS or FAILED)
from string FoneNumber of sender.
to string Phone number of recipient.
timestamp string Time stamp.
file string Fax file URL.
type string Call type (VOICE)
attempts number Number of fax attempts.
pages number Number of total pages.
pages_transmitted number Number of transmitted pages.

Callback URLs using the GET method use token replacements to place callback data values in query string parameters. For example, the following partial query string maps each callback data value to parameters in the query string: recipient={{to}}&sender={{from}}&id={{uid}}

FoneNumbers

List All FoneNumbers

Example Request

# Get all FoneNumbers under account.
$ curl --request GET
--url 'https://api.fonestorm.com/v2/fonenumbers?filter=all'
--header 'Content-Type: application/json'
--header 'Accept: application/json'
--header 'token: key'
var FoneStormApi220 = require('fone_storm_api_220');
var apiInstance = new FracTelApi.FonenumbersApi();
var opts = {
  'filter': "all"
};

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.getFonenumbers(opts, callback);
<?php
require_once(__DIR__ . '/vendor/autoload.php');

$api_instance = new Swagger\Client\Api\FonenumbersApi();
$filter = "all";

try {
    $result = $api_instance->getFonenumbers($filter);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling FonenumbersApi->getFonenumbers: ', $e->getMessage(), PHP_EOL;
}
?>
from __future__ import print_function
import time
import swagger_client
from swagger_client.rest import ApiException
from pprint import pprint

# create an instance of the API class
api_instance = swagger_client.FonenumbersApi()
filter = 'all'

try:
    # Get all active FoneNumbers listed under the account.
    api_response = api_instance.get_fonenumbers(filter=filter)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling FonenumbersApi->get_fonenumbers: %s\n" % e)

Example Response

{
  "fonenumbers": [
    {
      "fonenumber": "3215551111",
      "state": "FL",
      "rate_center": "ORLANDO",
      "is_active": "yes",
      "sms_options": {
        "receive": {
          "type": "email",
          "email": "support@domain.com",
          "device": "987123543678",
          "forward": "3215553333",
          "url": "https://hookb.in/KlwpR3j5",
          "url_method": "JSON"
        },
        "receive_notify": {
          "url": "https://hookb.in/KNRzy7P3",
          "method": "JSON"
        },
        "send_notify": {
          "url": "https://hookb.in/vewOPNyB",
          "method": "JSON"
        },
        "sms_enabled": "yes",
        "mms_enabled": "yes"
      },
      "voice_options": {
        "receive_notify": {
          "url": "https://requestb.in/1j0140z1",
          "method": "JSON"
        },
        "send_notify": {
          "url": "https://requestb.in/1j0140z1",
          "method": "JSON"
        }
      },
      "fax_options": {
        "receive_notify": {
          "url": "https://requestb.in/1j0140z1",
          "method": "JSON"
        },
        "send_notify": {
          "url": "https://requestb.in/1j0140z1",
          "method": "JSON"
        }
      }
    }
  ]
}

Get all the active FoneNumbers listed under the account.

HTTP Request

Method Route
GET /fonenumbers

Query Parameters

Parameter Type Default Description
filter string fonenumbers Filter the response attributes. Allowed values are fonenumbers or all. See Notes for additional information.

Response Properties

Property Type Description
fonenumbers array Array of fonenumber objects.

Notes

filter

The default filter value is fonenumbers. For a more detailed response you may use all.

Order New FoneNumber

Example Request

# Order quick FoneNumber with a '321' area code.
$ curl --request POST
--url 'https://api.fonestorm.com/v2/fonenumbers'
--header 'Content-Type: application/json'
--header 'Accept: application/json'
--header 'token: key'
--data '{"area_code": "321" }'
// Order FoneNumber with a '321' area code.
var FoneStormApi220 = require('fone_storm_api_220');
var apiInstance = new FracTelApi.FonenumbersApi();
var areaCode = "321";

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.postFonenumbers(areaCode, callback);
<?php
// Order FoneNumber with a '321' area code.
require_once(__DIR__ . '/vendor/autoload.php');

$api_instance = new Swagger\Client\Api\FonenumbersApi();
$area_code = "321";

try {
    $result = $api_instance->postFonenumbers($area_code);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling FonenumbersApi->postFonenumbers: ', $e->getMessage(), PHP_EOL;
}
?>
# Order FoneNumber with a '321' area code.
from __future__ import print_function
import time
import swagger_client
from swagger_client.rest import ApiException
from pprint import pprint

# create an instance of the API class
api_instance = swagger_client.FonenumbersApi()
area_code = '321'

try:
    # Order quick FoneNumber for the account.
    api_response = api_instance.post_fonenumbers(area_code)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling FonenumbersApi->post_fonenumbers: %s\n" % e)

Example Response

{
  "fonenumber": {
    "fonenumber": "3215551111",
    "state": "FL",
    "rate_center": "ORLANDO",
    "is_active": "yes",
    "sms_options": {
      "receive": {
        "type": "",
        "email": "",
        "device": "",
        "forward": "",
        "url": "",
        "url_method": ""
      },
      "receive_notify": {
        "url": "",
        "method": ""
      },
      "send_notify": {
        "url": "",
        "method": ""
      },
      "sms_enabled": "no",
      "mms_enabled": "no"
    },
    "voice_options": {
      "receive_notify": {
        "url": "",
        "method": ""
      },
      "send_notify": {
        "url": "",
        "method": ""
      }
    },
    "fax_options": {
      "receive_notify": {
        "url": "",
        "method": ""
      },
      "send_notify": {
        "url": "",
        "method": ""
      }
    }
  }
}

Order a new FoneNumber for the account.

HTTP Request

Method Route
POST /fonenumbers

Body Parameters

Parameter Type Default Description
area_code string A valid 3-digit Area Code.

Response Properties

Property Type Description
fonenumber object FoneNumber object.

Get FoneNumber Details

Example Request

# Get details for FoneNumber '3215551111'
$ curl --request GET
--url 'https://api.fonestorm.com/v2/fonenumbers/3215551111'
--header 'Content-Type: application/json'
--header 'Accept: application/json'
--header 'token: key'
// Get details for FoneNumber '3215551111'
var FoneStormApi220 = require('fone_storm_api_220');
var apiInstance = new FracTelApi.FonenumbersApi();
var fonenumber = "3215551111";

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.getFonenumbersFonenumber(fonenumber, callback);
<?php
// Get details for FoneNumber '3215551111'
require_once(__DIR__ . '/vendor/autoload.php');

$api_instance = new Swagger\Client\Api\FonenumbersApi();
$fonenumber = "3215551111";

try {
    $result = $api_instance->getFonenumbersFonenumber($fonenumber);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling FonenumbersApi->getFonenumbersFonenumber: ', $e->getMessage(), PHP_EOL;
}
?>
# Get details for FoneNumber '3215551111'
from __future__ import print_function
import time
import swagger_client
from swagger_client.rest import ApiException
from pprint import pprint

# create an instance of the API class
api_instance = swagger_client.FonenumbersApi()
fonenumber = '3215551111'

try:
    # Get a single FoneNumber listed under the account.
    api_response = api_instance.get_fonenumbers_fonenumber(fonenumber)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling FonenumbersApi->get_fonenumbers_fonenumber: %s\n" % e)

Example Response

{
  "fonenumber": {
    "fonenumber": "3215551111",
    "state": "FL",
    "rate_center": "ORLANDO",
    "is_active": "yes",
    "sms_options": {
      "receive": {
        "type": "email",
        "email": "support@domain.com",
        "device": "987123543678",
        "forward": "3215553333",
        "url": "https://hookb.in/KlwpR3j5",
        "url_method": "JSON"
      },
      "receive_notify": {
        "url": "https://hookb.in/KNRzy7P3",
        "method": "JSON"
      },
      "send_notify": {
        "url": "https://hookb.in/vewOPNyB",
        "method": "JSON"
      },
      "sms_enabled": "yes",
      "mms_enabled": "yes"
    },
    "voice_options": {
      "receive_notify": {
        "url": "https://requestb.in/1j0140z1",
        "method": "JSON"
      },
      "send_notify": {
        "url": "https://requestb.in/1j0140z1",
        "method": "JSON"
      }
    },
    "fax_options": {
      "receive_notify": {
        "url": "https://requestb.in/1j0140z1",
        "method": "JSON"
      },
      "send_notify": {
        "url": "https://requestb.in/1j0140z1",
        "method": "JSON"
      }
    }
  }
}

Get information for a single FoneNumber listed under the account.

HTTP Request

Method Route
GET /fonenumbers/:fonenumber

Path Parameters

Parameter Type Default Description
fonenumber string A FoneNumber associated with the account.

Response Properties

Property Type Description
fonenumber object FoneNumber object.

Update FoneNumber

Example Request

# Set FoneNumber service type for '3215551111'
# to receive messages to email address 'support@domain.com'
$ curl --request PUT
--url 'https://api.fonestorm.com/v2/fonenumbers/3215551111'
--header 'Content-Type: application/json'
--header 'Accept: application/json'
--header 'token: key'
--data '{"type": "Email", "value": "support@domain.com"}'
// Set service for FoneNumber '3215551111'
// to receive messages to email address 'support@domain.com'
var FoneStormApi220 = require('fone_storm_api_220');
var apiInstance = new FracTelApi.FonenumbersApi();
var fonenumber = "3215551111";
var type = "Email";
var opts = {
  'value': "support@domain.com",
};

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.putFonenumbersFonenumber(fonenumber, type, opts, callback);
<?php
// Set service for FoneNumber '3215551111'
// to receive messages to email address 'support@domain.com'
require_once(__DIR__ . '/vendor/autoload.php');

$api_instance = new Swagger\Client\Api\FonenumbersApi();
$fonenumber = "3215551111";
$type = "Email";
$value = "support@domain.com";

try {
    $result = $api_instance->putFonenumbersFonenumber($fonenumber, $type, $value);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling FonenumbersApi->putFonenumbersFonenumber: ', $e->getMessage(), PHP_EOL;
}
?>
# Set service for FoneNumber '3215551111'
# to receive messages to email address 'support@domain.com'
from __future__ import print_function
import time
import swagger_client
from swagger_client.rest import ApiException
from pprint import pprint

# create an instance of the API class
api_instance = swagger_client.FonenumbersApi()
fonenumber = '3215551111'
type = 'Email'
value = 'support@domain.com'

try:
    # Configure the service type for an account FoneNumber.
    api_response = api_instance.put_fonenumbers_fonenumber(fonenumber, type, value=value, url_method=url_method, url_username=url_username, url_password=url_password)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling FonenumbersApi->put_fonenumbers_fonenumber: %s\n" % e)

Example Response

{
  "fonenumber": {
    "fonenumber": "3215551111",
    "state": "FL",
    "rate_center": "ORLANDO",
    "is_active": "yes",
    "sms_options": {
      "receive": {
        "type": "email",
        "email": "support@domain.com",
        "device": "987123543678",
        "forward": "3215553333",
        "url": "https://hookb.in/KlwpR3j5",
        "url_method": "JSON"
      },
      "receive_notify": {
        "url": "https://hookb.in/KNRzy7P3",
        "method": "JSON"
      },
      "send_notify": {
        "url": "https://hookb.in/vewOPNyB",
        "method": "JSON"
      },
      "sms_enabled": "yes",
      "mms_enabled": "yes"
    },
    "voice_options": {
      "receive_notify": {
        "url": "https://requestb.in/1j0140z1",
        "method": "JSON"
      },
      "send_notify": {
        "url": "https://requestb.in/1j0140z1",
        "method": "JSON"
      }
    },
    "fax_options": {
      "receive_notify": {
        "url": "https://requestb.in/1j0140z1",
        "method": "JSON"
      },
      "send_notify": {
        "url": "https://requestb.in/1j0140z1",
        "method": "JSON"
      }
    }
  }
}

Configure the service type for account FoneNumber.

HTTP Request

Method Route
PUT /fonenumbers/:fonenumber

Path Parameters

Parameter Type Default Description
fonenumber string A FoneNumber associated with the account.

Body Parameters

Parameter Type Default Description
type string Message routing type. Allowed values are None, Device, Email, URL, or Forward.
value string Message routing type value.
url_method
optional
string URL method. Allowed values are GET, POST, or JSON. See Notes for additional information.
url_username
optional
string URL username for HTTP Basic authentication scheme.
url_password
optional
string URL password for HTTP Basic authentication scheme.

Response Properties

Property Type Description
fonenumber object FoneNumber object.

Notes

url_method

When type is URL then url_method is required. The URL value is expected to be a valid HTTP or HTTPS URL that will accept data when a message is sent to the FoneNumber. One of three available methods must be specified for the execution.

Delete FoneNumber

Example Request

# Cancel FoneNumber '3215551111' and remove from account.
$ curl --request DELETE
--url 'https://api.fonestorm.com/v2/fonenumbers/3215551111'
--header 'Content-Type: application/json'
--header 'Accept: application/json'
--header 'token: key'
// Cancel FoneNumber '3215551111' and remove from account.
var FoneStormApi220 = require('fone_storm_api_220');
var apiInstance = new FracTelApi.FonenumbersApi();
var fonenumber = "3215551111";

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.deleteFonenumbersFonenumber(fonenumber, callback);
<?php
// Cancel FoneNumber '3215551111' and remove from account.
require_once(__DIR__ . '/vendor/autoload.php');

$api_instance = new Swagger\Client\Api\FonenumbersApi();
$fonenumber = "3215551111";

try {
    $result = $api_instance->deleteFonenumbersFonenumber($fonenumber);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling FonenumbersApi->deleteFonenumbersFonenumber: ', $e->getMessage(), PHP_EOL;
}
?>
# Cancel FoneNumber '3215551111' and remove from account.
from __future__ import print_function
import time
import swagger_client
from swagger_client.rest import ApiException
from pprint import pprint

# create an instance of the API class
api_instance = swagger_client.FonenumbersApi()
fonenumber = '3215551111'

try:
    # Remove FoneNumber from the account.
    api_response = api_instance.delete_fonenumbers_fonenumber(fonenumber)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling FonenumbersApi->delete_fonenumbers_fonenumber: %s\n" % e)

Example Response

{
  "fonenumber": {
    "fonenumber": "3215551111",
    "state": "FL",
    "rate_center": "ORLANDO",
    "is_active": "cancel",
    "sms_options": {
      "receive": {
        "type": "email",
        "email": "support@domain.com",
        "device": "987123543678",
        "forward": "3215553333",
        "url": "https://hookb.in/KlwpR3j5",
        "url_method": "JSON"
      },
      "receive_notify": {
        "url": "https://hookb.in/KNRzy7P3",
        "method": "JSON"
      },
      "send_notify": {
        "url": "https://hookb.in/vewOPNyB",
        "method": "JSON"
      },
      "sms_enabled": "yes",
      "mms_enabled": "yes"
    },
    "voice_options": {
      "receive_notify": {
        "url": "https://requestb.in/1j0140z1",
        "method": "JSON"
      },
      "send_notify": {
        "url": "https://requestb.in/1j0140z1",
        "method": "JSON"
      }
    },
    "fax_options": {
      "receive_notify": {
        "url": "https://requestb.in/1j0140z1",
        "method": "JSON"
      },
      "send_notify": {
        "url": "https://requestb.in/1j0140z1",
        "method": "JSON"
      }
    }
  }
}

Remove FoneNumber from account.

HTTP Request

Method Route
DELETE /fonenumbers/:fonenumber

Path Parameters

Parameter Type Default Description
fonenumber string A FoneNumber associated with the account.

Response Properties

Property Type Description
fonenumber object FoneNumber object.

Messages

Send

Example Request

# Send an MMS message "Hello World"
# that does not require confirmation
# from FoneNumber 3215551111
# to a recipent 3215552222
# containing an image https://www.fractel.net/wp-content/uploads/2014/03/FracTEL_Tag_Logo.png
# with a callback url https://hookb.in/vDkMOVB9
$ curl --request POST
--url 'https://api.fonestorm.com/v2/messages/send'
--header 'Content-Type: application/json'
--header 'Accept: application/json'
--header 'token: key'
--data '{"to":"3215552222", "fonenumber": "3215551111", "message": "Hello%20World", "media_url": "https://www.fractel.net/wp-content/uploads/2014/03/FracTEL_Tag_Logo.png", "confirmation_url": "https%3A%2F%2Fhookb.in%2FvDkMOVB9", "require_confirmation": false}'
// Send an MMS message "Hello World"
// that does not require confirmation
// from FoneNumber 3215551111
// to a recipent 3215552222
// containing an image https://www.fractel.net/wp-content/uploads/2014/03/FracTEL_Tag_Logo.png
// with a callback url https://hookb.in/vDkMOVB9
var FoneStormApi220 = require('fone_storm_api_220');
var apiInstance = new FoneStormApi220.MessagesApi();
var to = "3215552222";
var fonenumber = "3215551111";
var message = "Hello World";
var opts = {
  'mediaUrl': ["https://www.fractel.net/wp-content/uploads/2014/03/FracTEL_Tag_Logo.png"],
  'confirmationUrl': "https://hookb.in/vDkMOVB9",
  'requireConfirmation': false
};

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.postMessagesSend(to, fonenumber, message, opts, callback);
<?php
// Send an MMS message "Hello World"
// that does not require confirmation
// from FoneNumber 3215551111
// to a recipent 3215552222
// containing an image https://www.fractel.net/wp-content/uploads/2014/03/FracTEL_Tag_Logo.png
// with a callback url https://hookb.in/vDkMOVB9
require_once(__DIR__ . '/vendor/autoload.php');

$api_instance = new Swagger\Client\Api\MessagesApi();
$to = "3215552222";
$fonenumber = "3215551111";
$message = "Hello World";
$media_url = array("https://www.fractel.net/wp-content/uploads/2014/03/FracTEL_Tag_Logo.png");
$confirmation_url = "https://hookb.in/vDkMOVB9";
$confirmation_url_username = '';
$confirmation_url_password = '';
$require_confirmation = false;

try {
    $result = $api_instance->postMessagesSend($to, $fonenumber, $message, $media_url, $confirmation_url, $confirmation_url_username, $confirmation_url_password, $require_confirmation);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling MessagesApi->postMessagesSend: ', $e->getMessage(), PHP_EOL;
}
?>
# Send an MMS message "Hello World"
# that does not require confirmation
# from FoneNumber 3215551111
# to a recipent 3215552222
# containing an image https://www.fractel.net/wp-content/uploads/2014/03/FracTEL_Tag_Logo.png
# with a callback url https://hookb.in/vDkMOVB9
from __future__ import print_function
import time
import swagger_client
from swagger_client.rest import ApiException
from pprint import pprint

# create an instance of the API class
api_instance = swagger_client.MessagesApi()
to = '3215552222'
fonenumber = '3215551111'
message = 'Hello World'
media_url = ['https://www.fractel.net/wp-content/uploads/2014/03/FracTEL_Tag_Logo.png']
confirmation_url = 'https://hookb.in/vDkMOVB9'
require_confirmation = false

try:
    # Send an SMS or MMS message to a recipient.
    api_response = api_instance.post_messages_send(to, fonenumber, message, media_url=media_url, confirmation_url=confirmation_url, require_confirmation=require_confirmation)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MessagesApi->post_messages_send: %s\n" % e)

Example Response

{
  "message": {
    "id": "574330d1cdd7e1566b61b771ac72295f"
  }
}

Send an SMS or MMS message to a recipient.

HTTP Request

Method Route
POST /messages/send

Body Parameters

Parameter Type Default Description
to string The recipient’s 10 digit phone number.
fonenumber string A FoneNumber associated with the account.
message string Contents of the SMS or MMS.
media_url
optional
array[string] Valid HTTP or HTTPS URL(s) for media to send via MMS. See Notes for additional information.
confirmation_url
optional
string Valid HTTP or HTTPS URL that will accept callback data after the message is sent. See Notes for additional information.
require_confirmation
optional
string Only send message if confirmation is available. See Notes for additional information.

Response Properties

Property Type Description
message object Message object.

Notes

media_url

Binaries, as identified by media_url, have a size limit of 1.5MB.

Multiple entries for media_url, with a limit of 10 per message, are supported. If a single URL is being sent, it must be sent as a single-element array.

Supported MMS File Types

Extension File Type - Extension File Type - Extension File Type - Extension File Type
.gz application/gzip .flac audio/flac .jpg image/jpeg .avi video/avi
.js application/javascript .m4a audio/mp4 .pjpeg image/pjpeg .m4v video/mp4
.json application/json .m4b audio/mp4 .png image/png .mp4 video/mp4
.oga application/ogg .m4p audio/mp4 .svg image/svg+xml .m1v video/mpeg
.ogg application/ogg .m4r audio/mp4 .tif image/tiff .mpeg video/mpeg
.ogv application/ogg .m1a audio/mpeg .tiff image/tiff .mpg video/mpeg
.ogx application/ogg .m2a audio/mpeg .webp image/webp .mpv video/mpeg
.pdf application/pdf .mp1 audio/mpeg .ico image/x-icon .ogg video/ogg
.rtf application/rtf .mp2 audio/mpeg .cal text/calendar .ogm video/ogg
.smil application/smil .mp3 audio/mpeg .css text/css .ogv video/ogg
.bz2 application/x-bzip2 .mpa audio/mpeg .csv text/csv .ogx video/ogg
.gz application/x-gzip .oga audio/ogg .html text/html .spx video/ogg
.tar application/x-tar .wav audio/wav .js text/javascript .mov video/quicktime
.xml application/xml .webm audio/webm .txt text/plain .qt video/quicktime
.zip application/zip .bmp image/bmp .vcard text/vcard .webm video/webm
.3gp audio/3gpp .dib image/bmp .vcf text/vcard .flv video/x-flv
.3ga audio/amr .gif image/gif .wap text/vnd.wap.wml .wmv video/x-ms-wmv
.amr audio/amr .jpeg image/jpeg .xml text/xml

confirmation_url

Message sending confirmation callback URLs receive JSON data via a POST request (see below for a description of the data package) but can also use token replacements to receive callback data values in query string parameters. For example, the following partial query string maps each callback data value to parameters in the query string: recipient={{to}}&sender={{from}}&message={{msg}}&code={{dc}}&state={{ds}}&id={{uid}}

Parameter Type Default Description
to string Phone number of recipient.
from string FoneNumber of sender.
message string Contents of the message.
deliverystate string Delivery state of the message. Potential values are waiting, delivered or not-delivered.
deliverycode int Delivery code of the message. Potential values are:
  • 000 - Message delivered to carrier
  • 100 - Message not delivered to carrier
  • 187 - Statistical spam detected
  • 188 - Keyword spam detected
  • 189 - Spam detected
  • 482 - Loop detected
  • 600 - Destination carrier could not accept messages
  • 610 - Message submission failed
  • 620 - Destination application error
  • 630 - Message not acknowledged
  • 720 - Invalid destination number
  • 740 - Invalid source number
  • 999 - Unknown error
uid string Unique identifier for the message.

require_confirmation

If this is set to false, and a message cannot be delivered with a confirmation option, the API will send the message anyway. This is the default behavior if this parameter is omitted.

If this is set to true, and a message cannot be delivered with a confirmation option, the API will return an error and the message will NOT be sent.

Send Notify

Example Request

# Configure FoneNumber 3215551111 to receive a callback with
# POST data (application/x-www-form-urlencoded) to url https://hookb.in/vDkMOVB9
# when a message is sent.
curl --request POST
--url 'https://api.fonestorm.com/v2/messages/send_notify'
--header 'Content-Type: application/json'
--header 'Accept: application/json'
--header 'token: key'
--data '{"fonenumber":"3215551111", "method":"POST", "url": "https%3A%2F%2Fhookb.in%2FvDkMOVB9" }'
// Configure FoneNumber 3215551111 to receive a callback with
// POST data (application/x-www-form-urlencoded) to url https://hookb.in/vDkMOVB9
// when a message is sent.
var FoneStormApi220 = require('fone_storm_api_220');
var apiInstance = new FoneStormApi220.MessagesApi();
var fonenumber = "3215551111";
var method = "POST";
var url = "https://hookb.in/vDkMOVB9";
var opts = {};

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.postMessagesSendNotify(fonenumber, method, url, opts, callback);
<?php
// Configure FoneNumber 3215551111 to receive a callback with
// POST data (application/x-www-form-urlencoded) to url https://hookb.in/vDkMOVB9
// when a message is sent.
require_once(__DIR__ . '/vendor/autoload.php');

$api_instance = new Swagger\Client\Api\MessagesApi();
$fonenumber = "3215551111";
$method = "POST";
$url = "https://hookb.in/vDkMOVB9";

try {
    $result = $api_instance->postMessagesSendNotify($fonenumber, $method, $url);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling MessagesApi->postMessagesSendNotify: ', $e->getMessage(), PHP_EOL;
}
?>
# Configure FoneNumber 3215551111 to receive a callback with
# POST data (application/x-www-form-urlencoded) to url https://hookb.in/vDkMOVB9
# when a message is sent.
from __future__ import print_function
import time
import swagger_client
from swagger_client.rest import ApiException
from pprint import pprint

# create an instance of the API class
api_instance = swagger_client.MessagesApi()
fonenumber = '3215551111'
method = 'POST'
url = 'https://hookb.in/vDkMOVB9'

try:
    # Configure the callback URL to notify when a message is sent.
    api_response = api_instance.post_messages_send_notify(fonenumber, method, url)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MessagesApi->post_messages_send_notify: %s\n" % e)

Example Response

{
  "fonenumber": {
    "fonenumber": "3215551111",
    "state": "FL",
    "rate_center": "ORLANDO",
    "is_active": "yes",
    "sms_options": {
      "receive": {
        "type": "",
        "email": "",
        "device": "",
        "forward": "",
        "url": "",
        "url_method": ""
      },
      "receive_notify": {
        "url": "",
        "method": ""
      },
      "send_notify": {
        "url": "https://hookb.in/vDkMOVB9",
        "method": "POST"
      },
      "sms_enabled": "no",
      "mms_enabled": "no"
    },
    "voice_options": {
      "receive_notify": {
        "url": "",
        "method": ""
      },
      "send_notify": {
        "url": "",
        "method": ""
      }
    },
    "fax_options": {
      "receive_notify": {
        "url": "",
        "method": ""
      },
      "send_notify": {
        "url": "",
        "method": ""
      }
    }
  }
}

Configure the callback URL to notify when a message is sent. Each FoneNumber can be configured to use its own callback URL for handling send notifications.

HTTP Request

Method Route
POST /messages/send_notify

Body Parameters

Parameter Type Default Description
fonenumber string A FoneNumber associated with the account.
url string Callback URL. See Notes for additional information.
method string Allowed values are GET,POST, or JSON. See Notes for additional information.

Response Properties

Property Type Description
fonenumber object FoneNumber object.

Notes

url

This is a valid HTTP or HTTPS URL that will accept callback data when a message is sent from the FoneNumber specified in from.

method

One of three available methods must be specified for the callback execution.

Callback Data

Parameter Type Default Description
to string Phone number of recipient.
from string FoneNumber of sender.
message string Contents of the message.
uid string Unique identifier for the message.

Callback URLs using the GET method use token replacements to place callback data values in query string parameters. For example, the following partial query string maps each callback data value to parameters in the query string: recipient={{to}}&sender={{from}}&message={{msg}}&id={{uid}}

Receive

Example Request

# Deliver all messages received by FoneNumber 3215551111
# to an email address email@domain.
$ curl --request POST
--url 'https://api.fonestorm.com/v2/messages/receive'
--header 'Content-Type: application/json'
--header 'Accept: application/json'
--header 'token: key'
--data '{"fonenumber": "3215551111", "type": "Email", "value": "email@domain.com"}'
// Deliver all messages received by FoneNumber 3215551111
// to an email address email@domain.
var FoneStormApi220 = require('fone_storm_api_220');
var apiInstance = new FoneStormApi220.MessagesApi();
var fonenumber = "3215551111";
var type = "Email";
var opts = {
  'value': "email@domain.com"
};

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.postMessagesReceive(fonenumber, type, opts, callback);
<?php
// Deliver all messages received by FoneNumber 3215551111
// to an email address email@domain.
require_once(__DIR__ . '/vendor/autoload.php');

$api_instance = new Swagger\Client\Api\MessagesApi();
$fonenumber = "3215551111";
$type = "Email";
$value = "email@domain.com";

try {
    $result = $api_instance->postMessagesReceive($fonenumber, $type, $value);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling MessagesApi->postMessagesReceive: ', $e->getMessage(), PHP_EOL;
}
?>
# Deliver all messages received by FoneNumber 3215551111
# to an email address email@domain.
from __future__ import print_function
import time
import swagger_client
from swagger_client.rest import ApiException
from pprint import pprint

# create an instance of the API class
api_instance = swagger_client.MessagesApi()
fonenumber = '3215551111'
type = 'Email'
value = 'email@domain.com'

try:
    # Configure the delivery service type used as the destination for received messages.
    api_response = api_instance.post_messages_receive(fonenumber, type, value=value, url_method=url_method, url_username=url_username, url_password=url_password)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MessagesApi->post_messages_receive: %s\n" % e)

Example Response

{
  "fonenumber": {
    "fonenumber": "3215551111",
    "state": "FL",
    "rate_center": "ORLANDO",
    "is_active": "yes",
    "sms_options": {
      "receive": {
        "type": "email",
        "email": "email@domain.com",
        "device": "",
        "forward": "",
        "url": "",
        "url_method": ""
      },
      "receive_notify": {
        "url": "",
        "method": ""
      },
      "send_notify": {
        "url": "",
        "method": ""
      },
      "sms_enabled": "no",
      "mms_enabled": "no"
    },
    "voice_options": {
      "receive_notify": {
        "url": "",
        "method": ""
      },
      "send_notify": {
        "url": "",
        "method": ""
      }
    },
    "fax_options": {
      "receive_notify": {
        "url": "",
        "method": ""
      },
      "send_notify": {
        "url": "",
        "method": ""
      }
    }
  }
}

Configure the delivery service type used as the destination for received messages.

HTTP Request

Method Route
POST /messages/receive

Body Parameters

Parameter Type Default Description
fonenumber string A FoneNumber associated with the account.
type string Message service routing type. Allowed values are Device, Email, URL, Forward, or None. See Notes for additional information.
value string Value of the chosen message routing type. Allows for a Device ID, Email Address, URL, or Phone Number depending on the specified type. See Notes for additional information.

Response Properties

Property Type Description
fonenumber object FoneNumber object.

Notes

type

Incoming messages can be routed to one of several destination options: a configured and registered Device (e.g. SIP handset, Fractelfone mobile app, or WebRTC endpoint), a valid Email address, a callback URL, or Forward to another telephone number. There is also the option to set the destination to None, in which case messages are deleted upon receipt without any delivery. Use the type parameter to specify the type of destination.

value

The value parameter contains the corresponding setting for the destination.

Type Value Example
Device The ID for the destination device 987123543678
Email An email address bingo@stokes.com
URL A callback URL https://api.yourserver.com/handler.php?msg={{msg}}
Forward A forwarding phone number 3215551111
None None

Callback Data

Parameter Type Default Description
to string FoneNumber of recipient.
from string Phone number of sender.
message string Contents of the message.
uid string Unique identifier for the message.

Callback URLs use the POST method and use token replacements to place callback data values in query string parameters. For example, the following partial query string maps each callback data value to parameters in the query string: recipient={{to}}&sender={{from}}&message={{msg}}&id={{uid}}

Receive Notify

Example Request

# Configure FoneNumber 3215551111 to receive a callback with
# JSON payload data (application/json) to url https://hookb.in/vDkMOVB9
# when a message is received.
$ curl --request POST
--url 'https://api.fonestorm.com/v2/messages/receive_notify'
--header 'Content-Type: application/json'
--header 'Accept: application/json'
--header 'token: key'
--data '{"fonenumber": "3215551111", "method": "JSON", "url": "https%3A%2F%2Fhookb.in%2FvDkMOVB9"}'
// Configure FoneNumber 3215551111 to receive a callback with
// JSON payload data (application/json) to url https://hookb.in/vDkMOVB9
// when a message is received.
var FoneStormApi220 = require('fone_storm_api_220');
var apiInstance = new FoneStormApi220.MessagesApi();
var fonenumber = "3215551111";
var method = "JSON";
var url = "https://hookb.in/vDkMOVB9";
var opts = {};

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.postMessagesReceiveNotify(fonenumber, method, url, opts, callback);
<?php
// Configure FoneNumber 3215551111 to receive a callback with
// JSON payload data (application/json) to url https://hookb.in/vDkMOVB9
// when a message is received.
require_once(__DIR__ . '/vendor/autoload.php');

$api_instance = new Swagger\Client\Api\MessagesApi();
$fonenumber = "3215551111";
$method = "JSON";
$url = "https://hookb.in/vDkMOVB9";

try {
    $result = $api_instance->postMessagesReceiveNotify($fonenumber, $method, $url);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling MessagesApi->postMessagesReceiveNotify: ', $e->getMessage(), PHP_EOL;
}
?>
# Configure FoneNumber 3215551111 to receive a callback with
# JSON payload data (application/json) to url https://hookb.in/vDkMOVB9
# when a message is received.
from __future__ import print_function
import time
import swagger_client
from swagger_client.rest import ApiException
from pprint import pprint

# create an instance of the API class
api_instance = swagger_client.MessagesApi()
fonenumber = '3215551111'
method = 'JSON'
url = 'https://hookb.in/vDkMOVB9'

try:
    # Configure the callback URL to notify when a message is received.
    api_response = api_instance.post_messages_receive_notify(fonenumber, method, url)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MessagesApi->post_messages_receive_notify: %s\n" % e)

Example Response

{
  "fonenumber": {
    "fonenumber": "3215551111",
    "state": "FL",
    "rate_center": "ORLANDO",
    "is_active": "yes",
    "sms_options": {
      "receive": {
        "type": "",
        "email": "",
        "device": "",
        "forward": "",
        "url": "",
        "url_method": ""
      },
      "receive_notify": {
        "url": "https://hookb.in/vDkMOVB9",
        "method": "JSON"
      },
      "send_notify": {
        "url": "",
        "method": ""
      },
      "sms_enabled": "no",
      "mms_enabled": "no"
    },
    "voice_options": {
      "receive_notify": {
        "url": "",
        "method": ""
      },
      "send_notify": {
        "url": "",
        "method": ""
      }
    },
    "fax_options": {
      "receive_notify": {
        "url": "",
        "method": ""
      },
      "send_notify": {
        "url": "",
        "method": ""
      }
    }
  }
}

Configure the callback URL to notify when a message is received. Each FoneNumber can be configured to use its own callback URL for handling receive notifications.

HTTP Request

Method Route
POST /messages/receive_notify

Body Parameters

Parameter Type Default Description
fonenumber string A FoneNumber associated with the account.
url string Callback URL. See Notes for additional information.
method string Allowed values are GET,POST, or JSON. See Notes for additional information.

Response Properties

Property Type Description
fonenumber object FoneNumber object.

Notes

url

This is a valid HTTP or HTTPS URL that will accept callback data when a message is sent to the FoneNumber specified in fonenumber.

method

One of three available methods must be specified for the callback execution.

Callback Data

Parameter Type Default Description
to string FoneNumber of recipient.
from string Phone number of sender.
message string Contents of the message.
uid string Unique identifier for the message.

Callback URLs using the GET method use token replacements to place callback data values in query string parameters. For example, the following partial query string maps each callback data value to parameters in the query string: recipient={{to}}&sender={{from}}&message={{msg}}&id={{uid}}

Errors

FoneStorm uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided and codes in the 5xx range indicate an error with our servers.

Client Errors

FoneStorm API uses the following HTTP status codes for client errors:

Code Error Description
400 Bad Request The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
401 Unauthorized The request has not been applied because it lacks valid authentication credentials for the target resource.
402 Payment Required The target resource requires some form of digital cash or micropayment scheme.
403 Forbidden The server understood the request but refuses to authorize it.
404 Not Found The origin server did not find a current representation for the target resource or is not willing to disclose that one exists.
405 Method Not Allowed The method received in the request-line is known by the origin server but not supported by the target resource.
406 Not Acceptable The target resource does not have a current representation that would be acceptable to the user agent, according to the proactive negotiation header fields received in the request, and the server is unwilling to supply a default representation.
407 Proxy Authentication Required Similar to 401 Unauthorized, but it indicates that the client needs to authenticate itself in order to use a proxy.
408 Request Time-Out The server did not receive a complete request message within the time that it was prepared to wait.
409 Conflict The request could not be completed due to a conflict with the current state of the target resource. This code is used in situations where the user might be able to resolve the conflict and resubmit the request.
410 Gone The target resource is no longer available at the origin server and that this condition is likely to be permanent.
411 Length Required The server refuses to accept the request without a defined Content-Length.
412 Precondition Failed One or more conditions given in the request header fields evaluated to false when tested on the server.
413 Request Entity Too Large The server is refusing to process a request because the request payload is larger than the server is willing or able to process.
414 Request-URI Too Large The server is refusing to service the request because the request-target is longer than the server is willing to interpret.
415 Unsupported Media Type The origin server is refusing to service the request because the payload is in a format not supported by this method on the target resource.
416 Requested Range Not Satisfiable None of the ranges in the request’s Range header field overlap the current extent of the selected resource or that the set of ranges requested has been rejected due to invalid ranges or an excessive request of small or overlapping ranges.
417 Expectation Failed The expectation given in the request’s Expect header field could not be met by at least one of the inbound servers.
422 Unprocessable Entity The server understands the content type of the request entity and the syntax of the request entity is correct, but was unable to process the contained instructions.
423 Locked The source or destination resource of a method is locked.
428 Precondition Required The origin server requires the request to be conditional.
429 Too Many Requests The user has sent too many requests in a given amount of time (“rate limiting”).
451 Unavailable For Legal Reasons The server is denying access to the resource as a consequence of a legal demand.

Server Errors

FoneStorm API uses the following HTTP status codes for server errors:

Code Error Description
500 Internal Server Error The server encountered an unexpected condition that prevented it from fulfilling the request.
501 Not Implemented The server does not support the functionality required to fulfill the request.
502 Bad Gateway The server, while acting as a gateway or proxy, received an invalid response from an inbound server it accessed while attempting to fulfill the request.
503 Service Unavailable The server is currently unable to handle the request due to a temporary overload or scheduled maintenance, which will likely be alleviated after some delay.
504 Gateway Time-Out The server, while acting as a gateway or proxy, did not receive a timely response from an upstream server it needed to access in order to complete the request.