Validate a number

The Number Insight API helps you validate numbers that customers provide to prevent fraud and ensure that you can contact that customer again in the future. It also provides you with other useful information such as how to format the number and whether the number is a mobile or landline.

The Number Insight API has three product levels:

• Basic API: Discover which country a number belongs to and use the information to format the number correctly.
• Standard API: Determine whether a number is a landline or mobile number (to choose between voice and SMS contact) and block virtual numbers.
• Advanced API: Calculate the risk associated with a number.

The Ruby Server SDK makes it straightforward to access the Number Insight API. It also enables you to work with the other APIs, such as the Pricing API. This means that as well as validating and sanitizing a phone number, you can confirm the cost of sending text messages and voice calls to it, as we demonstrate in the calculate the cost section of this tutorial.

In this tutorial

You learn how to sanitize and validate phone numbers using the Ruby Server SDK.

• Before you begin make sure that you have what you need to complete this tutorial
• Create the project by cloning the tutorial source code on GitHub and configuring it with your Vonage account details
• Install the dependencies including the Ruby Server SDK
• Code walkthrough to learn how the code works

Before you begin

To complete this tutorial you need:

• Your api_key and api_secret for your Vonage account - sign up for an account if you do not already have one
• Access to the tutorial source code on GitHub

Create the project

Clone the tutorial source code repository:

Change to the project folder:

Copy the .env-example file to .env and edit .env to configure your API key and secret from the dashboard:

Install the dependencies

Run bundle install to install the project's dependencies.

Code Walkthrough

The tutorial project is not an application, but a collection of code snippets that show you how to work with the Number Insight API. In this walkthrough you will execute each snippet in turn and learn how it works.

Determine the country

This sample uses the Number Insight Basic API to find out which country a number belongs to.

Run the code

Execute the snippets/1_country_code.rb ruby file:

This returns the phone number in international format as well as the name, code and prefix where the number is registered.

How it works

First, the code creates the nexmo client object with the API key and secret that you configured in the .env file:

Then, it calls the Number Insight Basic API, passing in the number to provide insight about:

Sanitize a Number

Your user might supply a phone number that is not in international format. That is, it does not include the country prefix. This sample shows you how to use the Number Insight Basic API to format the number correctly.

Run the code

Execute the snippets/2_cleanup.rb ruby file:

This returns the local number provided (020 3198 0560, a Great Britain (GB) number) in international format with the 44 prefix:

How it works

To retrieve a phone number in international format, call the Number Insight Basic API with a phone number in local format and a country code:

Determine the type of number (landline or mobile)

The Number Insight Standard API supplies more information about a phone number than the Basic API but includes all the data that the Basic API provides. One of its most useful features is that it tells you type of number you are dealing with, so that you can determine the best way to contact the number.

Run the code

Execute the snippets/3_channels.rb ruby file:

You see that this phone number is assigned to a UK landline, making voice a better option than SMS:

How it works

To determine the type of number, call the Number Insight Standard API, passing in either a local number with the country code as we demonstrate here:

You could also pass the number in international format without specifying the country:

Then we can find the current carrier information and use it to display the type of number (mobile or landline):

Calculate the cost

You can use the Number Insight APIs and Pricing APIs together to determine which network the number is on and how much it costs to call the number, or send an SMS to it.

Run the code

Execute the snippets/4_cost.rb ruby file:

The response indicates the cost to send an SMS message or the price-per-minute for a voice call to the phone number:

This output shows that the number is a landline and therefore best suited to voice calls, which you can make at a cost of 0.12 EUR per minute.

How it works

The code first calls the Number Insight Standard API, which provides information about the network the number is currently registered to, as well as the country of origin (a feature that is also available in the Basic API):

It then uses the Pricing API to retrieve the cost of calling and texting the number for all the carriers in that country:

Other options for retrieving pricing data in the Ruby REST Client API are:

• vonage.pricing.sms.list() or vonage.pricing.voice.list() - to retrieve pricing data for all countries
• vonage.pricing.sms.prefix(prefix) or vonage.pricing.voice.prefix(prefix) - to retrieve pricing data for a specific international prefix code, such as 44 for the United Kingdom.

The code then looks up the cost for the specific network that the number belongs to and displays that information:

Validate a mobile phone number

The Number Insight Advanced API enables you to validate a number to determine if it is likely to be genuine and a reliable way to contact your customer. For mobile numbers, you can also discover whether the number is active, roaming, reachable and in the same location as their IP address. The Advanced API includes all the information from the Basic and Standard APIs.

Run the code

Execute the snippets/5_validation.rb ruby file:

In this case the response indicates that the number is valid.

If you remove a few digits from the phone number and re-run the program, the Number Insight Advanced API reports that the number is not_valid.

If the Number Insight Advanced API is unable to determine whether the number is valid or not, you will receive a response of unknown:

How it works

The code requests the international representation of the number as before, using a feature that is available in the Basic API but which the Advanced API also includes:

It also returns and displays the valid_number field from the response. This field's value is one of valid, not_valid or unknown.

Conclusion

In this tutorial you learned how to validate and determine the international format of a number and calculate the cost of calling or sending SMS messages to it.

Resources and Further Reading

• Check out our Number Insight Guides for more things you can do with Number Insight.
• Read Blog Posts about Number Insight.
• Visit the Number Insight API Reference for detailed documentation on each endpoint.