Creating a Caller ID with Number Insight and Java

Published September 04, 2018 by Steve Crow


In this tutorial, you will create an application that can be used as a web-based caller ID. Your application will make requests to the Nexmo Number Insight API and display the results.

Feel free to refer to the nexmo-community/java-caller-id repository as you follow along.


To work through this tutorial, you will need a Nexmo account. Sign up now if you don’t already have an account.

During the sign-up process you will be assigned an API key and secret. You will need these in a later step of the tutorial.

You will be using Gradle to manage your dependencies and run your application. Additionally, you’ll need to make sure you have a copy of the JDK installed.

Building a Caller ID with Java

This tutorial will walk you through the following steps:

  1. Using Gradle to setup a new Java project.
  2. Using the Spark framework to serve the caller ID page as well as processing number lookup requests.
  3. Creating a front end which can be used to collect phone numbers to look up.

Using Gradle to Setup a New Java Project

You will use Gradle to manage your dependencies and to create and run your Java application.

The gradle init --type=java-application command will create all of the folders you will need as well as a sample class where you will be writing your code.

From the command line, create a new Java project with the following commands:

Using the Spark Framework

You will use the Spark framework to both serve the caller ID page as well as process number lookup requests through an API.

Adding the Dependencies

Add the following to the dependencies block in your build.gradle file:

Creating the API Route

Gradle creates an App class in src/main/java containing getGreeting and main methods. Delete the getGreeting method as we don’t need it.

Defining the Environment

Instead of hard-coding your Nexmo API key and secret, you will be storing it in an environment variable.

For the purpose of this demo you will be using the Dotenv library and a .env file.

Create a resources folder in src/main and create a file called .env with the following information:

Replace your-api-key and your-api-secret with your Nexmo API key and secret respectively.

Defining the Route

It can be helpful to store things as constants. You will instantiate a new NexmoClient using your NEXMO_API_KEY and NEXMO_API_SECRET defined earlier.

Additionally, you will define some constants that will be used in your Spark routing and an ObjectWriter which will be used to build the JSON response from your API.

Define the following constants and variables in App:

Next, you will create a new method which will return a spark.Route. This route will accept a NUMBER_PARAM in the URL, perform a Nexmo Number Insight API request, and return a JSON response containing the AdvancedInsightResponse information.

Create the following method in App below the main method:

Register the Route

You need to configure Spark so that it knows when to use the route you just defined.

First you will configure the port that Spark runs on, and then you will configure the path that your newly-created route will answer to (/api/:number).

The path that you define will use the :number parameter which will represent a phone number inside of the route.

Add the following constant to App near all of the other constants you have created:

Add the following method to App above the createRequestRoute method:

Now, you will change the main method in App in order to start Spark when the application is run.

Change the main method in App to the following:

Start your application using the gradle run command.

You can now navigate to http://localhost:3000/api/13034997111 and should see a response similar to the following:

Storing Static Content

You will need a folder for holding your static content. This folder should go in the resources directory under src/main which you created earlier. A good convention is to name the folder public and to also put a css and js folder.

Resource folder containing a public folder which contains a css and js folder

Add an index.html file to the public folder with the following content:

Serving Static Content

Static content is served out of a specific folder. You will create a constant to represent the location of this folder.

Define the following constants in App:

Now you will need to update Spark so that it knows to serve static content from this location.

Update the start method in App to the following:

Run the gradle run command.

This will start your application and start serving your index.html file at http://localhost:3000. Navigating to this address in your browser will display the Hello World text in the index.html page you previously made.

Building a User Interface

Now that you have Java and Spark performing requests to Nexmo Number Insight API and serving static content, it’s time to move on to building a user interface.

Example User Interface

The following is one approach to a user interface. It uses JavaScript to make AJAX calls to the API you built in an earlier step. It then renders the information on the page. It also uses the cleave.js JavaScript library to format the phone number on input.

The result will produce the following page:
index.html page with a form for entering a phone number and the resulting information

Create the Index Page

Replace your index.html with the following:

Style the Index Page

Create style.css in the src/main/resources/public/css folder with the following content:

Create the JavaScript

Create app.js in the src/main/resources/public/js folder with the following content:

Test Your Final Application

Start your application with the gradle run command inside of your java-caller-id directory. Navigate to http://localhost:3000 and you will be ready to gain insight.


The Nexmo Number Insight API is a powerful tool for gaining useful information on numbers. It uses a vast amount of real-time data from carrier databases and Nexmo databases to give you the most accurate set of information.

Explore other ways that you might use the Nexmo Number Insight API. Think about what other services you can integrate it with.

Check out our documentation on Nexmo Developer where you can learn more about the Nexmo Number Insight API and other Nexmo offerings. See our Nexmo Quickstart Examples for Java for full code examples on this tutorial and more.

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