Welcome to Nexmo Developer

We are improving our Documentation, API references, learning resources & tooling to help you more effectively use our services. We want to help you find everything you need to integrate Nexmo APIs into your code.

As we start this transition, we’d love to hear from you with thoughts & suggestions. If you’ve got something, positive or negative, to tell us, please tell us using the feedback tool at the bottom of each guide or file an issue on GitHub. - Nexmo

Number Insight API Reference

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

Request

Getting information about a number with Nexmo's Number Verify API is easy. Simply sign up for an account  and replace the following variables in the example below:

Key Description
API_KEY You can find this in your account overview 
API_SECRET You can find this in your account overview 
NUMBER A single phone number that you need insight about in national or international format. The number may include any or all of the following: white space, -, +, (, ).
LEVEL Should be basic, standard or advanced. See features in the table below.
FORMAT Should be json, xml. 
curl "https://api.nexmo.com/ni/:LEVEL/:FORMAT" \
   -d "api_key=API_KEY" \
   -d "api_secret=API_SECRET" \
   -d "number=NUMBER"

Optional parameters

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

Parameter Description Required
country If a 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 and in upper case. 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.
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 an additional charge. Default value is false.

Response

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

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

Each response comes:

Format

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"
}

Keys and Values

The response contains the following keys and values:

Key Value Basic Standard Advanced
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.
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.
refund_price If there is an internal lookup error, the refund_price will reflect the lookup price. If cnam is requested for a non-US number the refund_price will reflect the cnam price. If both of these conditions occur, refund_price is the sum of the lookup price and cnam price.
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. Possible values
original_carrier Information about the network number was initially connected to. Possible values:
caller_name Full name of the person who owns the phone number. unknown if this information is not available. This parameter is only present if cnam had a value of true within the request.
first_name First name of the person who owns the phone number if the owner is an individual. This parameter is only present if cnam had a value of true within the request.
last_name Last name of the person who owns the phone number if the owner is an individual. This parameter is only present if cnam had a value of true within the request.
caller_type The value will be business if the owner of a phone number is a business. If the owner is an individual the value will be consumer. The value will be unknown if this information is not available. This parameter is only present if cnam had a value of true within the request.
lookup_outcome and lookup_outcome_message Shows if all information about a phone number has been returned. Possible values.
valid_number Does number exist. Possible values are unknown, valid, not_valid. This is applicable to mobile numbers only.
reachable Can you call number now. Possible values are: unknown, reachable, undeliverable, absent, bad_number, blacklisted. This is applicable to mobile numbers only.
roaming Information about the roaming status for number. Possible values. This is applicable to mobile numbers only.
ip The ip address you specified in the request. This field is blank if you did not specify ip.
ip_warnings Warning levels for ip: unknown or no_warning
ip_match_level The match status between ip and number. Possible values are. Country Level or Mismatch. This value is only returned if you set ip in the request.
ip_country The country that ip is allocated to. This value is only returned if you set ip in the request.
Code Text
0 Success - request accepted for delivery by Nexmo.
1 Busy - you have made more requests in the last second than are permitted by your Nexmo account. Please retry.
3 Invalid - your request is incomplete and missing some mandatory parameters.
4 Invalid credentials - the api_key or api_secret you supplied is either not valid or has been disabled.
5 Internal Error - the format of the recipient address is not valid.
9 Partner quota exceeded - your Nexmo account does not have sufficient credit to process this request.

Standard and Advanced only

Code Text
19 Facility Not Allowed - your request makes use of a facility that is not enabled on your account.
43, 44, 45 Live mobile lookup not returned. Not all return parameters are available.
999 Request unparseable.
Key Value
network_code The https://en.wikipedia.org/wiki/Mobile_country_code  for the carriernumber is associated with. Unreal numbers are marked asunknown and the request is rejected altogether if the number is impossible according to the E.164 guidelines.
name The full name of the carrier that number is associated with.
country The country that number is associated with. This is in ISO 3166-1 alpha-2 format.
network_type The type of network that number is associated with. Possible values are: mobile, landline, landline_premium, landline_tollfree, virtual, unknown & pager
Key Value
network_code The https://en.wikipedia.org/wiki/Mobile_country_code  for the carriernumber is associated with. Unreal numbers are marked asunknown and the request is rejected altogether if the number is impossible according to the E.164 guidelines.
name The full name of the carrier that number is associated with.
country The country that number is associated with. This is in ISO 3166-1 alpha-2 format.
network_type The type of network that number is associated with. Possible values are: mobile, landline, landline_premium, landline_tollfree, virtual, unknown & pager
Code Text
0 Success
1 Partial success - some fields populated
2 Failed
Code Meaning
status Is number outside its home carrier network. Possible values are unknown, roaming, not_roaming.
roaming_country_code If number is roaming, this is the code  of the country number is roaming in.
roaming_network_code If number is roaming, this is the id of the carrier network number is roaming in.
roaming_network_name If number is roaming, this is the name of the carrier network number is roaming in.