This API provides the following metadata about a phone number:

  • Telecom Circle
  • Telecom Circle Name
  • Number Type
  • Whether the number belongs to DND or not

To get the above information you need to make a HTTP GET request to

GET

https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Numbers/~number~

  • 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 https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Numbers/XXXXX30240 
      
var request = require('request');

var options = {
    url: 'https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Numbers/XXXXX30240'
};

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>/v1/Accounts/<your_sid>/Numbers/XXXXX30240', $headers);
import requests

requests.get('https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Numbers/XXXXX30240')
require 'net/http'
require 'uri'

uri = URI.parse("https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Numbers/XXXXX30240")
response = Net::HTTP.get_response(uri)

# response.code
# response.body

HTTP Response:

  • On success, the HTTP response status code will be 200
  • the HTTP body will contain an XML similar to the one below
{
  "Numbers": {
    "PhoneNumber": "0XXXXX30240",
    "Circle": "GJ",
    "CircleName": "Gujarat Telecom Circle (includes Daman & Diu, Dadra & Nagar Haveli)",
    "Type": "Mobile",
    "Operator": "R",
    "OperatorName": "Reliance",
    "DND": "Yes"
  }
}
<?xml version="1.0" encoding="UTF-8"?>
<TwilioResponse>
 <Numbers>
  <PhoneNumber>0XXXXX30240</PhoneNumber>
  <Circle>GJ</Circle>
  <CircleName>Gujarat Telecom Circle (includes Daman &amp; Diu, Dadra &amp; Nagar Haveli)</CircleName>
  <Type>Mobile</Type>
  <Operator>R</Operator>
  <OperatorName>Reliance</OperatorName>
  <DND>Yes</DND>
 </Numbers>
</TwilioResponse>

Description of parameters mentioned in the above response:

Parameter Name Type & Value
PhoneNumber string; Reformatted phone number
Circle Two character telecom circle code. Refer below table for more details
CircleName Human readable string of the Circle code. Ex: Haryana Telecom Circle (excludes Faridabad, Gurgaon & Panchkula)
Type 'Mobile' or 'Landline'
Operator Single or two character telecom operator code. Refer below table for more details
OperatorName Telecom operator to which the number belongs
DND
  • Yes
  • No
  • Unavailable

Description of all the telecom circles in India:

Circle Name Value
AP Andhra Pradesh Telecom Circle
AS Assam Telecom Circle
BR Bihar & Jharkhand Telecom Circle
CH Chennai Metro Telecom Circle (includes Chennai, MEPZ & Mahabalipuram)
DL Delhi Metro Telecom Circle (includes NCR, Faridabad, Ghaziabad, Gurgaon & Noida)
GJ Gujarat Telecom Circle (includes Daman & Diu, Dadra & Nagar Haveli)
HP Himachal Pradesh Telecom Circle
HR Haryana Telecom Circle (excludes Faridabad, Gurgaon & Panchkula)
JK Jammu & Kashmir Telecom Circle
KL Kerala Telecom Circle (includes Lakshadeep)
KA Karnataka Telecom Circle
KO Kolkata Metro Telecom Circle (includes parts of Haora, Hooghly, North & South 24 Parganas and Nadia Districts)
MH Maharashtra Telecom Circle (includes Goa but excludes Mumbai, Navi Mumbai & Kalyan)
MP Madhya Pradesh & Chhattisgarh Telecom Circle
MU Mumbai Metro Telecom Circle (includes Navi Mumbai & Kalyan)
NE North East India Telecom Circle (includes Arunachal Pradesh, Meghalaya, Mizoram, Nagaland, Manipur & Tripura)
OR Orissa Telecom Circle
PB Punjab Telecom Circle (includes Chandigarh & Panchkula)
RJ Rajasthan Telecom Circle
TN Tamil Nadu Telecom Circle (excludes CH Chennai, MEPZ, Mahabalipuram & Minjur and includes Pondicherry except Yanam & Mahe)
UE Uttar Pradesh (East) Telecom Circle
UW Uttar Pradesh (West) & Uttarakhand Telecom Circle (excludes Ghaziabad & Noida)
WB West Bengal Telecom Circle (includes Andaman & Nicobar,Sikkim excludes Calcutta Telecom District)
AN Andaman & Nicobar
BY Mumbai Metro Telecom Circle (includes Navi Mumbai & Kalyan)
HA Haryana Telecom Circle (excludes Faridabad, Gurgaon & Panchkula)
ND Delhi Metro Telecom Circle (includes NCR, Faridabad, Ghaziabad, Gurgaon & Noida)
UPE Uttar Pradesh (East) Telecom Circle
UPW Uttar Pradesh (West) & Uttarakhand Telecom Circle (excludes Ghaziabad & Noida)

Description of Telecom operators in India:

Operator Name Value
AC Aircel
A Airtel
AL Allianz
B BSNL
D Dishnet
E Etisalat
H HFCL
I Idea
LO Loop
MT MTNL
P Ping
R Reliance
S Sistema
ST S Tel
T Tata
U Unitech
VI Videocon
V Vodafone