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.
This document contains the following information:
- Concepts - what you need to know
- Basic, Standard and Advanced API levels - understand their different capabilities
- Getting Started with the Number Insight API - try it out
- Guides - learn how to use the Number Insight API
- Code Snippets - code snippets to help with specific tasks
- Use Cases - detailed use cases with code examples
- Reference - complete API documentation
- Webhooks - you can use the Advanced API to return comprehensive data about a number to your application when it becomes available, via a webhook.
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 which are synchronous APIs, the Advanced API is intended to be used asynchronously.
- Basic API: Discovering which country a number belongs to and using the information to format the number correctly.
- Standard API: Determining whether the number is a landline or mobile number (to choose between voice and SMS contact) and blocking virtual numbers.
- Advanced API: Ascertaining the risk associated with a number.
|Number format and origin|
|Carrier and country|
|Reachability (not available in the US)|
|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.
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 Code Snippets.
$ npm install -g nexmo-cli
Note: Depending on your user permissions, you might need to prefix the above command with
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 the example command shown below, replacing the phone number with one that you want information about:
nexmo insight:basic 447700900000
The Basic API response lists the number together with the country the number is located in. For example:
447700900000 | GB
--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
- Retrieving CNAM Owner Details: Retrieve identity details for US callers.
- Using Number Insight via the Nexmo CLI: Use the Nexmo CLI to get information about a phone number.