Number Insight Advanced API

You use Number Insight Advanced API to retrieve validity, roaming, and reachability information about a mobile phone number synchronously. Number Insight Advanced API also returns the same information as Number Insight Standard API.

Note: check the legislation in your country and validate that you can save user information about roaming locally.

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

  • Retrieve the international and local format.
  • Know the country it is registered in.
  • See if it is for a mobile phone, landline, virtual number (Google Voice, Skype etc.) or a Premium/Toll-Free number.
  • Identify the mobile country code and mobile network code (MNCMCC) for a mobile phone number for routing outbound communication.
  • Find out if it is ported.
  • Identify the caller name (US only)
  • Learn if the phone number is reachable.
  • Discover which network phone number is using when roaming.
  • Confirm that your user's IP address is in the same location as their mobile phone.

The workflow for Number Insight Advanced API is:

workflow_number_insight_basic_api
  1. Request information about a phone number.
  2. Receive information about the number in the response and see the information you requested plus the status.

Implementing the Number Insight Advanced API workflow

To use Nexmo Number Insight Advanced API:

  1. Ask for information about a phone number using the request.
    <?php
    $url = 'https://api.nexmo.com/ni/advanced/json?' . http_build_query(
        [
            'api_key' => 'API_KEY',
            'api_secret' => 'API_SECRET',
            'number' => '441632960960'
        ]
    );
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    $response = curl_exec($ch);
    
    import urllib
    import urllib2
    
    params = {
        'api_key': 'API_KEY',
        'api_secret': 'API_SECRET',
        'number': '441632960960'
    }
    
    url = 'https://api.nexmo.com/ni/advanced/json?' + urllib.urlencode(params)
    
    request = urllib2.Request(url)
    request.add_header('Accept', 'application/json')
    response = urllib2.urlopen(request)
    
    require "net/http"
    require "uri"
    
    uri = URI.parse("https://api.nexmo.com/ni/advanced/json")
    params = {
        "api_key" => 'API_KEY',
        "api_secret" => 'API_SECRET',
        "number" => '441632960960'
    }
    
    response = Net::HTTP.post_form(uri, params)
    
    puts response.body
    
    xvar https = require('https');
    
    var data = JSON.stringify({
     api_key: 'API_KEY',
     api_secret: 'API_SECRET',
     number: '441632960960',
    
    });
    
    var options = {
     host: 'api.nexmo.com',
     path: '/ni/advanced/json',
     port: 443,
     method: 'POST',
     headers: {
       'Content-Type': 'application/json',
       'Content-Length': Buffer.byteLength(data)
     }
    };
    
    var req = https.request(options);
    
    req.write(data);
    req.end();
    
    var responseData = '';
    req.on('response', function(res){
     res.on('data', function(chunk){
       responseData += chunk;
     });
    
     res.on('end', function(){
       console.log(JSON.parse(responseData));
     });
    });
    
  2. Receive a response and see the information you requested plus the status and price for your request:
    <?php
    //Decode the json object you retrieved when you ran the request.
    $decoded_response = json_decode($response, true);
    
    if ($decoded_response['status'] == 0) {
      error_log("Success " . $decoded_response['request_id']);
      error_log( $decoded_response['international_format_number']
        . ' is using ' . $decoded_response['current_carrier']['name'] );
      error_log( 'Their home networks is: '
        . $decoded_response['original_carrier']['name'] );
    } else {
      error_log("Error {$decoded_response['status']} {$decoded_response['error_text']}");
    }
    
    import json
    
    #Using the response object from the request
    if response.code == 200 :
        data = response.read()
        #Decode JSON response from UTF-8
        decoded_response = json.loads(data.decode('utf-8'))
        # Check if your messages are succesful
        if decoded_response["status"] == 0:
            print "Success " + decoded_response['request_id']
            print decoded_response['international_format_number'] + \
                ' is using ' + decoded_response['current_carrier']['name']
            print 'Their home networks is: ' + \
                decoded_response['original_carrier']['name']
        else:
            print "Error " . decoded_response["status"] + \
                ': ' + decoded_response['status_message']
    else :
        #Check the errors
        print "unexpected http {code} response from nexmo api". response.code
    
    require 'json'
    
    #Decode the json object from the response object you retrieved from the request.
    if response.kind_of? Net::HTTPSuccess
      decoded_response = JSON.parse(response.body )
    
      if decoded_response["status"] == 0
        p "Success" + decoded_response["request_id"] + "\n"
        p decoded_response['international_format_number'] + ' is in ' \
          + decoded_response['country_name']
        p decoded_response['international_format_number'] + ' is using ' \
          + decoded_response['current_carrier']['name']
        p 'Their home networks is: ' + decoded_response['original_carrier']['name']
      else
        p "message has error " + decoded_response["status"].to_s + " " + decoded_response["status_message"]
      end
    else
      puts response.code + " error sending message"
    end
    
    //Decode the json object you retrieved when you ran the request.
    var decoded_response = JSON.parse(responseData);
    
    if (decoded_response.status === 0) {
      console.log('Success ' + decoded_response.request_id );
      console.log( decoded_response.international_format_number + ' is using '
        + decoded_response.current_carrier.name );
      console.log( 'Their home networks is: '
        + decoded_response.original_carrier.name );
    }
    else {
      console.log('Error ' + decoded_response.status  + ': ' +  decoded_response.status_message );
    }
    
Previous   Next