×

To get the details of a specific ExoPhone in your account including connectivity information, make an HTTP GET request to:

GET

https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/incoming-phone-numbers/<exophone_sid>

  • 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

curl -X GET https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/incoming-phone-numbers/<exophone_sid>
var request = require('request');
var options = {
    url: 'https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/incoming-phone-numbers/<exophone_sid>'
};
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();
$response = Requests::get('https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/incoming-phone-numbers/<exophone_sid>', $headers);
    
import requests
requests.get('https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/incoming-phone-numbers/<exophone_sid>')
    
require 'net/http'
require 'uri'
uri = URI.parse("https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/incoming-phone-numbers/<exophone_sid>")
response = Net::HTTP.get_response(uri)
# 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
{
  "request_id": "0f403dff8d854ca08c570a94717aa7d9",
  "method": "GET",
  "http_code": 200,
  "metadata": {
    "page_size": 1,
    "page": 0
  },
  "response": [
    {
      "code": 200,
      "error_data": null,
      "status": "success",
      "data": {
        "sid": "01139585476",
        "date_created": "2018-08-22T12:22:49Z",
        "date_updated": "2018-08-24T11:25:49Z",
        "friendly_name": "01139585476",
        "account_sid": "Exotel",
        "phone_number": "+911139585476",
        "capabilities": {
          "voice": true
        },
        "country": "IN",
        "region": "DL",
        "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.com/Exotel/exoml/start_voice/XXX",
        "sms_url": "https://my.exotel.com/Exotel/exoml/start_sms/XXX",
        "uri": "/v2/accounts/Exotel/incoming-phone-numbers/01139585476",
        "connectivity": {
          "incoming_call": {
            "status": "active",
            "last_check_time": "2018-08-24T11:25:49Z",
            "alternate_exophone": null
          },
          "outgoing_call": {
            "status": "active",
            "last_check_time": "2018-08-24T11:25:49Z",
            "alternate_exophone": null
          }
        }
      }
    }
  ]
}

Description of Parameters:

Parameter Name

Description

request_id

Random string to uniquely identify the request

method

HTTP request method (GET, POST, PUT, DELETE)

http_code

HTTP response code for your request like 200, 404, 429, 500 etc.

metadata

To provide metadata about the response. In case of GET for pagination (bulk), it'll contain:

  • page_size - total number of items in a page
  • page - denotes page number

response

JSON array representing the response and contains below parameters:

  • code - response code of the block in the response array, can be different from the overall http code, like in case of partial success (207)
  • error_data - To be populated in case of errors like below
"error_data": {
  "code": 1000,
  "description": "Not Found",
  "message": "Not Found"
}

In case of no errors, it’ll be null.

  • status - success or failure, depicting the status of the block in the response array
  • data - This will contain the data part of the block of the response array depending on the API, below table describes what will be populated in case of GET IPN. Please note, this field can be null also in case of failures like 404.

sid

String; An alpha-numeric unique identifier of the ExoPhone. This can be different than the ExoPhone itself.

date_created

Time in format: RFC 3339; Date and time at which the ExoPhone was added to the account

date_updated

Time in format: RFC 3339; Date and time at which the details of the ExoPhone was last updated

account_sid

Exotel account SID

phone_number

The phone number value of the ExoPhone in E.164 format like +911139585476

friendly_name

A freindly name that can be used to identify the ExoPhone

capabilities

These are the capabilities that are supported on this ExoPhone:

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

country

ISO Country Code to which this ExoPhone belongs to

region

The telecom circle this ExoPhone belongs to. Refer here for list of possible telecom circles.

one_time_price

One time cost incurred while adding this ExoPhone to your account

rental_price

Double; Recurring monthly rental associated with this ExoPhone

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 ExoPhone is billed

number_type

Double; The type of the ExoPhone

vanity_number

Boolean; Indicates if this ExoPhone 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 Url to the flow to which incoming calls are connected to

connectivity

JSON block representing connectivity information about the ExoPhone. It contains incoming_call, outgoing_call blocks which represent connectivity information for incoming call and outgoing call respectively.

Description of 'connectivity' parameters:

Parameter Name

Description

status

It represents the connectivity status for that functionality (incoming call or outgoing call). Possible values are

  • active: ExoPhone is healthy as per our monitoring system
  • major_outage: ExoPhone is inactive and calls are not connecting as per our monitoring system
  • partial_network_outage: ExoPhone is working partially and is down from/towards one or more operator connectivities. This would be populated once operator level connectivity monitoring information is exposed (yet to be released)

last_check_time

Format: RFC 3339; timestamp representing when this number was checked last for connectivity

alternate_exophone

If available, this will provide alternate ExoPhones in JSON array format which can be used if the given ExoPhone is down. If there are no alternate ExoPhones available it will be populated as null