Introduction

Welcome to the NumValidate API documentation.

NumValidate is an open source REST API powered by Google LibPhoneNumber that provides a simple yet effective way to validate and format a phone number.

We have language bindings in Shell, Javascript (JQuery), Ruby and Java! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

This API documentation page was created with Slate.

Authentication

To authorize, use this code:

curl "api_endpoint_here"
  -H "x-api-token: abc123"

  var settings = {
    "async": true,
    "crossDomain": true,
    "url": "api_endpoint_here",
    "method": "GET",
    "headers": {
      "x-api-token": "abc123"
    }
  }

  $.ajax(settings).done(function (response) {
    console.log(response);
  });

  require 'uri'
  require 'net/http'

  url = URI("api_endpoint_here")

  http = Net::HTTP.new(url.host, url.port)

  request = Net::HTTP::Get.new(url)
  request["x-api-token"] = 'abc123'

  response = http.request(request)
  puts response.read_body

  OkHttpClient client = new OkHttpClient();

  Request request = new Request.Builder()
    .url("api_endpoint_here")
    .get()
    .addHeader("x-api-token", "abc123")
    .build();

  Response response = client.newCall(request).execute();

Make sure to replace abc123 with your API key and api_endpoint_here with the desired API endpoint.

NumValidate API can be accessed without authentication, but to ensure a high quality of service for all API consumers, we've reduced the daily rate limit for unauthenticated requests.
To enjoy the daily rate limit of 1000 requests per day, you'll need to sign-up for a free account. Unauthenticated requests will be limited to 100 per day unless you include an API key generated with a free account. You can generate a new NumValidate API key at your dashboard.

NumValidate expects for the API key to be included in all API requests to the server in a header that looks like the following:

x-api-token: abc123

Validation

Validation of an international phone number (the leading 1 is the US dialling code):

curl "https://numvalidate.com/api/validate?number=12015550123"
  -H "Authorization: abc123"

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://numvalidate.com/api/validate?number=12015550123",
  "method": "GET",
  "headers": {
    "x-api-token": "abc123"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

require 'uri'
require 'net/http'

url = URI("https://numvalidate.com/api/validate?number=12015550123")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["x-api-token"] = 'abc123'

response = http.request(request)
puts response.read_body

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://numvalidate.com/api/validate?number=12015550123")
  .get()
  .addHeader("x-api-token", "abc123")
  .build();

Response response = client.newCall(request).execute();

The above command returns JSON structured like this:

{ 
  "data": {
    "valid": true,
    "number": "12015550123",
    "e164Format": "+12015550123",
    "internationalFormat": "+1 201-555-0123",
    "nationalFormat": "(201) 555-0123",
    "countryCode": "US",
    "countryPrefix": "1",
    "countryName": "United States"
  }
}

Validation of a local phone number:

curl "https://numvalidate.com/api/validate?number=2015550123&countryCode=US"
  -H "Authorization: abc123"

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://numvalidate.com/api/validate?number=2015550123&countryCode=US",
  "method": "GET",
  "headers": {
    "x-api-token": "abc123"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

require 'uri'
require 'net/http'

url = URI("https://numvalidate.com/api/validate?number=2015550123&countryCode=US")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["x-api-token"] = 'abc123'

response = http.request(request)
puts response.read_body

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://numvalidate.com/api/validate?number=2015550123&countryCode=US")
  .get()
  .addHeader("x-api-token", "abc123")
  .build();

Response response = client.newCall(request).execute();

The above command returns JSON structured like this:

{ 
  "data": {
    "valid": true,
    "number": "2015550123",
    "e164Format": "+12015550123",
    "internationalFormat": "+1 201-555-0123",
    "nationalFormat": "(201) 555-0123",
    "countryCode": "US",
    "countryPrefix": "1",
    "countryName": "United States"
  }
}

This endpoint validates and format a phone number.
If you intend to specify a phone number in its national (local) format, you will be required to provide additional country information, simply by appending your preferred 2-digit country code to the API's countryCode parameter and including it in your API request URL.

The output will consist in the following:

HTTP Request

GET https://numvalidate.com/api/validate

Query Parameters

Countries

curl "https://numvalidate.com/api/countries"
  -H "Authorization: abc123"

  var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://numvalidate.com/api/countries",
    "method": "GET",
    "headers": {
      "x-api-token": "abc123"
    }
  }

  $.ajax(settings).done(function (response) {
    console.log(response);
  });

  require 'uri'
  require 'net/http'

  url = URI("https://numvalidate.com/api/countries")

  http = Net::HTTP.new(url.host, url.port)

  request = Net::HTTP::Get.new(url)
  request["x-api-token"] = 'abc123'

  response = http.request(request)
  puts response.read_body

  OkHttpClient client = new OkHttpClient();

  Request request = new Request.Builder()
    .url("https://numvalidate.com/api/countries")
    .get()
    .addHeader("x-api-token", "abc123")
    .build();

  Response response = client.newCall(request).execute();

The above command returns JSON structured like this:

{
  "data" :
    {
    "AF": {
      "country_name": "Afghanistan",
      "dialling_code": "+93"
    },
    "AL": {
      "country_name": "Albania",
      "dialling_code": "+355"
    },
    "DZ": {
      "country_name": "Algeria",
      "dialling_code": "+213"
    },
    "AS": {
      "country_name": "American Samoa",
      "dialling_code": "+1"
    },
...

Using the API's countries endpoint, you may access a comprehensive list of all the supported countries, including country names and dialling codes.

HTTP Request

GET https://numvalidate.com/api/countries

Errors

NumValidate API uses the following error codes: