How to Use The Number Insight API with PHP

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.

Introduction

In this post, we’ll walk through an example application that uses the Vonage Number Insight API to validate and gain information about any phone number. This API is ideal for checking that a phone number is valid, active, and in a specific geography, making it commonly used to verify contact details at sign-up.

You could either use this project as a starting point (the code is on GitHub) or adapt the examples for your own applications. 

The Number Insight API

The Number Insight API provides information about a given phone number and is available at various service levels with corresponding pricing.

The Basic level is free and very useful for checking whether a number exists and is valid. Using a tool like this is great practice if you expect users to provide valid contact details.

The Standard level includes everything from Basic, plus information about the type of number and the carrier it uses. 

With Advanced, all the above is included along with roaming and reachability information.

The Advanced Number Insight API is also available as an asynchronous call. You can find examples of this and a good feature comparison table in the developer documentation.

Prerequisites

• PHP 8.1+

• Composer, for package management

• A Vonage API Account 

• Ngrok, for Advanced Insight

Vonage API Account

To complete this tutorial, you will need a Vonage API account. If you don’t have one already, you can sign up today and start building with free credit. Once you have an account, you can find your API Key and API Secret at the top of the Vonage API Dashboard.

Ready to start building?

Experience seamless connectivity, real-time messaging, and crystal-clear voice and video calls—all at your fingertips.

Get the code from the GitHub repository - clone or download this to your development machine.

Set Up the Application

To begin, change into the directory where you put the project code. Use Composer to install the dependencies by running this command:

composer install

Copy config.php.sample to config.php, then edit it to add your Vonage API key and secret (both available in your dashboard). 

<?php

return [

    'api_key' => 'YOUR_API_KEY',

    'api_secret' => 'YOUR_API_SECRET',

    'callback_url' => 'https://my-callback-url-here.ngrok.app'

];

For the Advanced Insight, you’ll need to provide a callback URL as well. 

In a new terminal tab, run ngrok http 8080, then paste the returned URL into config.php as the callback_url value.

Finally, change into the public/ directory and start PHP’s built-in web server:

cd public

php -S localhost:8080

If you visit http://localhost:8080/ in your browser, you will see a form to enter the number you are interested in and the level of insight you want.

Screenshot of Number Insights Form

Get an Insight Using the Vonage PHP SDK

One of the project's dependencies is vonage/client, which allows us to call the API from any PHP application using our SDK. This example uses the SlimPHP framework, but the Vonage PHP library works with any framework or standalone project.

Take a look around the project structure:

├── config.php

├── public

│   ├── css

│   │   └── marketing.css

│   └── index.php

└── templates

    └── main.php

Most of the PHP action is in public/index.php. The top-level route loads a page template (see templates/main.php) so the user can see the form. The form submits to /insight, which is the route where most of the activity occurs.

$params = $request->getParsedBody();

$basic = new \Vonage\Client\Credentials\Basic(

    $config['api_key'],

    $config['api_secret']

);

$client = new \Vonage\Client($basic);

// choose the correct insight type

switch($params['insight']) {

    case "standard":

        $insight = $client->insights()->standard($params['number']);

        break;

    case "advanced":

        $insight = $client->insights()->advanced($params['number']);

        break;

    default:

        $insight = $client->insights()->basic($params['number']);

        break;

}

First, we grab those form parameters into $params (this helper function is the only Slim-specific bit!), then we instantiate a new  \Vonage\Client object and supply our API key and secret to it.

Next, there's a switch statement so that the correct Number Insight API endpoint gets called, with "basic" as the default type - because we never trust user input! It's a form, they could send us anything.

The response is stored in $insight, and the action passes it through to the template for display. The $insight value is an object, but its data fields are accessible via array notation, for example, $insight['status'] or $insight['country_code']. 

In the template, the fields are displayed in a tabular layout, showing the fields that were returned for this level of Number Insight, as shown below:

Screenshot of the Standard Number Insight OutputThere is also handling for an error outcome: if status is non-zero, indicating an error; the status code and message are passed to the template and displayed above the form. You can test this by entering an invalid phone number.

Next Steps

Here are some places you might like to go next:

• The API Reference docs are probably a good place to start!

• Code Snippets are available on the developer portal in other programming languages.

• For one-off number lookups, you could use the Number Insight API from the CLI.

• Try the Identity Insights API for real-time access to a broad range of attributes related to the carrier, subscriber, or device associated with a phone number.

Conclusion

In this tutorial, we built a PHP application that uses the Vonage Number Insight API to validate phone numbers and retrieve key metadata. You can extend this example or combine it with other Vonage APIs for verification and fraud prevention.