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

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

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 https://api.nexmo.com/ni/standard/json \
-d 'api_key=NEXMO_API_KEY' \
-d 'api_secret=NEXMO_API_SECRET' \
-d 'number=447700900000'

200 HTTP response

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

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>