Getting Started with the Identity Insights API

This guide will walk you through all of the necessary steps to get up and running with the Vonage Identity Insights API.

Prerequisites

Before you begin, you'll need the following:

A Vonage account: Sign up here if you don't already have one.
cURL: You'll be using this to make API calls. You can install it from the cURL download page using your favorite package manager.

Set up the environment

Some of the Identity Insights rely on network features. In such cases, there are two different environments:

Production. This environment returns live data from the supported Operators in some countries. Access to the production environment requires approval from the mobile operators. To learn how to request access, follow this guide.
Playground. The Playground is a safe and controlled testing environment where API calls return live data only for a small group of allowlisted phone numbers. Unlike production, it does not require approval from Operators. Additionally, the Playground provides access to the Virtual Operator, a simulated operator that generates fake but deterministic responses.

In this guide, we will use the Playground Environment with the Virtual Operator for two key reasons:

It allows immediate use of the APIs without needing approval from the Operators.
It enables testing the APIs from anywhere in the world.

Create a New Application

To get started, we need to create a new application. This application will contain the credentials required for making API calls. Follow these steps:

Go to the Dashboard and select "Applications" from the left side menu.
Click the "Create a new application" button.
Enter a name for your application in the "Name" field.
Click "Generate public and private key" to generate a key pair. A private key file will be automatically downloaded. Save this file securely, as it is required for generating JWTs.
Scroll to the capabilities section and enable the "Network Registry" capability for the “Playground” environment. Features such as “QOD” or “Verify (SA)” do not need to be enabled here, as they are not used by Identity Insights.
Click the "Generate new application" button to finish the creation process.
If you'd like to test with live numbers, add them to the Allowlist in your playground.

After the application is created, copy the Application ID displayed on the dashboard. You will need this Application ID along with the private key file to generate JWTs for authenticating API requests.

Make Your First API Call

Using the Dashboard

From the Getting Started UI in the dashboard, you can also use the API without writing any code, eliminating any friction related to authentication generation or connectivity. It offers two test modes:

Sandbox: Choose from a predefined list of phone numbers to explore API behavior using mocked examples.
Live: Select your preferred application and test phone numbers based on its supported capabilities.

A screenshot showing the Getting Started UI for the Identity Insights API in the Vonage customer dashboard.

Using cURL

Authenticate yourself using a JWT, a compact and self-contained JSON token. To generate a JWT, you can use our online generator, or alternatively use the Vonage CLI.

Once you have your JWT, you can send a request to the API. The below example shows a cURL request to the API for the Format insight, which will validate the provided phone number (in this case 447009000000), and retrieve additional information based on the format of that number:

curl -X POST https://api-eu.vonage.com/v0.1/identity-insights \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
   "phone_number": "447009000000",
   "insights": {
      "format": {}
    }
  }'

The example response below shows that is_format_valid has returned as true - this involves verifying the length and prefix details at various levels to ensure accuracy and compliance with global numbering standards. A valid format means the number can be legitimately assigned by carriers to users, however it does not guarantee that the number is currently assigned to a carrier or that it is reachable.

It also returns information such as the country prefix, two and three character country codes for the provided phone number, and the number formatted according both the international E.164 format and local conventions of the country the phone number belongs to. You can read more about each of these fields in the API Specification.

{
   "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
   "insights": {
      "format": {
         "country_code_iso2": "GB",
         "country_code_iso3": "GBR",
         "country_name": "United Kingdom",
         "country_prefix": "44",
         "offline_location": "Texas",
         "time_zones": [
            "America/Chicago"
         ],
         "number_international": "447920000000",
         "number_national": "07920 000000",
         "is_format_valid": true,
         "status": {
            "code": "OK",
            "message": "Success"
         }
      }
   }
}

If you want to use insights that use the Network Registry, such as SIM Swap, you must include the purpose parameter in your request. The value provided must match one of the network profile purposes associated with your application. The following example is using the SIM Swap insight to check for any recent SIM pairing changes related to the provided phone number, 447009000000:

curl -X POST https://api-eu.vonage.com/v0.1/identity-insights \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
   "phone_number": "447009000000",
   "purpose": "FraudPreventionAndDetection",  
   "insights": {
      "sim_swap": {
         "period": 240
      }
    }
  }'

In this example response, the is_swapped parameter has been returned as true, along with a date and time in UTC ISO 8601 format to indicate when the latest SIM Swap has been performed:

{
   "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
   "insights": {
      "sim_swap": {
         "latest_sim_swap_at": "2024-07-08T09:30:27.504Z",
         "is_swapped": true,
         "status": {
            "code": "OK",
            "message": "Success"
         }
      }
   }
}

You can use any combination of insights in a single API call; for example, this request will return both the Format and SIM Swap insights:

curl -X POST https://api-eu.vonage.com/v0.1/identity-insights \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
   "phone_number": "447009000000",
   "purpose": "FraudPreventionAndDetection",  
   "insights": {
      "format": {},
      "sim_swap": {
         "period": 240
      }
    }
  }'

The response will then contain the results of both insight requests:

{
   "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
   "insights": {
      "format": {
         "country_code_iso2": "GB",
         "country_code_iso3": "GBR",
         "country_name": "United Kingdom",
         "country_prefix": "44",
         "offline_location": "Texas",
         "time_zones": [
            "America/Chicago"
         ],
         "number_international": "447920000000",
         "number_national": "07920 000000",
         "is_format_valid": true,
         "status": {
            "code": "OK",
            "message": "Success"
         }
      },
      "sim_swap": {
         "latest_sim_swap_at": "2024-07-08T09:30:27.504Z",
         "is_swapped": true,
         "status": {
            "code": "OK",
            "message": "Success"
         }
      }
   }
}