API reference

This defines the Number Insight Basic API:

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


A Number Insight Basic API request looks like:



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 Basic API must contain:

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

Your base URL becomes either:

https://api.nexmo.com/ni/basic/json https://api.nexmo.com/ni/basic/xml


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
cnam Indicates if the name of the person who owns the phone number should be looked up and returned in the response. Set to true to receive phone number owner name in the response. This features is available for US numbers only and incurs and additional charge. Default value is false. 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


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


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.


The response to each request you make to Number Insight Basic API returns the:

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

Each response comes:


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

    "status": 0,
    "status_message": "Success",
    "request_id": "d79c3d82-e2ee-46ff-972a-97b76be419cb",
    "international_format_number": "441632960960",
    "national_format_number": "01632 960960",
    "country_code": "GB",
    "country_code_iso3": "GBR",
    "country_name": "United Kingdom",
    "country_prefix": "44"
    country_name="United Kingdom"
    country_prefix="44">01632 960960
  <error code="0">Success</error>

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:
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.
Previous   Next