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

cURL

Install the Nexmo library

$ npm install --save nexmo

Install the Nexmo library

Add the following to build.gradle:

repositories {
    mavenCentral()
}

dependencies {
    compile 'com.nexmo:client:2.0.2'
}

Install the Nexmo library

$ composer require nexmo/client:@beta

Install the Nexmo library

$ pip install nexmo

Install the Nexmo library

$ gem install nexmo

Initialize the library

const Nexmo = require('nexmo')

const nexmo = new Nexmo({
  apiKey: NEXMO_API_KEY,
  apiSecret: NEXMO_API_SECRET
})

Initialize the library

AuthMethod auth = new TokenAuthMethod(NEXMO_API_KEY, NEXMO_API_SECRET);
NexmoClient client = new NexmoClient(auth);

Initialize the library

$basic  = new \Nexmo\Client\Credentials\Basic(NEXMO_API_KEY, NEXMO_API_SECRET);
$client = new \Nexmo\Client($basic);

Initialize the library

import nexmo

client = nexmo.Client(key=NEXMO_API_KEY, secret=NEXMO_API_SECRET)

Initialize the library

require 'nexmo'

client = Nexmo::Client.new(
  api_key: NEXMO_API_KEY,
  api_secret: NEXMO_API_SECRET
)

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, 45or999

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, unknownorpager
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, unknownorpager
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_portedorassumed_ported
roaming
object
- Key
  
  Description
- status
  Attribute | string
  
  Is number outside its home carrier network.
  
  One of: unknown, roamingornot_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, consumerorunknown
- 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, consumerorunknown
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, 1or2
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, validornot_valid
reachable
string

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

One of: unknown, reachable, undeliverable, absent, bad_numberorblacklisted
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: countryormismatch
- 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: unknownorno_warning

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

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, unknownorpager
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, unknownorpager
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, consumerorunknown
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, 1or2
- 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_numberorblacklisted
roaming
object
- Key
  
  Description
- status
  Attribute | string
  
  Is number outside its home carrier network.
  
  One of: unknown, roamingornot_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: countryormismatch
- 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, validornot_valid
ip_warnings
string

Warning levels for ip

One of: unknownorno_warning

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

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

<?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>
  <cnam caller-type="consumer" caller-name="John Smith" first-name="John" last-name="Smith" subscription-type="unknown">
  </cnam>
  <caller_name>John Smith</caller_name>
  <last_name>Smith</last_name>
  <firs_name>John</firs_name>
  <caller_type>consumer</caller_type>
  <lookup_outcome code="0">Success</lookup_outcome>
  <reachable>reachable</reachable>
  <roaming status="roaming" roaming_country_code="US" roaming_network_code="12345" roaming_network_name="Acme Inc">
  </roaming>
  <ip address="123.0.0.255" ip_match_level="country" ip_country="GB" ip_city="London">
  </ip>
  <valid_number>valid</valid_number>
  <ip_warnings>no_warning</ip_warnings>
</lookup>

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, standardoradvanced

standard

None
format
Required | string

The format of the response

Must be one of: jsonorxml

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

Example request

cURL

curl https://api.nexmo.com/ni/standard/json \
-d 'api_key=NEXMO_API_KEY' \
-d 'api_secret=NEXMO_API_SECRET' \
-d 'number=447700900000'

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

Basic
Standard
Advanced

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

<?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>
  <cnam caller-type="consumer" caller-name="John Smith" first-name="John" last-name="Smith" subscription-type="unknown">
  </cnam>
  <caller_name>John Smith</caller_name>
  <last_name>Smith</last_name>
  <firs_name>John</firs_name>
  <caller_type>consumer</caller_type>
</lookup>

<?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>
  <cnam caller-type="consumer" caller-name="John Smith" first-name="John" last-name="Smith" subscription-type="unknown">
  </cnam>
  <caller_name>John Smith</caller_name>
  <last_name>Smith</last_name>
  <firs_name>John</firs_name>
  <caller_type>consumer</caller_type>
  <lookup_outcome code="0">Success</lookup_outcome>
  <reachable>reachable</reachable>
  <roaming status="roaming" roaming_country_code="US" roaming_network_code="12345" roaming_network_name="Acme Inc">
  </roaming>
  <ip address="123.0.0.255" ip_match_level="country" ip_country="GB" ip_city="London">
  </ip>
  <valid_number>valid</valid_number>
  <ip_warnings>no_warning</ip_warnings>
</lookup>

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: jsonorxml

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

Example request

cURL

curl https://api.nexmo.com/ni/standard/async/json \
-d 'api_key=NEXMO_API_KEY' \
-d 'api_secret=NEXMO_API_SECRET' \
-d 'number=447700900000' \
-d 'callback=https://example.com/webhooks/event'

200 HTTP response

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

Callback Asynchronous response

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, 45or999

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, unknownorpager
  
  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, unknownorpager
  
  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_portedorassumed_ported

not_ported
roaming
object
- Key
  
  Description
  
  Example
- status
  Attribute | string
  
  Is number outside its home carrier network.
  
  One of: unknown, roamingornot_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, consumerorunknown
  
  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, consumerorunknown

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, 1or2

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, validornot_valid

valid
reachable
string

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

One of: unknown, reachable, undeliverable, absent, bad_numberorblacklisted

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: countryormismatch
  
  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: unknownorno_warning

no_warning

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

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

<?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>
  <cnam caller-type="consumer" caller-name="John Smith" first-name="John" last-name="Smith" subscription-type="unknown">
  </cnam>
  <caller_name>John Smith</caller_name>
  <last_name>Smith</last_name>
  <firs_name>John</firs_name>
  <caller_type>consumer</caller_type>
  <lookup_outcome code="0">Success</lookup_outcome>
  <reachable>reachable</reachable>
  <roaming status="roaming" roaming_country_code="US" roaming_network_code="12345" roaming_network_name="Acme Inc">
  </roaming>
  <ip address="123.0.0.255" ip_match_level="country" ip_country="GB" ip_city="London">
  </ip>
  <valid_number>valid</valid_number>
  <ip_warnings>no_warning</ip_warnings>
</lookup>