API reference

This defines Number Insight Standard API for the:

  • Request - ask for information about a phone number
  • Response - the information you requested about a phone number

Request

A Number Insight Standard API request looks like:

#!/bin/bash

base_url='https://api.nexmo.com'
version=''
action='/ni/standard/json?'
key='API_KEY'
secret='API_SECRET'
number='441632960960'

curl -X POST $base_url$version$action \
    -d api_key=$key \
    -d api_secret=$secret \
    -d number=$number

This request contains:

Base URL

All requests to Number Insight Standard API must contain:

  • https://api.nexmo.com/ni/standard
  • A response object: json or xml

Your base URL becomes either:

JSON XML
https://api.nexmo.com/ni/standard/json https://api.nexmo.com/ni/standard/xml

Parameters

The following table shows the parameters you use in the request:

Parameter Description Required
number A single phone number that you need insight about in national or international format. For example: to=441632960960 when sending to UK. The number may include any or all of the following: white space, -,+, (, ). Yes
country If number does not have a country code or is uncertain, set the two-character country code. This code must be in ISO 3166-1 alpha-2 format. For example, GB or US. If you set country and number is already in E.164 format, country must match the country code in number, No

Authentication information

If you are not using applications, you use the following parameters for calls to Nexmo API:

Parameter Description
api_key Your Key. For example: api_key=n3xm0rocks
api_secret Your Secret. For example: api_secret=12ab34cd

You find your Key and Secret in Dashboard.

If you are using signatures to verify your requests use:

Parameter Description
api_key Your Key. For example: api_key=n3xm0rocks
sig The hash of the request parameters in alphabetical order, a timestamp and the signature secret. For example: sig=TwoMenWentToMowWentTOMowAMeadowT

Security

To ensure privacy, you must use HTTPS for all Nexmo API requests.

Encoding

You submit all requests with a POST or GET call using UTF-8 encoding and URL encoded values. The expected Content-Type for POST is application/x-www-form-urlencoded. For calls to a JSON endpoint, we also support:

  • application/json
  • application/jsonrequest
  • application/x-javascript
  • text/json
  • text/javascript
  • text/x-javascript
  • text/x-json when posting parameters as a JSON object.

Response

Each request you make to Number Insight Standard API returns the:

  • Status and price of your request to Nexmo in JSON or XML format.
  • Information you asked for in the request.

Note: you are only charged for correctly submitted requests.

Each response comes:

Format

You set the response type using the Base URL. The following table shows example responses in JSON or XML:

JSON XML
{
    "status": 0,
    "status_message": "Success",
    "request_id": "34564b7d-df8b-47fd-aa07-b722602dd974",
    "international_format_number": "441632960960",
    "national_format_number": "01632 960960",
    "country_code": "GB",
    "country_code_iso3": "GBR",
    "country_name": "United Kingdom",
    "country_prefix": "44",
    "request_price": "0.00500000",
    "remaining_balance": "18.34408949",
    "current_carrier": {
        "network_code": "GB-FIXED-RESERVED",
        "name": "United Kingdom Landline Reserved",
        "country": "GB",
        "network_type": "landline"
    },
    "original_carrier": {
        "network_code": "GB-FIXED-RESERVED",
        "name": "United Kingdom Landline Reserved",
        "country": "GB",
        "network_type": "landline"
    },
    "ported": "assumed_not_ported"
}
<?xml version="1.0" encoding="UTF-8"?>
<lookup>
    <request_id>c76f20d7-3187-4af1-b64f-9c1393bc0098</request_id>
    <international_format_number>441632960960</international_format_number>
    <local_number
      country_code="GB"
      country_code_iso3="GBR"
      country_name="United Kingdom"
      country_prefix="44">01632 960960
    </local_number>
    <error code="0">Success</error>
    <request_price>0.00500000</request_price>
    <remaining_balance>18.33908949</remaining_balance>
    <current_carrier
      network_code="GB-FIXED-RESERVED"
      name="United Kingdom Landline Reserved"
      country="GB"
      network_type="landline"/>
    <original_carrier
      network_code="GB-FIXED-RESERVED"
      name="United Kingdom Landline Reserved"
      country="GB"
      network_type="landline"/>
    <ported>assumed_not_ported</ported>
</lookup>

Keys and Values

The response contains the following keys and values:

Key Value
status, status_message, error_text The status code and a description about your request. When status is 0 or 1, status_message is returned. For all other values, error_text.
Possible values are:
CodeText
0Success - request accepted for delivery by Nexmo.
1Busy - you have made more requests in the last second than are permitted by your Nexmo account. Please retry.
3Invalid - your request is incomplete and missing some mandatory parameters.
4Invalid credentials - the api_key or api_secret you supplied is either not valid or has been disabled.
5Internal Error - the format of the recipient address is not valid.
9Partner quota exceeded - your Nexmo account does not have sufficient credit to process this request.
Number Insight Standard and Advanced only
19Facility Not Allowed - your request makes use of a facility that is not enabled on your account.
43, 44, 45Live mobile lookup not returned. Not all return parameters are available.
999Request unparsable.
request_id The unique identifier for your request. This is a alphanumeric string up to 40 characters.
international_format_number The number in your request in International format.
national_format_number The number in your request in the format used by the country the number belongs to.
country_code Two character country code for number. This is in ISO 3166-1 alpha-2 format.
country_code_iso3 Three character country code for number. This is in ISO 3166-1 alpha-3 format.
country_name The full name of the country that number is registered in.
country_prefix The numeric prefix for the country that number is registered in.
request_price The amount in EUR charged to your account.
remaining_balance Your account balance in EUR after this request.
Not returned with Number Insight Advanced Async API.
ported If the user has changed carrier for number. Possible values are
  • unknown
  • ported
  • not_ported
  • assumed_not_ported
  • assumed_ported
The assumed status means that the information supplier has replied to the request but has not said explicitly that the number is ported.
current_carrier Information about the network number is currently connected to. Including:
KeyValue
network_codeThe https://en.wikipedia.org/wiki/Mobile_country_code for the carrier number is associated with. Unreal numbers are marked as unknown and the request is rejected altogether if the number is impossible according to the E.164 guidelines.
nameThe full name of the carrier that number is associated with.
countryThe country that number is associated with. This is in ISO 3166-1 alpha-2 format.
network_typeThe type of network that number is associated with. Possible values are:
  • mobile
  • landline
  • landline_premium
  • landline_tollfree
  • virtual
  • unknown
  • pager
original_carrier Information about the network number was initially connected to. Including:
KeyValue
network_codeThe https://en.wikipedia.org/wiki/Mobile_country_code for the carrier number is associated with. Unreal numbers are marked as 'unknown' and the request is rejected altogether if the number is impossible as per E.164 guidelines.
nameThe full name of the carrier that number is associated with.
countryThe country that number is associated with. This is in ISO 3166-1 alpha-2 format.
network_typeThe type of network that number is associated with. Possible values are:
  • mobile
  • landline
  • landline_premium
  • landline_tollfree
  • virtual
  • unknown
  • pager
Previous   Next