Number Insight Advanced Webhook

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.

This code snippet shows you how to code the webhook handler that receives the data returned by an asynchronous call to the Number Insight Advanced API. See the Number Insight Advanced code snippet to learn how to code the initial request for the insight data.

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

KeyDescription
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.

Prerequisites

npm install @vonage/server-sdk

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

const { Vonage } = require('@vonage/server-sdk');

const vonage = new Vonage({
  apiKey: VONAGE_API_KEY,
  apiSecret: VONAGE_API_SECRET,
});

View full source

Write the code

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

vonage.numberInsight.asyncAdvancedLookup(
  INSIGHT_NUMBER,
  INSIGHT_CALLBACK_URL,
)
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

View full source

Run your code

Save this file to your machine and run it:

node ni-advanced-async.js

Prerequisites

Add the following to build.gradle:

implementation 'com.vonage:server-sdk-kotlin:2.1.1'
implementation 'io.ktor:ktor-server-netty'
implementation 'io.ktor:ktor-serialization-jackson'

Write the code

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

embeddedServer(Netty, port = 8000) {
    routing {
        post ("/webhooks/insight") {
            val insightDetails = Jsonable.fromJson(call.receive(), AdvancedInsightResponse::class.java)
            println(insightDetails)
            call.respond(204)
        }
    }
}.start(wait = true)

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 AdvancedInsightWebhook:

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

Prerequisites

Add the following to build.gradle:

implementation 'com.vonage:server-sdk:9.3.1'
implementation 'com.sparkjava:spark-core:2.9.4'

Write the code

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

port(3000);
Spark.post("/webhooks/insight", (req, res) -> {
    AdvancedInsightResponse response = Jsonable.fromJson(req.body());
    System.out.println("Country: " + response.getCountryName());

    res.status(204);
    return "";
});

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 AsyncInsightTrigger:

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

Prerequisites

Install-Package Vonage

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

using Vonage.Utility;
using System;

View full source

Write the code

Add the following to NumberInsightsController.cs:

            var insights = await WebhookParser.ParseWebhookAsync<AdvancedInsightsResponse>
                (Request.Body, Request.ContentType);
            Console.WriteLine($"Advanced insights received: {insights.RequestId} " +
                $"that number's carrier is {insights.CurrentCarrier.Name} " +
                $"and it's ported status is: {insights.Ported}");
            return NoContent();
        }
    }
}

View full source

Prerequisites

composer require vonage/client

Write the code

Add the following to index.php:

$handler = function (Request $request, Response $response) {
    $params = $request->getParsedBody();

    error_log($params['status_message']);
    error_log($params['country_code']);
    error_log($params['current_carrier']['name']);

    return $response->withStatus(204);
};

View full source

Run your code

Save this file to your machine and run it:

php index.php

Prerequisites

pip install fastapi[standard]

Write the code

Add the following to main.py:

from fastapi import FastAPI, Request

app = FastAPI()


@app.post('/webhooks/insight')
async def display_advanced_number_insight_info(request: Request):
    data = await request.json()
    print(data)

View full source

Run your code

Save this file to your machine and run it:

fastapi dev number-insight/async-callback/main.py

Prerequisites

gem install sinatra sinatra/multi-route json

Write the code

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

require 'sinatra'
require 'sinatra/multi_route'
require 'json'

helpers do
  def parsed_body
     json? ? JSON.parse(request.body.read) : {}
  end

  def json?
    request.content_type == 'application/json'
  end
end

route :post, '/webhooks/insight' do
  puts params.merge(parsed_body)
  
  status 200
end

set :port, 3000

View full source

Run your code

Save this file to your machine and run it:

ruby ni-advanced-async.rb

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" }
}

For a description of each returned field and to see all possible values, see the Number Insights API documentation