Number Insight Advanced

You can use Nexmo's Number Insight Advanced API to retrieve a user's landline or mobile number, including checking to see that it is registered to an operator. This can help you verify that a phone number is real and give you information on how to format the number.

Number Insight Advanced Async API is a synchronous, easy-to-use RESTful web service. For any phone number you can:

  • Retrieve the international and local format.
  • Know the country where the number is registered.
  • Line type detection (mobile/landline/virtual number/premium/toll-free)
  • Detect mobile country code (MCC) and mobile network code (MNC)
  • Detect if number is ported
  • Identify caller name (USA only) - see the CNAM guide for details
  • Identify network when roaming
  • Confirm user's IP address is in same location as their mobile phone

Users are advised that the Advanced API does not give any information about landlines that is not already given by the Standard API. For number insights about landlines, you should use the Standard API.

curl "https://api.nexmo.com/ni/advanced/json?api_key=API_KEY&api_secret=API_SECRET&number=447700900000"
import com.nexmo.client.NexmoClient;
import com.nexmo.client.auth.AuthMethod;
import com.nexmo.client.insight.AdvancedInsightResponse;

AuthMethod auth = new TokenAuthMethod(API_KEY, API_SECRET);
NexmoClient client = new NexmoClient(auth);

AdvancedInsightResponse response = client.getInsightClient().getAdvancedNumberInsight(TO_NUMBER);
<?php 
require_once __DIR__ . '/../vendor/autoload.php';

$basic  = new \Nexmo\Client\Credentials\Basic(NEXMO_API_KEY, NEXMO_API_SECRET);
$client = new \Nexmo\Client($basic);

// Fetch advanced insights about this number
$response = $client->insights()->advanced('447700900000');

// Alternatively, you can fetch CNAM information too
$response = $client->insights()->advancedCnam('447700900000');
import nexmo

client = nexmo.Client(api_key='API_KEY', api_secret='API_SECRET')
client.get_advanced_number_insight(number="447700900000")
require 'nexmo'

client = Nexmo::Client.new(api_key: 'API_KEY', api_secret: 'API_SECRET')

client.number_insight.advanced(number: '447700900000')
nexmo insight:advanced --verbose 447700900000

The response from the API contains the following data:

{
    "status": 0,
    "status_message": "Success",
    "lookup_outcome": 0,
    "lookup_outcome_message": "Success",
    "request_id": "75fa272e-4743-43f1-995e-a684901222d6",
    "international_format_number": "447700900000",
    "national_format_number": "07700 900000",
    "country_code": "GB",
    "country_code_iso3": "GBR",
    "country_name": "United Kingdom",
    "country_prefix": "44",
    "request_price": "0.03000000",
    "remaining_balance": "10.000000",
    "current_carrier": {
        "network_code": "23420",
        "name": "Hutchison 3G Ltd",
        "country": "GB",
        "network_type": "mobile"
    },
    "original_carrier": {
        "network_code": "23410",
        "name": "Telefonica UK Limited",
        "country": "GB",
        "network_type": "mobile"
    },
    "valid_number": "valid",
    "reachable": "reachable",
    "ported": "ported",
    "roaming": {"status": "not_roaming"}
}
<?xml version="1.0" encoding="UTF-8"?>
<lookup>
  <request_id>75fa272e-4743-43f1-995e-a684901222d6</request_id>
  <international_format_number>447700900000</international_format_number>
  <lookup_outcome code="0">Success</lookup_outcome>
  <local_number country_code="GB" country_code_iso3="GBR" country_name="United Kingdom" country_prefix="44">07700 900000</local_number>
  <error code="0">Success</error>
  <request_price>0.03000000</request_price>
  <remaining_balance>10.000000</remaining_balance>
  <current_carrier network_code="23420" name="Hutchison 3G Ltd" country="GB" network_type="mobile" />
  <original_carrier network_code="23410" name="Telefonica UK Limited" country="GB" network_type="mobile" />
  <valid_number>valid</valid_number>
  <reachable>reachable</reachable>
  <ported>ported</ported>
  <roaming status="not_roaming" />
</lookup>