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.
Find out more about the basic, standard and advanced APIs. Note: Requests to the Number Insight Basic API are free. The other API levels incur costs. See the API reference for more information.
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
andapi_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:
git clone git@github.com:Nexmo/ruby-ni-customer-number-validation.git
Change to the project folder:
cd ruby-ni-customer-number-validation
Copy the .env-example
file to .env
and edit .env
to configure your API key and secret from the dashboard:
VONAGE_API_KEY="(Your API key)"
VONAGE_API_SECRET="(Your API secret)"
Install the dependencies
Run bundle install
to install the project's dependencies.
$ bundle install
Fetching gem metadata from https://rubygems.org/...
Resolving dependencies...
Using bundler 1.16.4
Using dotenv 2.1.1
Using jwt 2.1.0
Using vonage 7.2.0
Bundle complete! 2 Gemfile dependencies, 4 gems now installed.
Use `bundle info [gemname]` to see where a bundled gem is installed.
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:
$ ruby snippets/1_country_code.rb
This returns the phone number in international format as well as the name, code and prefix where the number is registered.
{
"status" => 0,
"status_message" => "Success",
"request_id" => "923c7054-3201-4146-b6df-23bfe929cd03",
"international_format_number" => "442079460000",
"national_format_number" => "020 7946 0000",
"country_code" => "GB",
"country_code_iso3" => "GBR",
"country_name" => "United Kingdom",
"country_prefix" => "44"
}
How it works
First, the code creates the nexmo
client object with the API key and secret that you configured in the .env
file:
require 'vonage'
vonage = Vonage::Client.new(
api_key: ENV['VONAGE_API_KEY'],
api_secret: ENV['VONAGE_API_SECRET']
)
Then, it calls the Number Insight Basic API, passing in the number
to provide insight about:
puts vonage.number_insight.basic(number: "442079460000")
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.
Most Vonage APIs expect a phone number to be in international format, so you can use the Number Insight Basic API to sanitize numbers before using them.
Run the code
Execute the snippets/2_cleanup.rb
ruby file:
$ ruby snippets/2_cleanup.rb
This returns the local number provided (020 3198 0560
, a Great Britain (GB
) number) in international format with the 44
prefix:
"442031980560"
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:
insight = vonage.number_insight.basic(
number: "020 3198 0560",
country: 'GB'
)
p insight.international_format_number
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:
$ ruby snippets/3_channels.rb
You see that this phone number is assigned to a UK landline, making voice a better option than SMS:
{
"network_code" => "GB-FIXED",
"name" => "United Kingdom Landline",
"country" => "GB",
"network_type" => "landline"
}
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:
insight = vonage.number_insight.standard(
number: "020 3198 0560",
country: 'GB'
)
You could also pass the number
in international format without specifying the country
:
insight = vonage.number_insight.standard(
number: "442031980560"
)
Then we can find the current carrier information and use it to display the type of number (mobile or landline):
p insight.current_carrier
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:
$ ruby snippets/4_cost.rb
The response indicates the cost to send an SMS message or the price-per-minute for a voice call to the phone number:
{
:sms => [{
"type" => "landline",
"price" => "0.03330000",
"currency" => "EUR",
"ranges" => [441, 442, 443],
"network_code" => "GB-FIXED",
"network_name" => "United Kingdom Landline"}],
:voice => [{
"type" => "landline",
"price" => "0.01200000",
"currency" => "EUR",
"ranges" => [441, 442, 443],
"network_code" => "GB-FIXED",
"network_name" => "United Kingdom Landline"}]
}
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):
insight = vonage.number_insight.standard(
number: '020 3198 0560',
country: 'GB'
)
# Store the network and country codes
current_network = insight.current_carrier.network_code
current_country = insight.country_code
It then uses the Pricing API to retrieve the cost of calling and texting the number for all the carriers in that country:
# Fetch the voice and SMS pricing data for the country
sms_pricing = vonage.pricing.sms.get(current_country)
voice_pricing = vonage.pricing.voice.get(current_country)
Other options for retrieving pricing data in the Ruby REST Client API are:
-
vonage.pricing.sms.list()
orvonage.pricing.voice.list()
- to retrieve pricing data for all countries -
vonage.pricing.sms.prefix(prefix)
orvonage.pricing.voice.prefix(prefix)
- to retrieve pricing data for a specific international prefix code, such as44
for the United Kingdom.
The code then looks up the cost for the specific network that the number belongs to and displays that information:
# Retrieve the network cost from the pricing data
sms_cost = sms_pricing.networks.select{|network| network.network_code == current_network}
voice_cost = voice_pricing.networks.select{|network| network.network_code == current_network}
p({
sms: sms_cost,
voice: voice_cost
})
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:
$ ruby snippets/5_validation.rb
In this case the response indicates that the number is valid
.
"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
.
"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
:
"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:
insight = vonage.number_insight.advanced(
number: "020 3198 0560",
country: 'GB'
)
It also returns and displays the valid_number
field from the response. This field's value is one of valid
, not_valid
or unknown
.
p insight.valid_number
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.