Number Insight API

Nexmo's Number Insight API provides details about the validity, reachability and roaming status of a phone number, as well as giving you details on how to format the number properly 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

Number Insight

The Number Insight object contains information about the request and details of the phone number information has been requested about.

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

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.

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

The status description of your request.
request_id
Required | string

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

The number in your request in international format.
national_format_number
Required | string

The number in your request in the format used by the country the number belongs to.
country_code
Required | string

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

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

The full name of the country that number is registered in.
country_prefix
Required | string

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

The amount in EUR charged to your account.
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.
remaining_balance
number

Your account balance in EUR after this request. Not returned with Number Insight Advanced Async API.
current_carrier
object
Key Description
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.
name
Attribute | string

The full name of the carrier that number is associated with.
country
Attribute | string

The country that number is associated with. This is in ISO 3166-1 alpha-2 format.
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
original_carrier
object
Key Description
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.
name
Attribute | string

The full name of the carrier that number is associated with.
country
Attribute | string

The country that number is associated with. This is in ISO 3166-1 alpha-2 format.
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
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
roaming
object
Key Description
status
Attribute | string

Is number outside its home carrier network.


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

If number is roaming, this is the code  of the country number is roaming in.
roaming_network_code
Attribute | string

If number is roaming, this is the id of the carrier network number is roaming in.
roaming_network_name
Attribute | string

If number is roaming, this is the name of the carrier network number is roaming in.
caller_identity
object
Key Description
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
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.
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.
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.
subscription_type
string

None
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.
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.
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.
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
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
lookup_outcome_message
string

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

Does number exist. This is applicable to mobile numbers only.


One of: unknown, valid or not_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
ip
object
Key Description
address
Attribute | string

The ip address you specified in the request.
ip_match_level
Attribute | string

The match status between ip and number parameters.


One of: country or mismatch
ip_country
Attribute | string

The country that ip is allocated to.
ip_city
Attribute | string

The city that ip is allocated to.
ip_warnings
string

Warning levels for ip


One of: unknown or no_warning
Key Description
request_id
string

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

The number in your request in international format.
local_number
object
Key Description
country_code
Attribute | string

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

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

The full name of the country that number is registered in.
country_prefix
Attribute | string

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

The number in your request in the format used by the country the number belongs to.
error
object
Key Description
code
Attribute | string

The status code
status_text
Value | string

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

Your account balance in EUR after this request. Not returned with Number Insight Advanced Async API.
current_carrier
object
Key Description
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.
name
Attribute | string

The full name of the carrier that number is associated with.
country
Attribute | string

The country that number is associated with. This is in ISO 3166-1 alpha-2 format.
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
original_carrier
object
Key Description
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.
name
Attribute | string

The full name of the carrier that number is associated with.
country
Attribute | string

The country that number is associated with. This is in ISO 3166-1 alpha-2 format.
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
ported

None
cnam

None
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.
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.
firs_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.
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
lookup_outcome
object
Key Description
code
Attribute |

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
Value | string

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

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


One of: unknown, reachable, undeliverable, absent, bad_number or blacklisted
roaming
object
Key Description
status
Attribute | string

Is number outside its home carrier network.


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

If number is roaming, this is the code  of the country number is roaming in.
roaming_network_code
Attribute | string

If number is roaming, this is the id of the carrier network number is roaming in.
roaming_network_name
Attribute | string

If number is roaming, this is the name of the carrier network number is roaming in.
ip
object
Key Description
address
Attribute | string

The ip address you specified in the request.
ip_match_level
Attribute | string

The match status between ip and number parameters.


One of: country or mismatch
ip_country
Attribute | string

The country that ip is allocated to.
ip_city
Attribute | string

The city that ip is allocated to.
valid_number
string

Does number exist. This is applicable to mobile numbers only.


One of: unknown, valid or not_valid
ip_warnings
string

Warning levels for ip


One of: unknown or no_warning
Example 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",
    "subscription_type": "unknown"
  },
  "caller_name": "John Smith",
  "last_name": "Smith",
  "first_name": "John",
  "caller_type": "consumer",
  "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": "no_warning"
}
Example Model
  <local_number country_code="GB" country_code_iso3="GBR" country_name="United Kingdom" country_prefix="44">
    07700 900000
  </local_number>

Synchronously get information about a phone number

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

Path Parameters

Key Description Example Default
level
Required | string

The level of request you wish to make.


Must be one of: basic, standard or advanced 		standard None
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
string

You can find your API key in your account overview 

abc123 None
api_secret
string

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.

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

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.
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
original_carrier
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.
roaming
caller_identity
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.
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.

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.
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
original_carrier
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.
roaming
caller_identity
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.
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
lookup_outcome_message

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

Does number exist. This is applicable to mobile numbers only.
reachable

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

Warning levels for ip
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.
error 
{
  "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"
}
{
  "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",
    "subscription_type": "unknown"
  },
  "caller_name": "John Smith",
  "last_name": "Smith",
  "first_name": "John",
  "caller_type": "consumer"
}
{
  "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",
    "subscription_type": "unknown"
  },
  "caller_name": "John Smith",
  "last_name": "Smith",
  "first_name": "John",
  "caller_type": "consumer",
  "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": "no_warning"
}
  <local_number country_code="GB" country_code_iso3="GBR" country_name="United Kingdom" country_prefix="44">
    07700 900000
  </local_number>
  <local_number country_code="GB" country_code_iso3="GBR" country_name="United Kingdom" country_prefix="44">
    07700 900000
  </local_number>
  <local_number country_code="GB" country_code_iso3="GBR" country_name="United Kingdom" country_prefix="44">
    07700 900000
  </local_number>

Asynchronously get information about a phone number

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
string

You can find your API key in your account overview 

abc123 None
api_secret
string

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.

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

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

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.

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
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
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
subscription_type
string

None

 unknown
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
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
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
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
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. This is applicable to mobile numbers only.


One of: unknown, valid or 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

Warning levels for ip


One of: unknown or no_warning 		no_warning
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",
    "subscription_type": "unknown"
  },
  "caller_name": "John Smith",
  "last_name": "Smith",
  "first_name": "John",
  "caller_type": "consumer",
  "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": "no_warning"
}
  <local_number country_code="GB" country_code_iso3="GBR" country_name="United Kingdom" country_prefix="44">
    07700 900000
  </local_number>