Number Insight API

Nexmo's Number Insight API delivers real-time intelligence about the validity, reachability and roaming status of a phone number and tells you how to format the number correctly in your application. There are three levels of Number Insight API available: Basic, Standard and Advanced. The advanced API is available asynchronously as well as synchronously.

Download OpenAPI 3 Definition
Improve this specification

Basic Number Insight

Provides basic number insight information about a number.

Note that this endpoint also supports POST requests.

GET https://api.nexmo.com/ni/basic/:format

Path Parameters

Key Description Example Default
format
Required | string

The format of the response


Must be one of: json or xml 		json None

Query Parameter

Key Description Example Default
api_key
apiKey

You can find your API key in your account overview

 abc123 None
api_secret
apiKey

You can find your API secret in your account overview

 abc123 None
number
Required | string

A single phone number that you need insight about in national or international format.

 447700900000 None
country
string

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.

 GB None

View response field descriptions

Response Fields

Field Description
status
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.
One of: 0, 1, 3, 4, 5 or 9
status_message

The status description of your request.
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.
Field Description
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.
local_number

An object containing the number in your request in the format used by the country the number belongs to.

Field Description
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.
number

The number in your request in the format used by the country the number belongs to.
error

The error code and status of your request

Field Description
code

The status code
status_text

The status description of your request.

 
{
  "status": 0,
  "status_message": "Success",
  "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "international_format_number": "447700900000",
  "national_format_number": "07700 900000",
  "country_code": "GB",
  "country_code_iso3": "GBR",
  "country_name": "United Kingdom",
  "country_prefix": "44"
}
<?xml version="1.0" encoding="UTF-8"?>
<format>
  <request_id>aaaaaaaa-bbbb-cccc-dddd-0123456789ab</request_id>
  <international_format_number>447700900000</international_format_number>
  <local_number country_code="GB" country_code_iso3="GBR" country_name="United Kingdom" country_prefix="44">
    07700 900000
  </local_number>
  <error code="0">Success</error>
</format>

Standard Number Insight

Provides standard number insight information about a number.

Note that this endpoint also supports POST requests.

GET https://api.nexmo.com/ni/standard/:format

Path Parameters

Key Description Example Default
format
Required | string

The format of the response


Must be one of: json or xml 		json None

Query Parameter

Key Description Example Default
api_key
apiKey

You can find your API key in your account overview

 abc123 None
api_secret
apiKey

You can find your API secret in your account overview

 abc123 None
number
Required | string

A single phone number that you need insight about in national or international format.

 447700900000 None
country
string

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.

 GB None
cnam
boolean

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.

 true false

View response field descriptions

Response Fields

Field Description
status
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.
One of: 0, 1, 3, 4, 5 or 9
status_message

The status description of your request.
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.
current_carrier

Information about the network number is currently connected to.

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

One of: mobile, landline, landline_premium, landline_tollfree, virtual, unknown or pager
original_carrier

Information about the network number is currently connected to.

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

One of: mobile, landline, landline_premium, landline_tollfree, virtual, unknown or pager
ported

If the user has changed carrier for number. The assumed status means that the information supplier has replied to the request but has not said explicitly that the number is ported.

One of: unknown, ported, not_ported, assumed_not_ported or assumed_ported
roaming

Information about the roaming status for number. This is applicable to mobile numbers only.

Field Description
status

Is number outside its home carrier network.

One of: unknown, roaming or 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.
caller_identity

Information about the network number is currently connected to.

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

One of: business, consumer or unknown
caller_name

Full name of the person or business 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_name

Full name of the person or business 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.
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.
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.
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.

One of: business, consumer or unknown
Field Description
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.
local_number

An object containing the number in your request in the format used by the country the number belongs to.

Field Description
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.
number

The number in your request in the format used by the country the number belongs to.
error

The error code and status of your request

Field Description
code

The status code
status_text

The status description of your request.
request_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.
current_carrier

Information about the network number is currently connected to.

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

One of: mobile, landline, landline_premium, landline_tollfree, virtual, unknown or pager
original_carrier

Information about the network number is currently connected to.

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

One of: mobile, landline, landline_premium, landline_tollfree, virtual, unknown or pager
ported

If the user has changed carrier for number. The assumed status means that the information supplier has replied to the request but has not said explicitly that the number is ported

Field Description
ported_message

If the user has changed carrier for number. The assumed status means that the information supplier has replied to the request but has not said explicitly that the number is ported.

One of: unknown, ported, not_ported, assumed_not_ported or assumed_ported
roaming

Information about the roaming status for number. This is applicable to mobile numbers only.

Field Description
status One of: unknown
caller_identity

Contains details of the number owner, if cnam was set to true in the request.

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

One of: business, consumer or unknown
caller-name

Full name of the person or business 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_name

Full name of the person or business 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.
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.
firs_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.
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.

One of: business, consumer or unknown 
{
  "status": 0,
  "status_message": "Success",
  "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "international_format_number": "447700900000",
  "national_format_number": "07700 900000",
  "country_code": "GB",
  "country_code_iso3": "GBR",
  "country_name": "United Kingdom",
  "country_prefix": "44",
  "request_price": "0.04000000",
  "refund_price": "0.01500000",
  "remaining_balance": "1.23456789",
  "current_carrier": {
    "network_code": "12345",
    "name": "Acme Inc",
    "country": "GB",
    "network_type": "mobile"
  },
  "original_carrier": {
    "network_code": "12345",
    "name": "Acme Inc",
    "country": "GB",
    "network_type": "mobile"
  },
  "ported": "not_ported",
  "roaming": {
    "status": "roaming",
    "roaming_country_code": "US",
    "roaming_network_code": 12345,
    "roaming_network_name": "Acme Inc"
  },
  "caller_identity": {
    "caller_type": "consumer",
    "caller_name": "John Smith",
    "first_name": "John",
    "last_name": "Smith"
  },
  "caller_name": "John Smith",
  "last_name": "Smith",
  "first_name": "John",
  "caller_type": "consumer"
}
<?xml version="1.0" encoding="UTF-8"?>
<lookup>
  <request_id>aaaaaaaa-bbbb-cccc-dddd-0123456789ab</request_id>
  <international_format_number>447700900000</international_format_number>
  <local_number country_code="GB" country_code_iso3="GBR" country_name="United Kingdom" country_prefix="44">
    07700 900000
  </local_number>
  <error code="0">Success</error>
  <request_price>0.01500000</request_price>
  <remaining_balance>1.23456789</remaining_balance>
  <current_carrier network_code="12345" name="Acme Inc" country="GB" network_type="mobile">
  </current_carrier>
  <original_carrier network_code="12345" name="Acme Inc" country="GB" network_type="mobile">
  </original_carrier>
  <ported>not_ported</ported>
  <roaming status="unknown">
  </roaming>
  <caller_identity caller-type="consumer" caller-name="John Smith" first-name="John" last-name="Smith">
    <caller_name>John Smith</caller_name>
    <last_name>Smith</last_name>
    <firs_name>John</firs_name>
    <caller_type>consumer</caller_type>
  </caller_identity>
</lookup>

Advanced Number Insight (sync)

Provides advanced number insight information about a number synchronously, in the same way that the basic and standard endpoints do.

Note that this endpoint also supports POST requests.

GET https://api.nexmo.com/ni/advanced/:format

Path Parameters

Key Description Example Default
format
Required | string

The format of the response


Must be one of: json or xml 		json None

Query Parameter

Key Description Example Default
api_key
apiKey

You can find your API key in your account overview

 abc123 None
api_secret
apiKey

You can find your API secret in your account overview

 abc123 None
number
Required | string

A single phone number that you need insight about in national or international format.

 447700900000 None
country
string

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.

 GB None
cnam
boolean

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.

 true false
ip
string

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.

 123.0.0.255 None

View response field descriptions

Response Fields

Field Description
status
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.
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.
One of: 0, 1, 3, 4, 5, 9, 19, 43, 44, 45 or 999
status_message

The status description of your request.
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.
current_carrier

Information about the network number is currently connected to.

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

One of: mobile, landline, landline_premium, landline_tollfree, virtual, unknown or pager
original_carrier

Information about the network number is currently connected to.

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

One of: mobile, landline, landline_premium, landline_tollfree, virtual, unknown or pager
ported

If the user has changed carrier for number. The assumed status means that the information supplier has replied to the request but has not said explicitly that the number is ported.

One of: unknown, ported, not_ported, assumed_not_ported or assumed_ported
roaming

Information about the roaming status for number. This is applicable to mobile numbers only.

Field Description
status

Is number outside its home carrier network.

One of: unknown, roaming or 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.
caller_identity

Information about the network number is currently connected to.

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

One of: business, consumer or unknown
caller_name

Full name of the person or business 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.
lookup_outcome

Shows if all information about a phone number has been returned. Possible values:

Code Text
0 Success
1 Partial success - some fields populated
2 Failed
One of: 0, 1 or 2
lookup_outcome_message

Shows if all information about a phone number has been returned.
valid_number

Does number exist. unknown means the number could not be validated. valid means the number is valid. not_valid means the number is not valid. inferred_not_valid means that the number could not be determined as valid or invalid via an external system and the best guess is that the number is invalid. This is applicable to mobile numbers only.

One of: unknown, valid, not_valid, inferred or inferred_not_valid
reachable

Can you call number now. This is applicable to mobile numbers only.

One of: unknown, reachable, undeliverable, absent, bad_number or blacklisted
ip

Information about the provided IP address

Field Description
address

The ip address you specified in the request.
ip_match_level

The match status between ip and number parameters.

One of: country or mismatch
ip_country

The country that ip is allocated to.
ip_city

The city that ip is allocated to.
ip_warnings

This property is deprecated and can safely be ignored.
Field Description
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.
local_number

An object containing the number in your request in the format used by the country the number belongs to.

Field Description
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.
number

The number in your request in the format used by the country the number belongs to.
error

The error code and status of your request

Field Description
code

The status code
status_text

The status description of your request.
request_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.
current_carrier

Information about the network number is currently connected to.

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

One of: mobile, landline, landline_premium, landline_tollfree, virtual, unknown or pager
original_carrier

Information about the network number is currently connected to.

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

One of: mobile, landline, landline_premium, landline_tollfree, virtual, unknown or pager
ported

If the user has changed carrier for number. The assumed status means that the information supplier has replied to the request but has not said explicitly that the number is ported.

Field Description
ported_message

If the user has changed carrier for number. The assumed status means that the information supplier has replied to the request but has not said explicitly that the number is ported.

One of: unknown, ported, not_ported, assumed_not_ported or assumed_ported
caller_identity

Contains details of the number owner, if cnam was set to true in the request.

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

One of: business, consumer or unknown
caller-name

Full name of the person or business 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_name

Full name of the person or business 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.
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.
firs_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.
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.

One of: business, consumer or unknown
lookup_outcome

An object indicating whether all information about a phone number has been returned.

Field Description
code

Shows if all information about a phone number has been returned. Possible values:

Code Text
0 Success
1 Partial success - some fields populated
2 Failed
One of: 0, 1 or 2
lookup_outcome_message

Shows if all information about a phone number has been returned.
reachable

Can you call number now. This is applicable to mobile numbers only.

One of: unknown, reachable, undeliverable, absent, bad_number or blacklisted
roaming

Information about the roaming status for number. This is applicable to mobile numbers only.

Field Description
status

Is number outside its home carrier network.

One of: unknown, roaming or 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.
ip

Information about the provided IP address

Field Description
address

The ip address you specified in the request.
ip_match_level

The match status between ip and number parameters.

One of: country or mismatch
ip_country

The country that ip is allocated to.
ip_city

The city that ip is allocated to.
valid_number

Does number exist. unknown means the number could not be validated. valid means the number is valid. not_valid means the number is not valid. inferred_not_valid means that the number could not be determined as valid or invalid via an external system and the best guess is that the number is invalid. This is applicable to mobile numbers only.

One of: unknown, valid, not_valid or inferred_not_valid
ip_warnings

This property is deprecated and can safely be ignored.

 
{
  "status": 0,
  "status_message": "Success",
  "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "international_format_number": "447700900000",
  "national_format_number": "07700 900000",
  "country_code": "GB",
  "country_code_iso3": "GBR",
  "country_name": "United Kingdom",
  "country_prefix": "44",
  "request_price": "0.04000000",
  "refund_price": "0.01500000",
  "remaining_balance": "1.23456789",
  "current_carrier": {
    "network_code": "12345",
    "name": "Acme Inc",
    "country": "GB",
    "network_type": "mobile"
  },
  "original_carrier": {
    "network_code": "12345",
    "name": "Acme Inc",
    "country": "GB",
    "network_type": "mobile"
  },
  "ported": "not_ported",
  "roaming": {
    "status": "roaming",
    "roaming_country_code": "US",
    "roaming_network_code": 12345,
    "roaming_network_name": "Acme Inc"
  },
  "caller_identity": {
    "caller_type": "consumer",
    "caller_name": "John Smith",
    "first_name": "John",
    "last_name": "Smith"
  },
  "lookup_outcome": "0",
  "lookup_outcome_message": "Success",
  "valid_number": "valid",
  "reachable": "reachable",
  "ip": {
    "address": "123.0.0.255",
    "ip_match_level": "country",
    "ip_country": "GB",
    "ip_city": "London"
  },
  "ip_warnings": "unknown"
}
<?xml version="1.0" encoding="UTF-8"?>
<lookup>
  <request_id>aaaaaaaa-bbbb-cccc-dddd-0123456789ab</request_id>
  <international_format_number>447700900000</international_format_number>
  <local_number country_code="GB" country_code_iso3="GBR" country_name="United Kingdom" country_prefix="44">
    07700 900000
  </local_number>
  <error code="0">Success</error>
  <request_price>0.01500000</request_price>
  <remaining_balance>1.23456789</remaining_balance>
  <current_carrier network_code="12345" name="Acme Inc" country="GB" network_type="mobile">
  </current_carrier>
  <original_carrier network_code="12345" name="Acme Inc" country="GB" network_type="mobile">
  </original_carrier>
  <ported>not_ported</ported>
  <caller_identity caller-type="consumer" caller-name="John Smith" first-name="John" last-name="Smith">
  </caller_identity>
  <caller_name>John Smith</caller_name>
  <last_name>Smith</last_name>
  <firs_name>John</firs_name>
  <caller_type>consumer</caller_type>
  <lookup_outcome code="0">Success</lookup_outcome>
  <reachable>reachable</reachable>
  <roaming status="roaming" roaming_country_code="US" roaming_network_code="12345" roaming_network_name="Acme Inc">
  </roaming>
  <ip address="123.0.0.255" ip_match_level="country" ip_country="GB" ip_city="London">
  </ip>
  <valid_number>valid</valid_number>
  <ip_warnings>unknown</ip_warnings>
</lookup>

Advanced Number Insight (async)

Provides advanced number insight number information asynchronously using the URL specified in the callback parameter.

Note that this endpoint also supports POST requests.

GET https://api.nexmo.com/ni/advanced/async/:format

Path Parameters

Key Description Example Default
format
Required | string

The format of the response


Must be one of: json or xml 		json None

Query Parameter

Key Description Example Default
api_key
apiKey

You can find your API key in your account overview

 abc123 None
api_secret
apiKey

You can find your API secret in your account overview

 abc123 None
callback
Required | string | (uriref)

The callback URL

 https://example.com/callback None
number
Required | string

A single phone number that you need insight about in national or international format.

 447700900000 None
country
string

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.

 GB None
cnam
boolean

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.

 true false
ip
string

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.

 123.0.0.255 None

View response field descriptions

Response Fields

Field Description
request_id

The unique identifier for your request. This is a alphanumeric string up to 40 characters.
number

The number in your request
remaining_balance

Your account balance in EUR after this request. Not returned with Number Insight Advanced Async API.
request_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.
status
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.
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.
One of: 0, 1, 3, 4, 5, 9, 19, 43, 44, 45 or 999
Field Description
request_id

The unique identifier for your request. This is a alphanumeric string up to 40 characters.
number

The number in your request
remaining_balance

Your account balance in EUR after this request. Not returned with Number Insight Advanced Async API.
request_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.
status
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.
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.
One of: 0, 1, 3, 4, 5, 9, 19, 43, 44, 45 or 999 
{
  "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "number": "447700900000",
  "remaining_balance": "1.23456789",
  "request_price": "0.01500000",
  "status": 0
}
<?xml version="1.0" encoding="UTF-8"?>
<lookup>
  <requestId>aaaaaaaa-bbbb-cccc-dddd-0123456789ab</requestId>
  <number>447700900000</number>
  <remainingBalance>1.23456789</remainingBalance>
  <requestPrice>0.01500000</requestPrice>
  <status>0</status>
</lookup>

Asynchronous response Callback

Contains the response to your

POST https://example.com /webhooks/event

Request body application/json

Key Description Example
status
Required | integer
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.
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.

One of: 0, 1, 3, 4, 5, 9, 19, 43, 44, 45 or 999 		0
status_message
Required | string

The status description of your request.

 Success
request_id
Required | string

The unique identifier for your request. This is a alphanumeric string up to 40 characters.

 aaaaaaaa-bbbb-cccc-dddd-0123456789ab
international_format_number
Required | string

The number in your request in international format.

 447700900000
national_format_number
Required | string

The number in your request in the format used by the country the number belongs to.

 07700 900000
country_code
Required | string

Two character country code for number. This is in ISO 3166-1 alpha-2 format.

 GB
country_code_iso3
Required | string

Three character country code for number. This is in ISO 3166-1 alpha-3 format.

 GBR
country_name
Required | string

The full name of the country that number is registered in.

 United Kingdom
country_prefix
Required | string

The numeric prefix for the country that number is registered in.

 44
request_price
number

The amount in EUR charged to your account.

 0.04000000
refund_price
number

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.

 0.01500000
remaining_balance
number

Your account balance in EUR after this request. Not returned with Number Insight Advanced Async API.

 1.23456789
current_carrier
object

Information about the network number is currently connected to.
Key Description Example
network_code
| Attribute string

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.

 12345
name
| Attribute string

The full name of the carrier that number is associated with.

 Acme Inc
country
| Attribute string

The country that number is associated with. This is in ISO 3166-1 alpha-2 format.

 GB
network_type
| Attribute string

The type of network that number is associated with.


One of: mobile, landline, landline_premium, landline_tollfree, virtual, unknown or pager 		mobile
original_carrier
object

Information about the network number is currently connected to.
Key Description Example
network_code
| Attribute string

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.

 12345
name
| Attribute string

The full name of the carrier that number is associated with.

 Acme Inc
country
| Attribute string

The country that number is associated with. This is in ISO 3166-1 alpha-2 format.

 GB
network_type
| Attribute string

The type of network that number is associated with.


One of: mobile, landline, landline_premium, landline_tollfree, virtual, unknown or pager 		mobile
ported
string

If the user has changed carrier for number. The assumed status means that the information supplier has replied to the request but has not said explicitly that the number is ported.


One of: unknown, ported, not_ported, assumed_not_ported or assumed_ported 		not_ported
roaming
object
Key Description Example
status
| Attribute string

Is number outside its home carrier network.


One of: unknown, roaming or not_roaming 		roaming
roaming_country_code
| Attribute string

If number is roaming, this is the code of the country number is roaming in.

 US
roaming_network_code
| Attribute string

If number is roaming, this is the id of the carrier network number is roaming in.

 12345
roaming_network_name
| Attribute string

If number is roaming, this is the name of the carrier network number is roaming in.

 Acme Inc
caller_identity
object
Key Description Example
caller_type
string

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.


One of: business, consumer or unknown 		consumer
caller_name
string

Full name of the person or business 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.

 John Smith
first_name
string

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.

 John
last_name
string

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.

 Smith
lookup_outcome
integer

Shows if all information about a phone number has been returned. Possible values:

Code Text
0 Success
1 Partial success - some fields populated
2 Failed

One of: 0, 1 or 2 		0
lookup_outcome_message
string

Shows if all information about a phone number has been returned.

 Success
valid_number
string

Does number exist. unknown means the number could not be validated. valid means the number is valid. not_valid means the number is not valid. inferred_not_valid means that the number could not be determined as valid or invalid via an external system and the best guess is that the number is invalid. This is applicable to mobile numbers only.


One of: unknown, valid, not_valid, inferred or inferred_not_valid 		valid
reachable
string

Can you call number now. This is applicable to mobile numbers only.


One of: unknown, reachable, undeliverable, absent, bad_number or blacklisted 		reachable
ip
object
Key Description Example
address
| Attribute string

The ip address you specified in the request.

 123.0.0.255
ip_match_level
| Attribute string

The match status between ip and number parameters.


One of: country or mismatch 		country
ip_country
| Attribute string

The country that ip is allocated to.

 GB
ip_city
| Attribute string

The city that ip is allocated to.

 London
ip_warnings
string

This property is deprecated and can safely be ignored.

 unknown
Request model
{
  "status": 0,
  "status_message": "Success",
  "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "international_format_number": "447700900000",
  "national_format_number": "07700 900000",
  "country_code": "GB",
  "country_code_iso3": "GBR",
  "country_name": "United Kingdom",
  "country_prefix": "44",
  "request_price": "0.04000000",
  "refund_price": "0.01500000",
  "remaining_balance": "1.23456789",
  "current_carrier": {
    "network_code": "12345",
    "name": "Acme Inc",
    "country": "GB",
    "network_type": "mobile"
  },
  "original_carrier": {
    "network_code": "12345",
    "name": "Acme Inc",
    "country": "GB",
    "network_type": "mobile"
  },
  "ported": "not_ported",
  "roaming": {
    "status": "roaming",
    "roaming_country_code": "US",
    "roaming_network_code": 12345,
    "roaming_network_name": "Acme Inc"
  },
  "caller_identity": {
    "caller_type": "consumer",
    "caller_name": "John Smith",
    "first_name": "John",
    "last_name": "Smith"
  },
  "lookup_outcome": "0",
  "lookup_outcome_message": "Success",
  "valid_number": "valid",
  "reachable": "reachable",
  "ip": {
    "address": "123.0.0.255",
    "ip_match_level": "country",
    "ip_country": "GB",
    "ip_city": "London"
  },
  "ip_warnings": "unknown"
}
<?xml version="1.0" encoding="UTF-8"?>
<lookup>
  <request_id>aaaaaaaa-bbbb-cccc-dddd-0123456789ab</request_id>
  <international_format_number>447700900000</international_format_number>
  <local_number country_code="GB" country_code_iso3="GBR" country_name="United Kingdom" country_prefix="44">
    07700 900000
  </local_number>
  <error code="0">Success</error>
  <request_price>0.01500000</request_price>
  <remaining_balance>1.23456789</remaining_balance>
  <current_carrier network_code="12345" name="Acme Inc" country="GB" network_type="mobile">
  </current_carrier>
  <original_carrier network_code="12345" name="Acme Inc" country="GB" network_type="mobile">
  </original_carrier>
  <ported>not_ported</ported>
  <caller_identity caller-type="consumer" caller-name="John Smith" first-name="John" last-name="Smith">
  </caller_identity>
  <caller_name>John Smith</caller_name>
  <last_name>Smith</last_name>
  <firs_name>John</firs_name>
  <caller_type>consumer</caller_type>
  <lookup_outcome code="0">Success</lookup_outcome>
  <reachable>reachable</reachable>
  <roaming status="roaming" roaming_country_code="US" roaming_network_code="12345" roaming_network_name="Acme Inc">
  </roaming>
  <ip address="123.0.0.255" ip_match_level="country" ip_country="GB" ip_city="London">
  </ip>
  <valid_number>valid</valid_number>
  <ip_warnings>unknown</ip_warnings>
</lookup>