Number Insight Advanced

Effective February 4, 2027, Vonage will sunset Vonage Number Insights. To ensure uninterrupted support and to provide a more scalable and future-proof solution, we encourage you to migrate to our enhanced offering: Vonage Identity Insights API. The Vonage Identity Insights API consolidates multiple phone number-related datasets into a single, flexible API, allowing you to request real-time information about a phone number and retrieve any combination of insights - such as number formatting, carrier details, SIM Swap and Subscriber Match - in one call.

Please review the Number Insights Transition Guide, which provides detailed guidance on API differences, required changes, and best practices for a smooth transition.

The Number Insight Advanced API provides all the data from the Number Insight Standard API together with the following additional information:

If the number is likely to be valid
If the number is ported
If the number is reachable (not available in the US)
If the number is roaming and, if so, the carrier and country

Use this information to determine the risk associated with a number.

Note that the Advanced API does not provide any extra information about landlines than the Number Insight Standard API. For insights about landline numbers, use the Standard API.

This code snippet shows you how to trigger an asynchronous call to the Number Insight API. This is the approach Vonage recommends. You can optionally use the Number Insight Advanced API synchronously, but be aware that synchronous use can result in timeouts.

Before attempting to run the code examples, replace the variable placeholders:

Key	Description
`VONAGE_API_KEY`	Your Vonage API key (see it on your dashboard).
`VONAGE_API_SECRET`	Your Vonage API secret (also available on your dashboard).
`INSIGHT_NUMBER`	The number you want to retrieve insight information for.

Write the code

Add the following to ni-advanced-async.sh:

curl \
  -u "${VONAGE_API_KEY}:${VONAGE_API_SECRET}" \
  "https://api.nexmo.com/ni/advanced/async/json?number=$INSIGHT_NUMBER&callback=$INSIGHT_CALLBACK_URL"

View full source

Run your code

Save this file to your machine and run it:

sh ni-advanced-async.sh

Prerequisites

npm install express body-parser

Write the code

Add the following to ni-advanced-async-client.js:

const app = require('express')();
const bodyParser = require('body-parser');

app.use(bodyParser.json());
app.use(bodyParser.urlencoded({
  extended: true,
}));

const handleInsight = (request, response) => {
  console.log('params', Object.assign(request.query, request.body));
  response.status(204).send();
};

app.post('/webhooks/insight', handleInsight);

app.listen(3000);

View full source

Run your code

Save this file to your machine and run it:

node ni-advanced-async-client.js

Prerequisites

Add the following to build.gradle:

implementation 'com.vonage:server-sdk-kotlin:2.1.1'

Create a file named AdvancedInsightAsync and add the following code to the main method:

val client = Vonage {
    apiKey(VONAGE_API_KEY)
    apiSecret(VONAGE_API_SECRET)
}

View full source

Write the code

Add the following to the main method of the AdvancedInsightAsync file:

client.numberInsight.advancedAsync(INSIGHT_NUMBER, INSIGHT_CALLBACK_URL)

View full source

Run your code

We can use the application plugin for Gradle to simplify the running of our application. Update your build.gradle with the following:

apply plugin: 'application'
mainClassName = project.hasProperty('main') ? project.getProperty('main') : ''

Run the following gradle command to execute your application, replacing com.vonage.quickstart.kt.numberinsight with the package containing AdvancedInsightAsync:

gradle run -Pmain=com.vonage.quickstart.kt.numberinsight.AdvancedInsightAsync

Prerequisites

Add the following to build.gradle:

implementation 'com.vonage:server-sdk:9.3.1'

Create a file named AdvancedInsightAsync and add the following code to the main method:

VonageClient client = VonageClient.builder()
        .apiKey(VONAGE_API_KEY)
        .apiSecret(VONAGE_API_SECRET)
        .build();

View full source

Write the code

Add the following to the main method of the AdvancedInsightAsync file:

var response = client.getInsightClient().getAdvancedAsyncNumberInsight(
        AdvancedInsightAsyncRequest.builder()
            .number(INSIGHT_NUMBER)
            .callback(INSIGHT_CALLBACK_URL)
            .build()
);

View full source

Run your code

We can use the application plugin for Gradle to simplify the running of our application. Update your build.gradle with the following:

apply plugin: 'application'
mainClassName = project.hasProperty('main') ? project.getProperty('main') : ''

Run the following gradle command to execute your application, replacing com.vonage.quickstart.insight with the package containing AdvancedInsightAsync:

gradle run -Pmain=com.vonage.quickstart.insight.AdvancedInsightAsync

Prerequisites

Install-Package Vonage

Create a file named AdvancedAsync.cs and add the following code:

using Vonage;
using Vonage.Request;
using Vonage.NumberInsights;

View full source

Add the following to AdvancedAsync.cs:


var creds = Credentials.FromApiKeyAndSecret(VONAGE_API_KEY, VONAGE_API_SECRET);

View full source

Write the code

Add the following to AdvancedAsync.cs:


var request = new AdvancedNumberInsightAsynchronousRequest() { Number = INSIGHT_NUMBER, Callback = INSIGHT_CALLBACK_URL };

View full source

Prerequisites

composer require vonage/client

Create a file named advanced-async-trigger.php and add the following code:

$basic  = new \Vonage\Client\Credentials\Basic(VONAGE_API_KEY, VONAGE_API_SECRET);
$client = new \Vonage\Client($basic);

View full source

Write the code

Add the following to advanced-async-trigger.php:

try {
    $client->insights()->advancedAsync(SEARCH_NUMBER, CALLBACK_WEBHOOK);
    echo "The number will be looked up soon.";
} catch (\Vonage\Client\Exception\Request $e) {
    error_log("Client error: " . $e->getMessage());
    exit(1);
} catch (\Vonage\Client\Exception\Server $e) {
    error_log("Server error: " . $e->getMessage());
    exit(1);
}

View full source

Run your code

Save this file to your machine and run it:

php advanced-async-trigger.php

Prerequisites

pip install vonage python-dotenv

Write the code

Add the following to ni-advanced-async-trigger.py:

from vonage import Auth, Vonage
from vonage_number_insight import (AdvancedAsyncInsightRequest,
                                   AdvancedAsyncInsightResponse)

client = Vonage(Auth(api_key=VONAGE_API_KEY, api_secret=VONAGE_API_SECRET))

insight: AdvancedAsyncInsightResponse = client.number_insight.get_advanced_info_async(
    AdvancedAsyncInsightRequest(number=INSIGHT_NUMBER, callback=INSIGHT_CALLBACK_URL)
)
pprint(insight)

View full source

Run your code

Save this file to your machine and run it:

python number-insight/ni-advanced-async-trigger.py

Prerequisites

gem install vonage

Create a file named ni-advanced-async-client.rb and add the following code:

client = Vonage::Client.new(
  api_key: VONAGE_API_KEY,
  api_secret: VONAGE_API_SECRET
)

View full source

Write the code

Add the following to ni-advanced-async-client.rb:

insight = client.number_insight.advanced(
  number: INSIGHT_NUMBER,
  callback: INSIGHT_CALLBACK_URL
)

puts insight.inspect

View full source

Run your code

Save this file to your machine and run it:

ruby ni-advanced-async-client.rb

The API acknowledges the request by returning the following information to the client:

{
    "request_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "number": "447700900000",
    "remaining_balance": "10.000000",
    "request_price": "0.03000000",
    "status": 0
}

When the data becomes available, it is sent to the specified webhook via a POST request. See the Number Insight Advanced Async Callback code snippet to learn how to code the webhook handler.