Nexmo Labs hosts "beta" products, integrations, a small set of projects and experimental features built by Nexmo and our developer community.

Before you get started

Create your Nexmo account, it's free


 

Number Insight Standard

Number Insight Standard API allows you to retrieve information such as local and international number format, country code, number type, current and original carriers name and code. These customer identifiers can be used by your application/business for decision making. The API is designed to be a synchronous, easy to use, web service that can be used to easily:

  • Get a number in appropriate local format for using in your application to display a pretty formatted number.
  • Generate a number in appropriate international format to figure out the correct destination number.
  • Understand which country a user is coming from, based on their phone number.
  • Know whether the number is a mobile phone, a landline, a virtual number (Google Voice, Skype etc.) or a Premium/Toll-Free number.
  • Identify the MCC/MNC of a mobile phone number to figure out the appropriate routing for outbound communication to it.
  • Know if a number is real or not - unreal numbers will be returned with 'unknown' as the MCC/MNC and the request will be rejected altogether if the number is impossible as per E.164 guidelines.

All Number Insight Standard requests to Nexmo must be submitted to the base URL. Nexmo provides you with an option of a response as a JSON object, or an XML string - you get to choose which response by selecting the appropriate base URL for your request.

To get started with integrating the API in your systems, all you need is to know the phone number and the country (if the number is not in international format).

Request

JSON end point

https://api.nexmo.com/number/lookup/json

XML end point

https://api.nexmo.com/number/lookup/xml

All requests require your API credentials, which you can find under "API Settings" in Nexmo Dashboard.

Parameters

Parameter Description
api_key Required. Your API Key. Ex: api_key=n3xm0rocks
api_secret Required. Your API Secret. Ex: api_secret=12ab34cd
number Required. Phone number in national or international format and one recipient per request. Ex: to=447525856424 when sending to UK. The number may include any or all of white spaces, -,+, (, ).
country Optional. If the number provided is in local format (without country code) or when the input may not be certain to be with or without country code, use this to specify the two-character country code in ISO 3166-1 alpha-2 format (e.g. GB, US etc.). Verify will determine the international format phone number itself. If an international format number is provided along with country code, we will accept the request if the two match and reject it otherwise.

Response

After submitting a request to the Nexmo API, you will receive a synchronous response to your request. The HTTP response will contain either a JSON object or XML string, depending on the base URL you chose to submit your request and indicates the success or failure for the Nexmo platform as well as lookup information for the requested number.

JSON Response

{
status: status,
status_message: status_message,
request_id: request_id,
international_format_number: number,
national_format_number: local_number,
country_code: country_code,
request_price: request_price,
current_carrier: {
   network_code: mccmnc,
   name: name,
   country: country_code,
   network_type: number_type
}
original_carrier: {
   network_code: mccmnc,
   name: name,
   country: country_code,
   network_type: number_type
}
}

XML Response

<?xml version="1.0" encoding="UTF-8"?>
<lookup>
<request_id>request_id</request_id>
<international_format_number>number</international_format_number>
<local_number country_code="code">local_number</local_number>
<error code="code">status</error>
<request_price>price</request_price>
<remaining_balance>balance</remaining_balance>
<current_carrier network_code="mccmnc" name="carrier" country="country" network_type="type" />
<original_carrier network_code="mccmnc" name="carrier" country="country" network_type="type" />
</lookup>

The response will contain the following object/array keys and values:

Key Value
status The status of this request. For a list of the possible status codes, see Return Codes below.
status_message A description of the status. For a list of the possible status codes, see Return Codes below.
request_id Unique identifier (alphanumeric up to 40 characters).
international_format_number Looked up Number in International format.
national_format_number Looked up Number in format used by the country the number belongs to.
country_code Two character ISO 3166-1 alpha-2 country code for the country that the number belongs to.
request_price The amount in EUR charged to your account.
current_carrier: network_code The network code for the carrier that the number is currently associated with.
current_carrier: name The name for the carrier that the number is currently associated with.
current_carrier: country The country of the phone number currently in ISO 3166-1 alpha-2 format.
current_carrier: network_type The type of network that the number belongs to now. Mobile/Landline/Virtual/Premium/Toll-Free etc.
original_carrier: network_code The network code for the carrier that the number is currently associated with.
original_carrier: name The name for the carrier that the number is currently associated with.
original_carrier: country The country of the phone number currently in ISO 3166-1 alpha-2 format.
original_carrier: network_type The type of network that the number belongs to now. Mobile/Landline/Virtual/Premium/Toll-Free etc.

Return Codes

Code Error Text Meaning
0 Success The request was successfully accepted by Nexmo
1 Busy Busy (Throttled) Please re-try
3 Invalid Request Your request is incomplete and missing some mandatory parameters
4 Invalid credentials The api_key / api_secret you supplied is either invalid or 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


Number Insight Basic

Number Insight Basic API allows you to retrieve information such as local and international number format, country code; thereby allowing you to perform basic semantic checks on phone numbers for correctness. These customer identifiers can be used by your application/business for deciding if you should accept the phone number or ask your customers to check and correct it. The API is designed to be a synchronous, easy to use, web service that can be used to easily:

  • See if the number is inconsistent with E.164 and local guidelines - too short for the country, too long for the country, the wrong prefix or number series etc.
  • Return a number in appropriate local format for using in your application to display a pretty formatted number.
  • Generate a number in appropriate international format to figure out the correct destination number.
  • Understand which country a user is coming from, based on their phone number.

All Number Insight Basic API requests to Nexmo must be submitted to the base URL. Nexmo provides you with an option of a response as a JSON object, or an XML string - you get to choose which response by selecting the appropriate base URL for your request.

To get started with integrating the API in your systems, all you need is to know the phone number and the country (if the number is not in international format).

Request

JSON end point

https://api.nexmo.com/number/format/json

XML end point

https://api.nexmo.com/number/format/xml

All requests require your API credentials, which you can find under "API Settings" in Nexmo Dashboard.

Parameters

Parameter Description
api_key Required. Your API Key. Ex: api_key=n3xm0rocks
api_secret Required. Your API Secret. Ex: api_secret=12ab34cd
number Required. Phone number in national or international format and one recipient per request. Ex: to=447525856424 when sending to UK. The number may include any or all of white spaces, -,+, (, ).
country Optional. If the number provided is in local format (without country code) or when the input may not be certain to be with or without country code, use this to specify the two-character country code in ISO 3166-1 alpha-2 format (e.g. GB, US etc.). Verify will determine the international format phone number itself. If an international format number is provided along with country code, we will accept the request if the two match and reject it otherwise.

Response

After submitting a request to the Nexmo API, you will receive a synchronous response to your request. The HTTP response will contain either a JSON object or XML string, depending on the base URL you chose to submit your request and indicates the success or failure for the Nexmo platform as well as lookup information for the requested number.

JSON Response

{
status: status,
status_message: status_message,
request_id: request_id,
international_format_number: number,
national_format_number: local_number,
country_code: country_code_iso2,
country_code_iso3: country_code_iso3,
country_name: country_name,
country_prefix: country_prefix
}

XML Response

<?xml version="1.0" encoding="UTF-8"?>
<lookup>
<request_id>request_id</request_id>
<international_format_number>number</international_format_number>
<local_number country_code="code" country_code_iso3="country_code_iso3" country_name="country_name" country_prefix="country_prefix">local_number</local_number>
<error code="code">status</error>
</lookup>

The response will contain the following object/array keys and values:

Key Value
status The status of this request. For a list of the possible status codes, see Return Codes below.
status_message A description of the status. For a list of the possible status codes, see Return Codes below.
request_id Unique identifier (alphanumeric up to 40 characters).
international_format_number Looked up Number in International format.
national_format_number Looked up Number in format used by the country the number belongs to.
country_code Two character ISO 3166-1 alpha-2 country code for the country that the number belongs to.
country_code_iso3 Two character ISO 3166-1 alpha-3 country code for the country that the number belongs to.
country_name The full name of the country that the number belongs to.
country_prefix The numeric prefix for the country that the number belongs to.

Return Codes

Code Error Text Meaning
0 Success The request was successfully accepted by Nexmo
1 Busy Busy (Throttled) Please re-try
3 Invalid Request Your request is incomplete and missing some mandatory parameters
4 Invalid credentials The api_key / api_secret you supplied is either invalid or 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


OAuth: Nexmo Authentication Flow

Introduction

When your application acts on behalf of our users, it's important that:

  • The application be able to identify the user
  • The user's privacy is protected
  • Nexmo can tell which application and user are making the request

To accomplish this, Nexmo uses the OAuth 1.0a protocol to give your application authorized access to the APIs. OAuth is a standard for negotiating developer authorization and granting access on behalf of Nexmo users to perform API requests. One of OAuth's benefits is the availability of many libraries, allowing developers to authenticate with Nexmo quickly and in a similar manner to how they authenticate with services such as Twitter and LinkedIn.

In summary, the OAuth flow can be described as:

  • An application requests a set of temporary credentials, also known as a request token. At this point this credentials isn't associated with a specific Nexmo user's account
  • The application redirects the user to a Nexmo login page where they authorize these temporary credentials (request token) to be associated with their Nexmo user's account
  • The application upgrades the temporary request token for permanent credentials, also known as an access token. These credentials are necessary to give the application access to the Nexmo APIs and make calls on behalf of the Nexmo user's account

We suggest that you use an existing OAuth Library for your programming language of choice.

Configuring Your Application

Feel free to contact us if you want to participate to the "Apps developer program".

Sign in to your Nexmo Dashboard and select the "Apps" section.




Click on the "Developer" link and register your application:




And receive your "consumer key" and "consumer secret" required for the OAuth interaction:




Nexmo OAuth end points:

  • Request Token: https://dashboard.nexmo.com/oauth/request_token
  • Authorize: https://dashboard.nexmo.com/oauth/authorize
  • Authenticate: https://dashboard.nexmo.com/oauth/authenticate
  • Access Token: https://dashboard.nexmo.com/oauth/access_token

Once the OAuth handshaking completed, you will be able to use Nexmo APIs on behalf of the Nexmo user's account, replace "api_key" and "api_secret" by OAuth parameters.

Checkout our code sample from Github.



Nexmo Sandbox

Nexmo Sandbox provides an opportunity for developers to quickly test using the Nexmo REST or SMPP API without opening a production account. This can be very useful for load testing and/or regression testing. You can create a new test account simply by filling in the form below. With this account you will be sending message requests to our Sandbox environment. API responses will look just like those in production, but the messages won't be delivered to any real handset. Instead they will be logged in our shared Sandbox Inbox Folder.

From within the Sandbox Inbox Folder you will be able to test receiving Delivery Receipts (with a selection of statuses and error codes) to your DLR callback URL or SMPP client.

To start using our Sandbox, please create an account using the following form:

/ sec

If you disable quota, you can send unlimited messages - this might be helpful for load testing.

If quota is enabled then 0.05 cents will be subtracted from your test account balance upon each message sent.

Create Sandbox LVN

You can add LVNs to our sandbox. This will allow you to search and purchase them through our Dev API. You can also try other documented Dev API functions. For instance you can search numbers with http://rest-sandbox.nexmo.com/number/search/YOUR_KEY/YOUR_SECRET/COUNTRY_CODE?pattern=NUMBER