Getting Started with Nexmo’s Number Insight APIs on Koa.js

Published February 21, 2019 by Hui Jing Chen

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.

There are three levels of Number Insight API available: Basic, Standard, and Advanced, each returning an increasing amount of information about the queried phone number. The advanced API is available asynchronously as well as synchronously.

In this blog post we’re going to look at how to use the API with Node.js and the Koa.js framework.


  • A basic understanding of Javascript
  • Node.js installed on your machine
  • A Nexmo account (for your API credentials)

This tutorial will take you through the process from scratch. If you’d like to see the finished code, you can clone the git repository for this project or remix it on Glitch. Note that they are slight differences for the Glitch implementation to cater for how projects are hosted on the platform.

Starting a Koa.js project from scratch

Create a project folder on your local machine, then run the following command to set up a new Node.js project.

This will trigger a series of prompts that will generate your package.json file. You can choose to leave the answers blank to use the default values if you wish.

Configuring package.json

Next, install Koa.js. Do note that Koa requires node v7.6.0 or higher for ES2015 and async function support.

Create a server.js file in your project folder.

Paste the following code into your newly created file.

Run the server.js file.

If you navigate to http://localhost:3000 from your browser, you should see an empty page with the text, “Hello Dinosaur ?”.

Check that server is running

You should also install dotenv, which allows you to load environment variables stored in a .env file into process.env.

And now you can create the .env file and it should contain at least the following variables:

To access environment variables, you’ll have to require it, ideally at the top of your server.js file.

If you haven’t signed up for a Nexmo account yet, now is a pretty good time to do it. Once you’ve logged into the dashboard, your API credentials should be the first thing you see. Be sure to enclose both your key and secret with quotes.

Getting to Know the Number Insights API

First off, install the Nexmo REST API client for Node.js:

Next, initialise a new Nexmo instance.

As mentioned earlier, there are three levels for the Number Insight API, and you can pick one depending on the type of information you require. This is how the API is structured.

You can refer to our API reference to see how the response JSON is structured.

Obtaining Number Insights

You will need some way to input the phone number to be queried, so let’s create a basic web page to do that.

Create a public folder in your project and add an index.html, styles.css and scripts.js to the folder. Your project structure should now look something like this:

Add the following your index.html page:

You can also add some basic styles to the page by adding the following to the styles.css file:

The next step is to send the input to the server so you can plug it into the Number Insight API and check it. To do that, trigger a POST request to a route that will handle the form content. The sample code below uses the Fetch API for this.

You will need to handle this POST request on the server side. Unlike other popular Node.js frameworks like Express or Hapi.js, Koa.js is much more modular. Features like routing or serving static files are supported, but in seperate modules, which need to be installed:

Update your server.js file to use these new dependencies. First, instead of serving up a “Hello Dinosaur! ?“ message, modify your server.js file to use the index.html file instead by replacing


Next, set up the route for incoming POST requests to /submit.

Basic API

If everything is set up correctly, you should be able to enter a phone number and get the resulting information about that number on your web page. With the Basic API, you can determine:

  • The country where a number is registered
  • The local and international representation of that number

With such information, you could discover which country a number belongs to and use the information to format the number correctly.

Basic Number API

Standard API

The Number Insight Standard API provides all the information from the Number Insight Basic API together with the following additional data:

  • The line type (mobile/landline/virtual number/premium/toll-free)
  • The Mobile Country Code (MCC) and Mobile Network Code (MNC)
  • The name of the caller (USA only)

A common use-case for this would be to determine the best type of communication for a number (SMS or voice) and block virtual numbers.

Standard Number API

Advanced API

Finally, the Number Insight Advanced API provides all the data from the Number Insight Standard API together with the following additional information:

  • If the number is likely to be valid
  • If the number is ported
  • If the number is reachable
  • If the number is roaming and, if so, the carrier and country

Often, such information is used to determine the risk associated with a number.

Advanced Number API

The Advanced Number API can also be used asychronously to return the insight data when it becomes available, via a webhook. Note that this feature is not available for the Basic and Standard APIs.

Where Next?

If you are keen to do more with these APIs, here are some links that might be helpful to you:

Leave a Reply

Your email address will not be published.

Get the latest posts from Nexmo’s next-generation communications blog delivered to your inbox.

By signing up to our communications blog, you accept our privacy policy , which sets out how we use your data and the rights you have in respect of your data. You can opt out of receiving our updates by clicking the unsubscribe link in the email or by emailing us at