×

To begin using a new ExoPhone, make an HTTP POST request to:

POST

https://<your_api_key>:<your_api_token><subdomain>/v2_beta/Accounts/<your_sid>/IncomingPhoneNumbers

  • Replace <your_api_key> and <your_api_token> with the API key and token created by you.
  • Replace <your_sid> with your “Account sid”
  • Replace <subdomain> with the region of your account
    1. <subdomain> of Singapore cluster is @api.exotel.com
    2. <subdomain> of Mumbai cluster is @api.in.exotel.com

<your_api_key> , <your_api_token> and <your_sid> are available in the API settings page of your Exotel Dashboard

The following are the POST parameters:

Parameter Name

Mandatory/Optional

Value

PhoneNumber

Mandatory

The ExoPhone that you wish to get.

VoiceUrl

Optional

The VoiceURL to be associated to this number. The URL is of the form: http://my.exotel.com/{your_sid}/exoml/start_voice/{app_id} where app_id is the identifier of the flow (or applet) that you want to connect to once the From number picks up the call. You can get the app_id from your Exotel Dashboard.

SMSUrl

Optional

The SMSUrl to be associated to this number. The URL is of the form: http://my.exotel.com/{your_sid}/exoml/start_sms/{app_id} where app_id is the identifier of the flow (or applet) that you want to connect to once an incoming SMS is received.

FriendlyName

Optional

A friendly name that can be used to identify this number easily.

 
curl -X POST https://<your_api_key>:<your_api_token><subdomain>/v2_beta/Accounts/<your_sid>/IncomingPhoneNumbers \
  -d "PhoneNumber=XXXXX30240"
    
var request = require('request');
var dataString = 'PhoneNumber=XXXXX30240';
var options = {
    url: 'https://<your_api_key>:<your_api_token><subdomain>/v2_beta/Accounts/<your_sid>/IncomingPhoneNumbers',
    method: 'POST',
    body: dataString
};
function callback(error, response, body) {
    if (!error && response.statusCode == 200) {
        console.log(body);
    }
}
request(options, callback);
    
<?php
include('vendor/rmccue/requests/library/Requests.php');
Requests::register_autoloader();
$headers = array();
$data = array(
    'PhoneNumber' => 'XXXXX30240'
);
$response = Requests::post('https://<your_api_key>:<your_api_token><subdomain>/v2_beta/Accounts/<your_sid>/IncomingPhoneNumbers', $headers, $data);
    
import requests
data = {
  'PhoneNumber': 'XXXXX30240'
}
requests.post('https://<your_api_key>:<your_api_token><subdomain>/v2_beta/Accounts/<your_sid>/IncomingPhoneNumbers', data=data)
    
require 'net/http'
require 'uri'
uri = URI.parse("https://<your_api_key>:<your_api_token><subdomain>/v2_beta/Accounts/<your_sid>/IncomingPhoneNumbers")
request = Net::HTTP::Post.new(uri)
request.set_form_data(
  "PhoneNumber" => "XXXXX30240",
)
req_options = {
  use_ssl: uri.scheme == "https",
}
response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
# response.code
# response.body

HTTP Response:

  • On success, the HTTP response status code will be 200
  • The sid is the unique identifier of the number
  • the HTTP body will contain an JSON similar to the one below:
  • Example Response
{
  "sid": "9eeafc8ab479a386dc95f854f9d7cd8a",
  "date_created": "2016-11-09 13:48:12",
  "date_updated": "2017-03-30 14:19:02",
  "account_sid": "Exotel",
  "friendly_name": "XXXXX30240",
  "phone_number": "+91XXXX30240",
  "capabilities": {
      "voice": true,
      "sms": true
  },
  "country": "IN",
  "region": "WB",
  "one_time_price": "0.000000",
  "rental_price": "499.000000",
  "incoming_rate": "0.000000",
  "incoming_pulse": "60",
  "currency": "INR",
  "number_type": "Landline",
  "vanity_number": false,
  "voice_url": "https://my.exotel.in/Exotel/exoml/start_voice/12XX48",
  "sms_url": "https://my.exotel.in/Exotel/exoml/start_sms/22XX39",
  "uri": "/v2_beta/Accounts/Exotel/IncomingPhoneNumbers/9eeafc8ab479a386dc95f854f9d7cd8a"
}

Description of IncomingPhoneNumbers Parameters:

Parameter Name

Type & Value

sid

string; an alpha-numeric unique identifier of the number

date_created

Time in format YYYY-MM-DD HH:mm:ss; Date and time at which the number was purchases

date_updated

Time in format YYYY-MM-DD HH:mm:ss; Date and time at which the details of the number was last updated

account_sid

Exotel account SID

phone_number

The phone number that was purchased

friendly_name

A freindly name that can be used to identify the number

capabilities

These are the capabilities that are supported on this number:

  • voice - Boolean that indicates if incoming voice calls are supported on the number
  • sms - Boolean that indicates if incoming SMS is supported on the number

country

ISO Country Code to which this number belongs to

region

The telecom circle this number belongs to

one_time_price

One time cost incurred while purchasing this number

rental_price

Double; Recurring monthly rental associated with this number

incoming_rate

Double; The per pulse cost for incoming calls

incoming_pulse

Double; The duration of one pulse in seconds

currency

Double; The currency in which this number is billed

number_type

Double; The type of the number

vanity_number

Boolean; Indicates if this number is a vanity number

voice_url

string; The Url to the flow to which incoming calls are connected to

sms_url

string; The Url to the flow to which incoming SMS are connected to

uri

string; The URI is the path of the ExoPhone SID.