The 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.
Provides basic number insight information about a number.
Note that this endpoint also supports POST requests.
GET
https://api.nexmo.com/ni/basic/:format
Host
https://api.nexmo.com
GET
/ni/basic/:format
The format of the response
Must be one of:json or xml
You can find your API key in your account overview
You can find your API secret in your account overview
A single phone number that you need insight about in national or international format.
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.
| Code | Text |
|---|---|
| 0 | Success - request accepted for delivery by . |
| 1 | Busy - you have made more requests in the last second than are permitted by your 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 account does not have sufficient credit to process this request. |
0, 1, 3, 4, 5 or 9
The status description of your request.
The unique identifier for your request. This is a alphanumeric string up to 40 characters.
The number in your request in international format.
The number in your request in the format used by the country the number belongs to.
The full name of the country that number is registered in.
The numeric prefix for the country that number is registered in.
The unique identifier for your request. This is a alphanumeric string up to 40 characters.
The number in your request in international format.
An object containing the number in your request in the format used by the country the number belongs to.
The full name of the country that number is registered in.
The numeric prefix for the country that number is registered in.
The number in your request in the format used by the country the number belongs to.
The error code and status of your request
The status code
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>
Provides standard number insight information about a number.
Note that this endpoint also supports POST requests.
GET
https://api.nexmo.com/ni/standard/:format
Host
https://api.nexmo.com
GET
/ni/standard/:format
The format of the response
Must be one of:json or xml
You can find your API key in your account overview
You can find your API secret in your account overview
A single phone number that you need insight about in national or international format.
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.
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.
| Code | Text |
|---|---|
| 0 | Success - request accepted for delivery by . |
| 1 | Busy - you have made more requests in the last second than are permitted by your 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 account does not have sufficient credit to process this request. |
0, 1, 3, 4, 5 or 9
The status description of your request.
The unique identifier for your request. This is a alphanumeric string up to 40 characters.
The number in your request in international format.
The number in your request in the format used by the country the number belongs to.
The full name of the country that number is registered in.
The numeric prefix for the country that number is registered in.
The amount in EUR charged to your account.
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.
Your account balance in EUR after this request.
The https://en.wikipedia.org/wiki/Mobile_country_code for the carriernumber is associated with. Unreal numbers are marked asnull and the request is rejected altogether if the number is impossible according to the E.164 guidelines.
The full name of the carrier that number is associated with.
The country that number is associated with. This is in ISO 3166-1 alpha-2 format.
The type of network that number is associated with.
mobile, landline, landline_premium, landline_tollfree, virtual, unknown or pager
Information about the network number was initially connected to.
The https://en.wikipedia.org/wiki/Mobile_country_code for the carriernumber is associated with. Unreal numbers are marked asnull and the request is rejected altogether if the number is impossible according to the E.164 guidelines.
The full name of the carrier that number is associated with.
The country that number is associated with. This is in ISO 3166-1 alpha-2 format.
The type of network that number is associated with.
mobile, landline, landline_premium, landline_tollfree, virtual, unknown or pager
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.
unknown, ported, not_ported, assumed_not_ported or assumed_ported
Information about the roaming status for number. This is applicable to mobile numbers only.
Is number outside its home carrier network.
roaming or not_roaming
If number is roaming, this is the id of the carrier network number is roaming in.
If number is roaming, this is the name of the carrier network number is roaming in.
Information about the network number is currently connected to.
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.
business, consumer or unknown
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 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 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.
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 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 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.
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.
business, consumer or unknown
| Code | Text |
|---|---|
| 0 | Success - request accepted for delivery by . |
| 1 | Busy - you have made more requests in the last second than are permitted by your 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 account does not have sufficient credit to process this request. |
0, 1, 3, 4, 5 or 9
The status description of your request.
The unique identifier for your request. This is a alphanumeric string up to 40 characters.
The number in your request in international format.
The number in your request in the format used by the country the number belongs to.
The full name of the country that number is registered in.
The numeric prefix for the country that number is registered in.
The amount in EUR charged to your account.
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.
Your account balance in EUR after this request.
The https://en.wikipedia.org/wiki/Mobile_country_code for the carriernumber is associated with. Unreal numbers are marked asnull and the request is rejected altogether if the number is impossible according to the E.164 guidelines.
The full name of the carrier that number is associated with.
The country that number is associated with. This is in ISO 3166-1 alpha-2 format.
The type of network that number is associated with.
mobile, landline, landline_premium, landline_tollfree, virtual, unknown or pager
Information about the network number was initially connected to.
The https://en.wikipedia.org/wiki/Mobile_country_code for the carriernumber is associated with. Unreal numbers are marked asnull and the request is rejected altogether if the number is impossible according to the E.164 guidelines.
The full name of the carrier that number is associated with.
The country that number is associated with. This is in ISO 3166-1 alpha-2 format.
The type of network that number is associated with.
mobile, landline, landline_premium, landline_tollfree, virtual, unknown or pager
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.
unknown, ported, not_ported, assumed_not_ported or assumed_ported
unknown
Information about the network number is currently connected to.
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.
business, consumer or unknown
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 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 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.
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 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 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.
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.
business, consumer or unknown
The unique identifier for your request. This is a alphanumeric string up to 40 characters.
The number in your request in international format.
An object containing the number in your request in the format used by the country the number belongs to.
The full name of the country that number is registered in.
The numeric prefix for the country that number is registered in.
The number in your request in the format used by the country the number belongs to.
The error code and status of your request
The status code
The status description of your request.
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.
Your account balance in EUR after this request.
The https://en.wikipedia.org/wiki/Mobile_country_code for the carriernumber is associated with. Unreal numbers are marked asnull and the request is rejected altogether if the number is impossible according to the E.164 guidelines.
The full name of the carrier that number is associated with.
The country that number is associated with. This is in ISO 3166-1 alpha-2 format.
The type of network that number is associated with.
mobile, landline, landline_premium, landline_tollfree, virtual, unknown or pager
Information about the network number was initially connected to.
The https://en.wikipedia.org/wiki/Mobile_country_code for the carriernumber is associated with. Unreal numbers are marked asnull and the request is rejected altogether if the number is impossible according to the E.164 guidelines.
The full name of the carrier that number is associated with.
The country that number is associated with. This is in ISO 3166-1 alpha-2 format.
The type of network that number is associated with.
mobile, landline, landline_premium, landline_tollfree, virtual, unknown or pager
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
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.
unknown, ported, not_ported, assumed_not_ported or assumed_ported
Information about the roaming status for number. This is applicable to mobile numbers only.
unknown
Contains details of the number owner, if cnam was set to true in the request.
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.
business, consumer or unknown
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 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 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.
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 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 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.
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.
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"
}{
"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": "unknown",
"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>
Provides advanced number insight number information asynchronously using the URL specified in the callback parameter. recommends asynchronous use of the Number Insight Advanced API, to avoid timeouts.
Note that this endpoint also supports POST requests.
GET
https://api.nexmo.com/ni/advanced/async/:format
Host
https://api.nexmo.com
GET
/ni/advanced/async/:format
The format of the response
Must be one of:json or xml
You can find your API key in your account overview
You can find your API secret in your account overview
The callback URL
A single phone number that you need insight about in national or international format.
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.
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.
This parameter is deprecated as we are no longer able to retrieve reliable IP data globally from carriers.
The unique identifier for your request. This is a alphanumeric string up to 40 characters.
The number in your request
Your account balance in EUR after this request.
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.
| Code | Text |
|---|---|
| 0 | Success - request accepted for delivery by . |
| 1 | Busy - you have made more requests in the last second than are permitted by your 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 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. |
0, 1, 3, 4, 5, 9, 19, 43, 44, 45 or 999
The status description of your request. Note: This field is equivalent to status_message field in the other endpoints
The unique identifier for your request. This is a alphanumeric string up to 40 characters.
The number in your request
Your account balance in EUR after this request.
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.
| Code | Text |
|---|---|
| 0 | Success - request accepted for delivery by . |
| 1 | Busy - you have made more requests in the last second than are permitted by your 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 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. |
0, 1, 3, 4, 5, 9, 19, 43, 44, 45 or 999
The status description of your request. Note: This field is equivalent to status_message field in the other endpoints
{
"request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"number": "447700900000",
"remaining_balance": "1.23456789",
"request_price": "0.01500000",
"status": 0,
"error_text": "Success"
}<?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>
<error_text>Success</error_text>
</lookup>
Contains the response to your Number Insight Advanced API request.
POST
https://example.com/webhooks/event
| Code | Text |
|---|---|
| 0 | Success - request accepted for delivery by . |
| 1 | Busy - you have made more requests in the last second than are permitted by your 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 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. |
0, 1, 3, 4, 5, 9, 19, 43, 44, 45 or 999
The status description of your request.
The unique identifier for your request. This is a alphanumeric string up to 40 characters.
The number in your request in international format.
The number in your request in the format used by the country the number belongs to.
Two character country code for number. This is in ISO 3166-1 alpha-2 format.
Three character country code for number. This is in ISO 3166-1 alpha-3 format.
The full name of the country that number is registered in.
The numeric prefix for the country that number is registered in.
The amount in EUR charged to your account.
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.
Your account balance in EUR after this request.
Information about the network number is currently connected to.
The https://en.wikipedia.org/wiki/Mobile_country_code for the carriernumber is associated with. Unreal numbers are marked asnull and the request is rejected altogether if the number is impossible according to the E.164 guidelines.
The full name of the carrier that number is associated with.
The country that number is associated with. This is in ISO 3166-1 alpha-2 format.
The type of network that number is associated with.
mobile, landline, landline_premium, landline_tollfree, virtual, unknown or pager
Information about the network number was initially connected to.
The https://en.wikipedia.org/wiki/Mobile_country_code for the carriernumber is associated with. Unreal numbers are marked asnull and the request is rejected altogether if the number is impossible according to the E.164 guidelines.
The full name of the carrier that number is associated with.
The country that number is associated with. This is in ISO 3166-1 alpha-2 format.
The type of network that number is associated with.
mobile, landline, landline_premium, landline_tollfree, virtual, unknown or pager
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.
unknown, ported, not_ported, assumed_not_ported or assumed_ported
Information about the roaming status for number. This is applicable to mobile numbers only.
Is number outside its home carrier network.
roaming or not_roaming
If number is roaming, this is the code of the country number is roaming in.
If number is roaming, this is the id of the carrier network number is roaming in.
If number is roaming, this is the name of the carrier network number is roaming in.
Information about the network number is currently connected to.
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.
business, consumer or unknown
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 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 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.
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 |
0, 1 or 2
Shows if all information about a phone number has been returned.
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.
unknown, valid, not_valid, inferred or inferred_not_valid
Can you call number now. This is applicable to mobile numbers only.
unknown, reachable, undeliverable, absent, bad_number or blacklisted
{
"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"
},
"lookup_outcome": 0,
"lookup_outcome_message": "Success",
"valid_number": "valid",
"reachable": "reachable"
}{
"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"
},
"lookup_outcome": 0,
"lookup_outcome_message": "Success",
"valid_number": "valid",
"reachable": "reachable"
}Contains the response to your Number Insight Advanced API request.
POST
https://example.com/webhooks/event
| Code | Text |
|---|---|
| 0 | Success - request accepted for delivery by . |
| 1 | Busy - you have made more requests in the last second than are permitted by your 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 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. |
0, 1, 3, 4, 5, 9, 19, 43, 44, 45 or 999
The status description of your request.
The unique identifier for your request. This is a alphanumeric string up to 40 characters.
The number in your request in international format.
The number in your request in the format used by the country the number belongs to.
Two character country code for number. This is in ISO 3166-1 alpha-2 format.
Three character country code for number. This is in ISO 3166-1 alpha-3 format.
The full name of the country that number is registered in.
The numeric prefix for the country that number is registered in.
The amount in EUR charged to your account.
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.
Your account balance in EUR after this request.
Information about the network number is currently connected to.
The https://en.wikipedia.org/wiki/Mobile_country_code for the carriernumber is associated with. Unreal numbers are marked asnull and the request is rejected altogether if the number is impossible according to the E.164 guidelines.
The full name of the carrier that number is associated with.
The country that number is associated with. This is in ISO 3166-1 alpha-2 format.
The type of network that number is associated with.
mobile, landline, landline_premium, landline_tollfree, virtual, unknown or pager
Information about the network number was initially connected to.
The https://en.wikipedia.org/wiki/Mobile_country_code for the carriernumber is associated with. Unreal numbers are marked asnull and the request is rejected altogether if the number is impossible according to the E.164 guidelines.
The full name of the carrier that number is associated with.
The country that number is associated with. This is in ISO 3166-1 alpha-2 format.
The type of network that number is associated with.
mobile, landline, landline_premium, landline_tollfree, virtual, unknown or pager
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.
unknown, ported, not_ported, assumed_not_ported or assumed_ported
Unknown Roaming
One of:unknown
Information about the network number is currently connected to.
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.
business, consumer or unknown
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 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 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.
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 |
0, 1 or 2
Shows if all information about a phone number has been returned.
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.
unknown, valid, not_valid, inferred or inferred_not_valid
Can you call number now. This is applicable to mobile numbers only.
unknown, reachable, undeliverable, absent, bad_number or blacklisted
{
"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": "unknown",
"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"
}{
"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": "unknown",
"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"
}Provides advanced number insight information about a number synchronously, in the same way that the basic and standard endpoints do.
Vonage recommends accessing the Advanced API asynchronously using the /advanced/async endpoint, to avoid timeouts.
Note that this endpoint also supports POST requests.
GET
https://api.nexmo.com/ni/advanced/:format
Host
https://api.nexmo.com
GET
/ni/advanced/:format
The format of the response
Must be one of:json or xml
You can find your API key in your account overview
You can find your API secret in your account overview
A single phone number that you need insight about in national or international format.
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.
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.
This parameter is deprecated as we are no longer able to retrieve reliable IP data globally from carriers.
| Code | Text |
|---|---|
| 0 | Success - request accepted for delivery by . |
| 1 | Busy - you have made more requests in the last second than are permitted by your 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 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. |
0, 1, 3, 4, 5, 9, 19, 43, 44, 45 or 999
The status description of your request.
The unique identifier for your request. This is a alphanumeric string up to 40 characters.
The number in your request in international format.
The number in your request in the format used by the country the number belongs to.
The full name of the country that number is registered in.
The numeric prefix for the country that number is registered in.
The amount in EUR charged to your account.
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.
Your account balance in EUR after this request.
Information about the network number is currently connected to.
The https://en.wikipedia.org/wiki/Mobile_country_code for the carriernumber is associated with. Unreal numbers are marked asnull and the request is rejected altogether if the number is impossible according to the E.164 guidelines.
The full name of the carrier that number is associated with.
The country that number is associated with. This is in ISO 3166-1 alpha-2 format.
The type of network that number is associated with.
mobile, landline, landline_premium, landline_tollfree, virtual, unknown or pager
Information about the network number was initially connected to.
The https://en.wikipedia.org/wiki/Mobile_country_code for the carriernumber is associated with. Unreal numbers are marked asnull and the request is rejected altogether if the number is impossible according to the E.164 guidelines.
The full name of the carrier that number is associated with.
The country that number is associated with. This is in ISO 3166-1 alpha-2 format.
The type of network that number is associated with.
mobile, landline, landline_premium, landline_tollfree, virtual, unknown or pager
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.
unknown, ported, not_ported, assumed_not_ported or assumed_ported
Information about the roaming status for number. This is applicable to mobile numbers only.
Is number outside its home carrier network.
roaming or not_roaming
If number is roaming, this is the id of the carrier network number is roaming in.
If number is roaming, this is the name of the carrier network number is roaming in.
Information about the network number is currently connected to.
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.
business, consumer or unknown
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 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 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.
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 |
0, 1 or 2
Shows if all information about a phone number has been returned.
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.
unknown, valid, not_valid, inferred or inferred_not_valid
Can you call number now. This is applicable to mobile numbers only.
unknown, reachable, undeliverable, absent, bad_number or blacklisted
| Code | Text |
|---|---|
| 0 | Success - request accepted for delivery by . |
| 1 | Busy - you have made more requests in the last second than are permitted by your 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 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. |
0, 1, 3, 4, 5, 9, 19, 43, 44, 45 or 999
The status description of your request.
The unique identifier for your request. This is a alphanumeric string up to 40 characters.
The number in your request in international format.
The number in your request in the format used by the country the number belongs to.
The full name of the country that number is registered in.
The numeric prefix for the country that number is registered in.
The amount in EUR charged to your account.
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.
Your account balance in EUR after this request.
Information about the network number is currently connected to.
The https://en.wikipedia.org/wiki/Mobile_country_code for the carriernumber is associated with. Unreal numbers are marked asnull and the request is rejected altogether if the number is impossible according to the E.164 guidelines.
The full name of the carrier that number is associated with.
The country that number is associated with. This is in ISO 3166-1 alpha-2 format.
The type of network that number is associated with.
mobile, landline, landline_premium, landline_tollfree, virtual, unknown or pager
Information about the network number was initially connected to.
The https://en.wikipedia.org/wiki/Mobile_country_code for the carriernumber is associated with. Unreal numbers are marked asnull and the request is rejected altogether if the number is impossible according to the E.164 guidelines.
The full name of the carrier that number is associated with.
The country that number is associated with. This is in ISO 3166-1 alpha-2 format.
The type of network that number is associated with.
mobile, landline, landline_premium, landline_tollfree, virtual, unknown or pager
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.
unknown, ported, not_ported, assumed_not_ported or assumed_ported
unknown
Information about the network number is currently connected to.
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.
business, consumer or unknown
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 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 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.
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 |
0, 1 or 2
Shows if all information about a phone number has been returned.
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.
unknown, valid, not_valid, inferred or inferred_not_valid
Can you call number now. This is applicable to mobile numbers only.
unknown, reachable, undeliverable, absent, bad_number or blacklisted
The unique identifier for your request. This is a alphanumeric string up to 40 characters.
The number in your request in international format.
An object containing the number in your request in the format used by the country the number belongs to.
The full name of the country that number is registered in.
The numeric prefix for the country that number is registered in.
The number in your request in the format used by the country the number belongs to.
The error code and status of your request
The status code
The status description of your request.
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.
Your account balance in EUR after this request.
Information about the network number is currently connected to.
The https://en.wikipedia.org/wiki/Mobile_country_code for the carriernumber is associated with. Unreal numbers are marked asnull and the request is rejected altogether if the number is impossible according to the E.164 guidelines.
The full name of the carrier that number is associated with.
The country that number is associated with. This is in ISO 3166-1 alpha-2 format.
The type of network that number is associated with.
mobile, landline, landline_premium, landline_tollfree, virtual, unknown or pager
Information about the network number was initially connected to.
The https://en.wikipedia.org/wiki/Mobile_country_code for the carriernumber is associated with. Unreal numbers are marked asnull and the request is rejected altogether if the number is impossible according to the E.164 guidelines.
The full name of the carrier that number is associated with.
The country that number is associated with. This is in ISO 3166-1 alpha-2 format.
The type of network that number is associated with.
mobile, landline, landline_premium, landline_tollfree, virtual, unknown or pager
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.
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.
unknown, ported, not_ported, assumed_not_ported or assumed_ported
Contains details of the number owner, if cnam was set to true in the request.
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.
business, consumer or unknown
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 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 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.
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 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 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.
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.
business, consumer or unknown
An object indicating whether all information about a phone number has been returned.
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 |
0, 1 or 2
Shows if all information about a phone number has been returned.
Can you call number now. This is applicable to mobile numbers only.
unknown, reachable, undeliverable, absent, bad_number or blacklisted
Information about the roaming status for number. This is applicable to mobile numbers only.
Is number outside its home carrier network.
roaming or not_roaming
If number is roaming, this is the id of the carrier network number is roaming in.
If number is roaming, this is the name of the carrier network number is roaming in.
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.
unknown, valid, not_valid or inferred_not_valid
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"
}{
"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": "unknown",
"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"
}<?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>
<valid_number>valid</valid_number>
<ip_warnings>unknown</ip_warnings>
</lookup>