Protect yourself from fraud and spam

Get real-time intelligence on numbers anywhere in the world.


Quick start

Make sure you’ve read Getting Started.

About

Nexmo's Number Insight API provides details about the validity, reachability and roaming status of a phone number, as well as details on how to format the number properly in your application.

How it works

To get started and test the API from your local workstation you can use Postman or our API Reference (powered by SwaggerHub) or cURL as an HTTP client. If you use the Postman collection or API Reference, make sure you update the environment settings with your credentials in order to authenticate.

 

 

 

Connect to the API

To start testing the API you need to get authorization credentials. Log in to your account and create a developer app on the My Apps page. The steps to create a developer app are briefly discussed under 'Support'  🡆 'Frequently Asked Questions'.

Get access token

Copy your app's credentials and replace APP_CONSUMER_KEY and APP_CONSUMER_SECRET with the copied values, then execute the below cURL command to receive an access token.

You can use the same token to make multiple 'API' calls, provided the token is active. If the token expires then you can repeat this step.


curl -X POST \
 'https://api-prd.kpn.com/oauth/client_credential/accesstoken?grant_type=client_credentials' \
 -H 'content-type: application/x-www-form-urlencoded' \
 -d 'client_id=APP_CONSUMER_KEY&client_secret=APP_CONSUMER_SECRET'

The authorization service returns a JSON message that contains the access token field.

{
    "refresh_token_expires_in": "0",
    "api_product_list": "[Number Insight - Nexmo]",
    "api_product_list_json": [
        "Number Insight - Nexmo"
    ],
    "organization_name": "kpn",
    "developer.email": "demo123@kpn.com",
    "token_type": "BearerToken",
    "issued_at": "1521039195424",
    "client_id": "2Xvp2YLhEeT8w4cXQWvKuOpMoHQQ9zGx",
    "access_token": "haf2SDl07E9N7RluNQ4kJ1TkGgso",
    "application_name": "6e38ed2d-48b1-4362-97d6-04254065d79c",
    "scope": "",
    "expires_in": "3599",
    "refresh_count": "0",
    "status": "approved"
}

Number Insight Basic

You can use Nexmo's Number Insight Basic API to retrieve local and international representations of a phone number by doing semantic checks on the number you submit. This can help you normalize and consistently print numbers in your user interface and give you information to help you decide whether you accept the phone number entered by your user, or ask them to check and correct it.

The Number Insight Basic API is a free synchronous, easy-to-use RESTful web service. For any phone number you can:
          
- Retrieve the international and local format.
- Know the country where the number is registered.


curl -X POST \
'https://api-prd.kpn.com/communication/nexmo/number-insight/basic' \
  -H 'authorization: Bearer access_token' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'number=3162*******'

Number Insight Standard

You can use Nexmo's Number Insight Standard API to retrieve a user's landline or mobile number, including checking to see if it's registered to an operator. This can help you verify that a phone number is real and give you information on how to format the number.

The Number Insight Standard API is a synchronous, easy-to-use RESTful web service. For any phone number you can:
        
-  Retrieve the international and local format.
-  Know the country where the number is registered.
-  Detect the line type (mobile/landline/virtual number/premium/toll-free)
-  Detect mobile country code (MCC) and mobile network code (MNC)
-  Detect if the number is ported
-  Identify caller name (USA only)
-  Check if phone number is reachable


curl -X POST \
'https://api-prd.kpn.com/communication/nexmo/number-insight/standard' \
  -H 'authorization: Bearer access_token' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'number=3162*******'

Number Insight Advanced

You can use Nexmo's Number Insight Advanced API to retrieve a user's landline or mobile number, including checking to see if it's registered to an operator. This can help you verify that a phone number is real and give you information on how to format the number.
        
The Number Insight Advanced Async API is a synchronous, easy-to-use RESTful web service. For any phone number you can:
        
- Retrieve the international and local format.
- Know the country where the number is registered.
- Detect the line type (mobile/landline/virtual number/premium/toll-free)
- Detect mobile country code (MCC) and mobile network code (MNC)
- Detect if the number is ported
- Identify caller name (USA only) - see the CNAM guide for details
- Identify network when roaming
- Confirm that user's IP address is in the same location as their mobile phone
        
Be aware that the Advanced API does not give any information about landlines that has not already been given by the Standard API. For number insights about landlines, you should use the Standard API.


curl -X POST \
'https://api-prd.kpn.com/communication/nexmo/number-insight/advanced' \
  -H 'authorization: Bearer access_token' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'number=3162*******'

Number Insight Advanced Async

You can use Nexmo's Number Insight Async API to retrieve a user's landline or mobile number, including checking to see if it's registered to an operator. This can help you verify that a phone number is real and give you information on how to format the number.
        
The Number Insight Advanced Async API is an asynchronous web service that returns data to a webhook. For any phone number you can
        
- Retrieve the international and local format.
- Know the country where the number is registered.
- Line type detection (mobile/landline/virtual number/premium/toll-free)
- Detect mobile country code (MCC) and mobile network code (MNC)
- Detect if the number is ported
- Identify caller name (USA only)
- Identify network when roaming
- Confirm that user's IP address is in the same location as their mobile phone

Be aware that the Advanced API does not give any information about landlines that has not already been given by the Standard API. For number insights about landlines, you should use the Standard API.


curl -X POST \
'https://api-prd.kpn.com/communication/nexmo/number-insight/advanced/async' \
  -H 'authorization: Bearer access_token' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'number=3162*******' \
  -d 'callback=https://example.com/callback'