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 Insight 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.
`ip`	The IP address of the user. If supplied, we will compare this to the country the user's phone is located in and return an error if it does not match.

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:

In a specific Format
With Keys and values

Format

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

Basic
Standard
Advanced

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

<format>
  <request_id>d781445d-233a-4ae8-a6a4-1d072e17179a</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>
</format>

JSON
XML

{
    "status": 0,
    "status_message": "Success",
    "request_id": "34564b7d-df8b-47fd-aa07-b722602dd974",
    "international_format_number": "14155550100",
    "national_format_number": "(415) 555-0100",
    "country_code": "US",
    "country_code_iso3": "USA",
    "country_name": "United States of America",
    "country_prefix": "1",
    "request_price": "0.015",
    "remaining_balance": "18.34408949",
    "current_carrier": {
        "network_code": "US-FIXED",
        "name": "United States of America Landline",
        "country": "US",
        "network_type": "landline"
    },
    "original_carrier": {
        "network_code": "US-FIXED",
        "name": "United States of America Landline",
        "country": "US",
        "network_type": "landline"
    },
    "ported": "assumed_not_ported",
    "caller_name": "Jane Doe",
    "last_name": "Doe",
    "first_name": "Jane",
    "caller_type": "consumer"
}

<?xml version="1.0" encoding="UTF-8"?>
<lookup>
    <request_id>c76f20d7-3187-4af1-b64f-9c1393bc0098</request_id>
    <international_format_number>14155550100</international_format_number>
    <local_number
      country_code="US"
      country_code_iso3="USA"
      country_name="United States of America"
      country_prefix="1">(512) 555-5555
    </local_number>
    <error code="0">Success</error>
    <request_price>0.015</request_price>
    <remaining_balance>18.33908949</remaining_balance>
    <current_carrier
      network_code="US-FIXED"
      name="United States of America Landline"
      country="US"
      network_type="landline"/>
    <original_carrier
      network_code="US-FIXED"
      name="United States of America Landline"
      country="US"
      network_type="landline"/>
    <ported>assumed_not_ported</ported>
    <caller_name>Jane Doe</caller_name>
    <last_name>Doe</last_name>
    <first_name>Jane</first_name>
    <caller_type>consumer</caller_type>
</lookup>

JSON
XML

{
    "status": 0,
    "status_message": "Success",
    "lookup_outcome": 1,
    "lookup_outcome_message": "Partial success - some fields populated",
    "request_id": "0c082a69-85df-4bbc-aae6-ee998e17e5a4",
    "international_format_number": "14155550100",
    "national_format_number": "(415) 555-0100",
    "country_code": "US",
    "country_code_iso3": "USA",
    "country_name": "United States of America",
    "country_prefix": "1",
    "request_price": "0.04",
    "remaining_balance": "18.30908949",
    "current_carrier": {
        "network_code": "US-FIXED",
        "name": "United States of America Landline",
        "country": "US",
        "network_type": "landline"
    },
    "original_carrier": {
        "network_code": "US-FIXED",
        "name": "United States of America Landline",
        "country": "US",
        "network_type": "landline"
    },
    "valid_number": "valid",
    "reachable": "unknown",
    "ported": "assumed_not_ported",
    "roaming": {"status": "not_roaming"},
    "caller_name": "Jane Doe",
    "last_name": "Doe",
    "first_name": "Jane",
    "caller_type": "consumer"
}

<?xml version="1.0" encoding="UTF-8"?>
<lookup>
  <request_id>51cbf7f1-2ae3-4b4c-a611-21f4273b93b0</request_id>
  <international_format_number>14155550100</international_format_number>
  <lookup_outcome code="1">Partial success - some fields populated</lookup_outcome>
  <local_number
    country_code="US"
    country_code_iso3="USA"
    country_name="United States of America"
    country_prefix="1">(415) 555-0100</local_number>
  <error code="0">Success</error>
  <request_price>0.03000000</request_price>
  <remaining_balance>18.27908949</remaining_balance>
  <current_carrier
    network_code="US-FIXED"
    name="United States of America Landline"
    country="US"
    network_type="landline" />
  <original_carrier
    network_code="US-FIXED"
    name="United States of America Landline"
    country="US"
    network_type="landline" />
  <valid_number>valid</valid_number>
  <reachable>unknown</reachable>
  <ported>assumed_not_ported</ported>
  <roaming status="not_roaming" />
  <caller_name>Jane Doe</caller_name>
  <last_name>Doe</last_name>
  <first_name>Jane</first_name>
  <caller_type>consumer</caller_type>
</lookup>

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 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.
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 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.
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.