Number Insight API Overview

Nexmo's Number Insight API delivers real-time intelligence about the validity, reachability and roaming status of a phone number and tells you how to format the number correctly in your application.

Contents

This document contains the following information:

Concepts

Basic, Standard and Advanced APIs

Each API level builds upon the capabilities of the previous one. For example, the Standard API includes all of the locale and formatting information from the Basic API and returns extra data about the type of number, whether it is ported and the identity of the caller (US only). The Advanced API provides the most comprehensive data. It includes everything that is available in the Basic and Standard APIs and adds roaming and reachability information.

Unlike the Basic and Standard APIs, you can optionally use the Advanced API asynchronously.

Typical use cases

Feature comparison

Feature Basic Standard Advanced
Number format and origin
Number type
Carrier and country
Ported
IP match
Validity
Reachability
Roaming status
Roaming carrier and country
US number caller name and type

Check the legislation in your country to ensure that you are allowed to save user roaming information.

Getting Started

This example shows you how to use the Nexmo CLI to access the Number Insight Basic API and display information about a number.

For examples of how to use Basic, Standard and Advanced Number Insight with curl and the developer SDKs see the Building Blocks.

Before you begin:

Install and set up the Nexmo CLI

$ npm install -g nexmo-cli

Note: Depending on your user permissions, you might need to prefix the above command with sudo.

Use your NEXMO_API_KEY and NEXMO_API_SECRET from the dashboard getting started page  to set up the Nexmo CLI with your credentials:

$ nexmo setup NEXMO_API_KEY NEXMO_API_SECRET

Execute a Number Insight API Basic lookup

Execute the example command shown below, replacing the phone number with one that you want information about:

nexmo insight:basic 447700900000

View the response

The Basic API response lists the number together with the country the number is located in. For example:

447700900000 | GB

Use the --verbose flag (or -v) to see everything that the Basic API response contains:

$ nexmo insight:basic --verbose 447700900000

[status]
0

[status_message]
Success

[request_id]
aaaaaaaa-bbbb-cccc-dddd-0123456789ab

[international_format_number]
447700900000

[national_format_number]
07700 900000

[country_code]
GB

[country_code_iso3]
GBR

[country_name]
United Kingdom

[country_prefix]
44

Guides

Building Blocks

Tutorials

Reference