Number Insight Basic
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.
Use the Vonage Number Insight Basic API to determine:
- The country where a number is registered
- The local and international representation of that number
This can help you present numbers to your users in the correct format for their locale.
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-basic.sh:
curl "https://api.nexmo.com/ni/basic/json?api_key=$VONAGE_API_KEY&api_secret=$VONAGE_API_SECRET&number=$INSIGHT_NUMBER"
Run your code
Save this file to your machine and run it:
Prerequisites
npm install @vonage/server-sdkCreate a file named ni-basic.js and add the following code:
const { Vonage } = require('@vonage/server-sdk');
const vonage = new Vonage({
apiKey: VONAGE_API_KEY,
apiSecret: VONAGE_API_SECRET,
});Write the code
Add the following to ni-basic.js:
vonage.numberInsights.basicLookup(INSIGHT_NUMBER)
.then((result) => console.log(result))
.catch((error) => console.error(error));Run your code
Save this file to your machine and run it:
Prerequisites
Add the following to build.gradle:
implementation 'com.vonage:server-sdk-kotlin:2.1.1'Create a file named BasicInsight and add the following code to the main method:
val client = Vonage {
apiKey(VONAGE_API_KEY)
apiSecret(VONAGE_API_SECRET)
}Write the code
Add the following to the main method of the BasicInsight file:
val response = client.numberInsight.basic(INSIGHT_NUMBER)
println(response)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 BasicInsight:
Prerequisites
Add the following to build.gradle:
implementation 'com.vonage:server-sdk:9.3.1'Create a file named BasicInsight and add the following code to the main method:
VonageClient client = VonageClient.builder()
.apiKey(VONAGE_API_KEY)
.apiSecret(VONAGE_API_SECRET)
.build();Write the code
Add the following to the main method of the BasicInsight file:
BasicInsightResponse response = client.getInsightClient().getBasicNumberInsight(INSIGHT_NUMBER);
System.out.println("International format: " + response.getInternationalFormatNumber());
System.out.println("National format: " + response.getNationalFormatNumber());
System.out.println("Country: " + response.getCountryName() +
" (" + response.getCountryCodeIso3() + ", +" + response.getCountryPrefix() + ")"
);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 BasicInsight:
Prerequisites
Install-Package VonageCreate a file named BasicInsights.cs and add the following code:
using Vonage;
using Vonage.NumberInsights;
using Vonage.Request;Add the following to BasicInsights.cs:
var creds = Credentials.FromApiKeyAndSecret(VONAGE_API_KEY, VONAGE_API_SECRET);Write the code
Add the following to BasicInsights.cs:
var request = new BasicNumberInsightRequest() { Number = INSIGHT_NUMBER };Prerequisites
composer require vonage/clientWrite the code
Add the following to basic.php:
$basic = new \Vonage\Client\Credentials\Basic(VONAGE_API_KEY, VONAGE_API_SECRET);
$client = new \Vonage\Client($basic);
$insights = $client->insights()->basic(INSIGHT_NUMBER);Run your code
Save this file to your machine and run it:
Prerequisites
pip install vonage python-dotenvWrite the code
Add the following to ni-basic.py:
from vonage import Auth, Vonage
from vonage_number_insight import BasicInsightRequest, BasicInsightResponse
client = Vonage(Auth(api_key=VONAGE_API_KEY, api_secret=VONAGE_API_SECRET))
insight: BasicInsightResponse = client.number_insight.get_basic_info(
BasicInsightRequest(number=INSIGHT_NUMBER)
)
pprint(insight)Run your code
Save this file to your machine and run it:
Prerequisites
gem install vonageCreate a file named ni-basic.rb and add the following code:
Run your code
Save this file to your machine and run it:
The response from the API contains the following data:
{
"status": 0,
"status_message": "Success",
"request_id": "fcb1e9a2-db9c-4ea2-84be-4e60da45e187",
"international_format_number": "447700900000",
"national_format_number": "07700 900000",
"country_code": "GB",
"country_code_iso3": "GBR",
"country_name": "United Kingdom",
"country_prefix": "44"
}
For a description of each returned field and to see all possible values, see the Number Insights API documentation