Using Number Insight via the Vonage CLI

Overview

You can use the Vonage CLI to work with the Number Insight API without having to create the requests using curl or by writing program code. This guide shows you how.

Getting Started

Before you begin:

Install and Setup the Vonage CLI (Command Line Interface)

Install latest version of Vonage Command Line Interface (CLI)

The Vonage CLI allows you to carry out many operations on the command line. Examples include creating applications, purchasing numbers, and linking a number to an application.

To install the CLI with NPM run:

npm install -g @vonage/cli

Set up the Vonage CLI to use your Vonage API Key and API Secret. You can get these from the settings page in the Dashboard.

Run the following command in a terminal, while replacing API_KEY and API_SECRET with your own:

vonage config:set --apiKey=API_KEY --apiSecret=API_SECRET

Try your own number with the Basic API

The Number Insight Basic API is free to use. Test it with your own number by using vonage numberinsight [NUMBER] and replacing [NUMBER] shown with your own number. The number must be in international format:

$ vonage numberinsight 15555555555

The Vonage CLI displays the basic level of insights by default:

Number Formats
National: (555) 555-5555
International: 15555555555

Country Details
Country: United States of America
Country Code: US
ISO 3 Code: USA
Prefix: 1

If you do not see a response similar to that shown above, check your API credentials and ensure that you have installed Node.js and the Vonage CLI properly. You can check your config by running vonage config

Test the Standard and Advanced APIs

The Standard and Advanced Number Insight APIs provide even more information about the number including details of the operator and roaming status (for mobile numbers). See the feature comparison table to see the response data that each API level includes.

Note: Calls to the Standard and Advanced APIs are not free, and you will be asked to confirm that you wish to charge your account when you use them.

Using the Number Insight Standard API

To use the Number Insight Standard API, use the following command:

$ vonage numberinsight --level=standard 15555555555

After running this command, you should see the following prompt:

This operation will charge your account. Proceed?

Enter y to proceed, and n to abort.

A typical response from the Standard API looks like this:

Number Formats
National: (555) 555-5555
International: 15555555555

Country Details
Country: United States of America
Country Code: US
ISO 3 Code: USA
Prefix: 1

Current Carrier
Name: CARRIER
Country: US
Network Type: undefined
Network Code: #####

Original Carrier
Name: CARRIER
Country: US
Network Type: undefined
Network Code: #####

Ported: ported

Roaming Status: undefined

Account Balance
Request Cost: 0.00500000
Remaining Balance: 100.00000000

Using the Number Insight Advanced API

$ vonage numberinsight --level=advanced 15555555555

As with the Standard API, you should see a This operation will charge your account. Proceed? prompt.

A typical response from the Advanced API looks like this:

Partial success - some fields populated

Number Formats
National: (555) 555-5555
International: 15555555555

Country Details
Country: United States of America
Country Code: US
ISO 3 Code: USA
Prefix: 1

Current Carrier
Name: CARRIER
Country: US
Network Type: undefined
Network Code: #####

Original Carrier
Name: CARRIER
Country: US
Network Type: undefined
Network Code: #####

Ported: ported

Roaming Status: undefined

Valid Number: valid

Reachable: unknown

Account Balance
Request Cost: 0.03000000
Remaining Balance: 100.00000000