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
Number Lookup 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 Lookup 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).
JSON end point
XML end point
All requests require your API credentials, which you can find under "API Settings" in Nexmo Dashboard.
|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.|
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.
<?xml version="1.0" encoding="UTF-8"?>
<current_carrier network_code="mccmnc" name="carrier" country="country" network_type="type" />
<original_carrier network_code="mccmnc" name="carrier" country="country" network_type="type" />
The response will contain the following object/array keys and values:
|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.|
|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
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 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:
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