RealValidito Lookup API Documentation

RealValidito API is a REST based JSON API. It provides a set of stateless endpoints that any program or web browser can call by sending a standard HTTP request.

RealValidito will respond with a standard HTTP response carrying a JSON payload. This documentation describes these endpoints, their input/output parameters and authentication methods.

RealValidito API allows you to create Custom Integrations to add Phone Number Validation, DNC Validation, Gender Validation or ZIP Validation to any part of your software application. Let's take a quick look at how to get started.

Getting started with RealValidito is free and does not require a credit card. Your account comes with 1,000 free phone validation lookup credits.

Once you have signed up and created an account try out a curl command to access the RealValidito APIs.

All URLs referenced in the API documentation have the following base :

https://app.realvalidito.com

This REST API is served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported.

Request Header :

Content-Type: application/json

All RealValidito Api requests require authentication, by passing your api key & api secret as part of the request parameters.

You can find your api key & api secret in your console.

Authentication is always required. To simplify the examples, however, the documentation will frequently omit showing the query-string api key & api secret parameters.

Your api key & api secret should not, in any circumstances, be shared with anyone else. You are responsible for any costs incurred while accessing the Api with your key & api secret.

Get Available Credits

GET /phonelookup/getcredits/{api_key}/{api_secret}

Phone Number Lookup

POST /phonelookup/validate

GET /phonelookup/getcredits/{api_key}/{api_secret}

Path variables

api_key

string required

API Key

Example:

RWK0JWVM3Gp2QmtG09TStoWjhjNlB

api_secret

string required

API Secret

Example:

f606925fd8f72ebc15a5c27e7be040

Responses

200 OK

Success

Failed


{
  "status": "success",
  "data": {
     "available_credits": 5000
   }
}



Unauthorized
{
  "status": "failed",
  "error": {
    "error_code": 600,
    "message": "Invalid API Key or API Secret."
  }
}

{
  "status": "failed",
  "error": {
    "error_code": 614,
    "message": "The request could not be authenticated. Only HTTP GET method is allowed."
  }
}

cURL (Bash)

JQuery (Javascript)

PHP (cURL)

curl -X GET 'https://app.realvalidito.com/phonelookup/getcredits/RWK0JWVM3Gp2QmtG09TStoWjhjNlB/f606925fd8f72ebc15a5c27e7be040' \

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "status": "success",
  "data": {
     "available_credits": 5000
   }
}

var api_key = 'RWK0JWVM3Gp2QmtG09TStoWjhjNlB';
var api_secret = 'f606925fd8f72ebc15a5c27e7be040';
$.ajax({
    url: 'https://app.realvalidito.com/phonelookup/getcredits/' + api_key + '/' + api_secret,
    method: 'GET',
    dataType: 'json',
    success: function(data) {
        console.log(data);       
    }
});

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "status": "success",
  "data": {
     "available_credits": 5000
   }
}

$api_key = 'RWK0JWVM3Gp2QmtG09TStoWjhjNlB';
$api_secret = 'f606925fd8f72ebc15a5c27e7be040';
$ch = curl_init('https://app.realvalidito.com/phonelookup/getcredits/' . api_key . '/' + api_secret);  
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = curl_exec($ch);
curl_close($ch);
echo $data;

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "status": "success",
  "data": {
     "available_credits": 5000
   }
}

POST /phonelookup/validate

Request body

Object

api_key

string required

API Key

Example:

RWK0JWVM3Gp2QmtG09TStoWjhjNlB

api_secret

string required

API Secret

Example:

f606925fd8f72ebc15a5c27e7be040

numbers

array required

Phone number(s) to validate

Example:

['1234567890', '470*******', '908*******', '704*******']

Array of 10 digit, numeric phone number of USA / CANADA only. No spaces, special characters, etc. No leading +1.

Maximum of 1,000 phone numbers are permitted.

Responses

200 OK

Success

Failed


{
  "status": "success",
  "data": {
    "1234567890": {
      "status": "Invalid",
      "phone_number": "1234567890",
      "national_format": "",
      "country_prefix": "",
      "number_type": "Unknown",
      "zip": "",
      "area": "",
      "city": "",
      "state": "",
      "country": "",
      "timezone": "",
      "network_name": "",
      "network_type": "",
      "network_domain": ""
    },
    "470*******": {
      "status": "Valid",
      "phone_number": "+1470*******",
      "national_format": "(470) ***-****",
      "country_prefix": "1",
      "number_type": "Mobile",
      "zip": "30097",
      "area": "",
      "city": "DULUTH",
      "state": "GA",
      "country": "US",
      "timezone": "EST (America/New_York)",
      "network_name": "CELLCO PARTNERSHIP DBA VERIZON",
      "network_type": "WIRELESS",
      "network_domain": "470*******@vtext.com"
    },
    "908*******": {
      "status": "Valid",
      "phone_number": "+1908*******",
      "national_format": "(908) ***-****",
      "country_prefix": "1",
      "number_type": "Landline",
      "zip": "07102",
      "area": "Essex",
      "city": "NEWARK",
      "state": "NJ",
      "country": "US",
      "timezone": "EST (America/New_York)",
      "network_name": "CABLEVISION LIGHTPATH, INC. -",
      "network_type": "CLEC",
      "network_domain": ""
    },
    "704*******": {
      "status": "Valid",
      "phone_number": "+1704*******",
      "national_format": "(704) ***-****",
      "country_prefix": "1",
      "number_type": "VoIP",
      "zip": "",
      "area": "",
      "city": "",
      "state": "NC",
      "country": "US",
      "timezone": "EST",
      "network_name": "LEVEL 3 COMMUNICATIONS, LLC -",
      "network_type": "CLEC",
      "network_domain": ""
    }
  }
}



Unauthorized
{
  "status": "failed",
  "error": {
    "error_code": 600,
    "message": "Invalid API Key or API Secret."
  }
}

{
  "status": "failed",
  "error": {
    "error_code": 601,
    "message": "API Key & API Secret are required."
  }
}

{
  "status": "failed",
  "error": {
    "error_code": 602,
    "message": "The request could not be authenticated. Only HTTP POST method is allowed."
  }
}



Payment Required
{
  "status": "failed",
  "error": {
    "error_code": 603,
    "message": "Insufficient credits are available to cover the cost of the requested operation."
  }
}

{
  "status": "failed",
  "error": {
    "error_code": 604,
    "message": "No credits are available to cover the cost of the requested operation."
  }
}



Inactive Account
{
  "status": "failed",
  "error": {
    "error_code": 605,
    "message": "Your account is not activated to use this services."
  }
}



Invalid File Format
{
  "status": "failed",
  "error": {
    "error_code": 606,
    "message": "Invalid file format, supported file format - (csv)."
  }
}



Unknown Error
{
  "status": "failed",
  "error": {
    "error_code": 607,
    "message": "Unknown error : The cause of the error is unknown but details have been passed to our support staff who will investigate. Please send error message on Support Team for immediate response."
  }
}



Phone Number(s) Required
{
  "status": "failed",
  "error": {
    "error_code": 608,
    "message": "The request doesn't contain Phone Number(s)."
  }
}



Too Many Phone Numbers
{
  "status": "failed",
  "error": {
    "error_code": 609,
    "message": "The request must not contain more then 1000 Phone Number(s)."
  }
}

cURL (Bash)

JQuery

PHP (cURL)

NodeJS

Python

Go

C#

curl \
-H "Content-Type: application/json" \
-X POST \
-d '{"api_key": "RWK0JWVM3Gp2QmtG09TStoWjhjNlB","api_secret": "f606925fd8f72ebc15a5c27e7be040","numbers": ['1234567890', '470*******', '908*******', '704*******']}' \
"https://app.realvalidito.com/phonelookup/validate"

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "status": "success",
  "data": {
    "1234567890": {
      "status": "Invalid",
      "phone_number": "1234567890",
      "national_format": "",
      "country_prefix": "",
      "number_type": "Unknown",
      "zip": "",
      "area": "",
      "city": "",
      "state": "",
      "country": "",
      "timezone": "",
      "network_name": "",
      "network_type": "",
      "network_domain": ""
    },
    "470*******": {
      "status": "Valid",
      "phone_number": "+1470*******",
      "national_format": "(470) ***-****",
      "country_prefix": "1",
      "number_type": "Mobile",
      "zip": "30097",
      "area": "",
      "city": "DULUTH",
      "state": "GA",
      "country": "US",
      "timezone": "EST (America/New_York)",
      "network_name": "CELLCO PARTNERSHIP DBA VERIZON",
      "network_type": "WIRELESS",
      "network_domain": "470*******@vtext.com"
    },
    "908*******": {
      "status": "Valid",
      "phone_number": "+1908*******",
      "national_format": "(908) ***-****",
      "country_prefix": "1",
      "number_type": "Landline",
      "zip": "07102",
      "area": "Essex",
      "city": "NEWARK",
      "state": "NJ",
      "country": "US",
      "timezone": "EST (America/New_York)",
      "network_name": "CABLEVISION LIGHTPATH, INC. -",
      "network_type": "CLEC",
      "network_domain": ""
    },
    "704*******": {
      "status": "Valid",
      "phone_number": "+1704*******",
      "national_format": "(704) ***-****",
      "country_prefix": "1",
      "number_type": "VoIP",
      "zip": "",
      "area": "",
      "city": "",
      "state": "NC",
      "country": "US",
      "timezone": "EST",
      "network_name": "LEVEL 3 COMMUNICATIONS, LLC -",
      "network_type": "CLEC",
      "network_domain": ""
    }
  }
}

var url = 'https://app.realvalidito.com/phonelookup/validate';
var api_key = 'RWK0JWVM3Gp2QmtG09TStoWjhjNlB';
var api_secret = 'f606925fd8f72ebc15a5c27e7be040';
var request = {
	api_key: api_key,
	api_secret: api_secret,
	numbers: ['1234567890', '470*******', '908*******', '704*******']
};

$.ajax(url, {
    data : JSON.stringify(request),
    contentType : 'application/json',
    type : 'POST',
    dataType: 'json',
    success: function (data,status,xhr) {
        console.log(data);
    }
});

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "status": "success",
  "data": {
    "1234567890": {
      "status": "Invalid",
      "phone_number": "1234567890",
      "national_format": "",
      "country_prefix": "",
      "number_type": "Unknown",
      "zip": "",
      "area": "",
      "city": "",
      "state": "",
      "country": "",
      "timezone": "",
      "network_name": "",
      "network_type": "",
      "network_domain": ""
    },
    "470*******": {
      "status": "Valid",
      "phone_number": "+1470*******",
      "national_format": "(470) ***-****",
      "country_prefix": "1",
      "number_type": "Mobile",
      "zip": "30097",
      "area": "",
      "city": "DULUTH",
      "state": "GA",
      "country": "US",
      "timezone": "EST (America/New_York)",
      "network_name": "CELLCO PARTNERSHIP DBA VERIZON",
      "network_type": "WIRELESS",
      "network_domain": "470*******@vtext.com"
    },
    "908*******": {
      "status": "Valid",
      "phone_number": "+1908*******",
      "national_format": "(908) ***-****",
      "country_prefix": "1",
      "number_type": "Landline",
      "zip": "07102",
      "area": "Essex",
      "city": "NEWARK",
      "state": "NJ",
      "country": "US",
      "timezone": "EST (America/New_York)",
      "network_name": "CABLEVISION LIGHTPATH, INC. -",
      "network_type": "CLEC",
      "network_domain": ""
    },
    "704*******": {
      "status": "Valid",
      "phone_number": "+1704*******",
      "national_format": "(704) ***-****",
      "country_prefix": "1",
      "number_type": "VoIP",
      "zip": "",
      "area": "",
      "city": "",
      "state": "NC",
      "country": "US",
      "timezone": "EST",
      "network_name": "LEVEL 3 COMMUNICATIONS, LLC -",
      "network_type": "CLEC",
      "network_domain": ""
    }
  }
}

$url = "https://app.realvalidito.com/phonelookup/validate";
$api_key = 'RWK0JWVM3Gp2QmtG09TStoWjhjNlB';
$api_secret = 'f606925fd8f72ebc15a5c27e7be040';
$header = array('Content-Type:application/json');
$request_array = array(
	'api_key' => $api_key,
	'api_secret' => $api_secret,
	'numbers' => array('1234567890', '470*******', '908*******', '704*******'),
);
$request = json_encode($request_array);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch,CURLOPT_POST, 1);
curl_setopt($ch,CURLOPT_POSTFIELDS, $request);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_TIMEOUT, 30);
curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
$data = curl_exec($ch);
curl_close($ch);
echo $data;

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "status": "success",
  "data": {
    "1234567890": {
      "status": "Invalid",
      "phone_number": "1234567890",
      "national_format": "",
      "country_prefix": "",
      "number_type": "Unknown",
      "zip": "",
      "area": "",
      "city": "",
      "state": "",
      "country": "",
      "timezone": "",
      "network_name": "",
      "network_type": "",
      "network_domain": ""
    },
    "470*******": {
      "status": "Valid",
      "phone_number": "+1470*******",
      "national_format": "(470) ***-****",
      "country_prefix": "1",
      "number_type": "Mobile",
      "zip": "30097",
      "area": "",
      "city": "DULUTH",
      "state": "GA",
      "country": "US",
      "timezone": "EST (America/New_York)",
      "network_name": "CELLCO PARTNERSHIP DBA VERIZON",
      "network_type": "WIRELESS",
      "network_domain": "470*******@vtext.com"
    },
    "908*******": {
      "status": "Valid",
      "phone_number": "+1908*******",
      "national_format": "(908) ***-****",
      "country_prefix": "1",
      "number_type": "Landline",
      "zip": "07102",
      "area": "Essex",
      "city": "NEWARK",
      "state": "NJ",
      "country": "US",
      "timezone": "EST (America/New_York)",
      "network_name": "CABLEVISION LIGHTPATH, INC. -",
      "network_type": "CLEC",
      "network_domain": ""
    },
    "704*******": {
      "status": "Valid",
      "phone_number": "+1704*******",
      "national_format": "(704) ***-****",
      "country_prefix": "1",
      "number_type": "VoIP",
      "zip": "",
      "area": "",
      "city": "",
      "state": "NC",
      "country": "US",
      "timezone": "EST",
      "network_name": "LEVEL 3 COMMUNICATIONS, LLC -",
      "network_type": "CLEC",
      "network_domain": ""
    }
  }
}

var request = require("request");
var options = {
 method: 'POST',
 url: 'https://app.realvalidito.com/phonelookup/validate',
 headers: {
   'Content-Type': 'application/json',
 },
 body: {
	 "api_key": "RWK0JWVM3Gp2QmtG09TStoWjhjNlB",
	 "api_secret": "f606925fd8f72ebc15a5c27e7be040",
	 "numbers": ['1234567890', '470*******', '908*******', '704*******']
 },
 json: true
};

request(options, function (err, response, body) {
  if (err) throw new Error(err);
  console.log(body);
});

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "status": "success",
  "data": {
    "1234567890": {
      "status": "Invalid",
      "phone_number": "1234567890",
      "national_format": "",
      "country_prefix": "",
      "number_type": "Unknown",
      "zip": "",
      "area": "",
      "city": "",
      "state": "",
      "country": "",
      "timezone": "",
      "network_name": "",
      "network_type": "",
      "network_domain": ""
    },
    "470*******": {
      "status": "Valid",
      "phone_number": "+1470*******",
      "national_format": "(470) ***-****",
      "country_prefix": "1",
      "number_type": "Mobile",
      "zip": "30097",
      "area": "",
      "city": "DULUTH",
      "state": "GA",
      "country": "US",
      "timezone": "EST (America/New_York)",
      "network_name": "CELLCO PARTNERSHIP DBA VERIZON",
      "network_type": "WIRELESS",
      "network_domain": "470*******@vtext.com"
    },
    "908*******": {
      "status": "Valid",
      "phone_number": "+1908*******",
      "national_format": "(908) ***-****",
      "country_prefix": "1",
      "number_type": "Landline",
      "zip": "07102",
      "area": "Essex",
      "city": "NEWARK",
      "state": "NJ",
      "country": "US",
      "timezone": "EST (America/New_York)",
      "network_name": "CABLEVISION LIGHTPATH, INC. -",
      "network_type": "CLEC",
      "network_domain": ""
    },
    "704*******": {
      "status": "Valid",
      "phone_number": "+1704*******",
      "national_format": "(704) ***-****",
      "country_prefix": "1",
      "number_type": "VoIP",
      "zip": "",
      "area": "",
      "city": "",
      "state": "NC",
      "country": "US",
      "timezone": "EST",
      "network_name": "LEVEL 3 COMMUNICATIONS, LLC -",
      "network_type": "CLEC",
      "network_domain": ""
    }
  }
}

import requests
import array
import json
url = "https://app.realvalidito.com/phonelookup/validate"
numbers = [1234567890,470*******,908*******,704*******]
payload = {
	"api_key": "RWK0JWVM3Gp2QmtG09TStoWjhjNlB",
	"api_secret": "f606925fd8f72ebc15a5c27e7be040",
	"numbers": numbers
}
headers = {
	'Content-Type': "application/json",
}
response = requests.request("POST", url, json=payload, headers=headers)
response = response.json()
print('Response: ', response, '\n')

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "status": "success",
  "data": {
    "1234567890": {
      "status": "Invalid",
      "phone_number": "1234567890",
      "national_format": "",
      "country_prefix": "",
      "number_type": "Unknown",
      "zip": "",
      "area": "",
      "city": "",
      "state": "",
      "country": "",
      "timezone": "",
      "network_name": "",
      "network_type": "",
      "network_domain": ""
    },
    "470*******": {
      "status": "Valid",
      "phone_number": "+1470*******",
      "national_format": "(470) ***-****",
      "country_prefix": "1",
      "number_type": "Mobile",
      "zip": "30097",
      "area": "",
      "city": "DULUTH",
      "state": "GA",
      "country": "US",
      "timezone": "EST (America/New_York)",
      "network_name": "CELLCO PARTNERSHIP DBA VERIZON",
      "network_type": "WIRELESS",
      "network_domain": "470*******@vtext.com"
    },
    "908*******": {
      "status": "Valid",
      "phone_number": "+1908*******",
      "national_format": "(908) ***-****",
      "country_prefix": "1",
      "number_type": "Landline",
      "zip": "07102",
      "area": "Essex",
      "city": "NEWARK",
      "state": "NJ",
      "country": "US",
      "timezone": "EST (America/New_York)",
      "network_name": "CABLEVISION LIGHTPATH, INC. -",
      "network_type": "CLEC",
      "network_domain": ""
    },
    "704*******": {
      "status": "Valid",
      "phone_number": "+1704*******",
      "national_format": "(704) ***-****",
      "country_prefix": "1",
      "number_type": "VoIP",
      "zip": "",
      "area": "",
      "city": "",
      "state": "NC",
      "country": "US",
      "timezone": "EST",
      "network_name": "LEVEL 3 COMMUNICATIONS, LLC -",
      "network_type": "CLEC",
      "network_domain": ""
    }
  }
}

package main

import (
"fmt"
"io/ioutil"
"net/http"
"strings"
"encoding/json"
)

type HttpResponseData struct {
 Data struct {
   International string `json:"international_format"`
   LineType string `json:"line_type"`
   Carrier string `json:"carrier"`
   Country string `json:"country_name"`
   Location string `json:"location"`
 } `json:"data"`
}

func main() {
  url := "https://app.realvalidito.com/phonelookup/validate"
  request := strings.NewReader('{"api_key": "RWK0JWVM3Gp2QmtG09TStoWjhjNlB","api_secret": "f606925fd8f72ebc15a5c27e7be040","numbers": ['1234567890', '470*******', '908*******', '704*******']}')
  req, _ := http.NewRequest("POST", url, request)

  req.Header.Add("Content-Type", "application/json")

  res, err := http.DefaultClient.Do(req)
  if err != nil {
      fmt.Println(err)
  } else {
    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    var response HttpResponseData
    err = json.Unmarshal(body, &response)
    if err != nil {
      fmt.Println(err)
    }
    fmt.Println(response)
  }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "status": "success",
  "data": {
    "1234567890": {
      "status": "Invalid",
      "phone_number": "1234567890",
      "national_format": "",
      "country_prefix": "",
      "number_type": "Unknown",
      "zip": "",
      "area": "",
      "city": "",
      "state": "",
      "country": "",
      "timezone": "",
      "network_name": "",
      "network_type": "",
      "network_domain": ""
    },
    "470*******": {
      "status": "Valid",
      "phone_number": "+1470*******",
      "national_format": "(470) ***-****",
      "country_prefix": "1",
      "number_type": "Mobile",
      "zip": "30097",
      "area": "",
      "city": "DULUTH",
      "state": "GA",
      "country": "US",
      "timezone": "EST (America/New_York)",
      "network_name": "CELLCO PARTNERSHIP DBA VERIZON",
      "network_type": "WIRELESS",
      "network_domain": "470*******@vtext.com"
    },
    "908*******": {
      "status": "Valid",
      "phone_number": "+1908*******",
      "national_format": "(908) ***-****",
      "country_prefix": "1",
      "number_type": "Landline",
      "zip": "07102",
      "area": "Essex",
      "city": "NEWARK",
      "state": "NJ",
      "country": "US",
      "timezone": "EST (America/New_York)",
      "network_name": "CABLEVISION LIGHTPATH, INC. -",
      "network_type": "CLEC",
      "network_domain": ""
    },
    "704*******": {
      "status": "Valid",
      "phone_number": "+1704*******",
      "national_format": "(704) ***-****",
      "country_prefix": "1",
      "number_type": "VoIP",
      "zip": "",
      "area": "",
      "city": "",
      "state": "NC",
      "country": "US",
      "timezone": "EST",
      "network_name": "LEVEL 3 COMMUNICATIONS, LLC -",
      "network_type": "CLEC",
      "network_domain": ""
    }
  }
}

using System;
using System.IO;
using System.Net;
using System.Text;
using Newtonsoft.Json.Linq;

namespace Examples.System.Net
{
    public class InstantVerifyExample
    {
        public static void Main()
        {
            WebRequest request = WebRequest.Create("https://app.realvalidito.com/phonelookup/validate");
            request.Method = "POST";
            string postData = "{\"api_key\": \"RWK0JWVM3Gp2QmtG09TStoWjhjNlB\",\"api_secret\": \"f606925fd8f72ebc15a5c27e7be040\",\"numbers\": [\"1234567890\", \"470*******\", \"908*******\", \"704*******\"]}";
            byte[] byteArray = Encoding.UTF8.GetBytes(postData);
            request.ContentType = "application/json";
            request.ContentLength = byteArray.Length;

            Stream dataStream = request.GetRequestStream();
            dataStream.Write(byteArray, 0, byteArray.Length);
            dataStream.Close();
            WebResponse response = request.GetResponse();
            dataStream = response.GetResponseStream();
            StreamReader reader = new StreamReader(dataStream);
            string responseFromServer = reader.ReadToEnd();
            JObject joResponse = JObject.Parse(responseFromServer);

            Console.WriteLine(joResponse);

            reader.Close();
            dataStream.Close();
            response.Close();
        }
    }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "status": "success",
  "data": {
    "1234567890": {
      "status": "Invalid",
      "phone_number": "1234567890",
      "national_format": "",
      "country_prefix": "",
      "number_type": "Unknown",
      "zip": "",
      "area": "",
      "city": "",
      "state": "",
      "country": "",
      "timezone": "",
      "network_name": "",
      "network_type": "",
      "network_domain": ""
    },
    "470*******": {
      "status": "Valid",
      "phone_number": "+1470*******",
      "national_format": "(470) ***-****",
      "country_prefix": "1",
      "number_type": "Mobile",
      "zip": "30097",
      "area": "",
      "city": "DULUTH",
      "state": "GA",
      "country": "US",
      "timezone": "EST (America/New_York)",
      "network_name": "CELLCO PARTNERSHIP DBA VERIZON",
      "network_type": "WIRELESS",
      "network_domain": "470*******@vtext.com"
    },
    "908*******": {
      "status": "Valid",
      "phone_number": "+1908*******",
      "national_format": "(908) ***-****",
      "country_prefix": "1",
      "number_type": "Landline",
      "zip": "07102",
      "area": "Essex",
      "city": "NEWARK",
      "state": "NJ",
      "country": "US",
      "timezone": "EST (America/New_York)",
      "network_name": "CABLEVISION LIGHTPATH, INC. -",
      "network_type": "CLEC",
      "network_domain": ""
    },
    "704*******": {
      "status": "Valid",
      "phone_number": "+1704*******",
      "national_format": "(704) ***-****",
      "country_prefix": "1",
      "number_type": "VoIP",
      "zip": "",
      "area": "",
      "city": "",
      "state": "NC",
      "country": "US",
      "timezone": "EST",
      "network_name": "LEVEL 3 COMMUNICATIONS, LLC -",
      "network_type": "CLEC",
      "network_domain": ""
    }
  }
}

Get Available Credits

GET /dnclookup/getcredits/{api_key}/{api_secret}

DNC Lookup

POST /dnclookup/validate

GET /dnclookup/getcredits/{api_key}/{api_secret}

Path variables

api_key

string required

API Key

Example:

RWK0JWVM3Gp2QmtG09TStoWjhjNlB

api_secret

string required

API Secret

Example:

f606925fd8f72ebc15a5c27e7be040

Responses

200 OK

Success

Failed


{
  "status": "success",
  "data": {
     "available_credits": 5000
   }
}



Unauthorized
{
  "status": "failed",
  "error": {
    "error_code": 600,
    "message": "Invalid API Key or API Secret."
  }
}

{
  "status": "failed",
  "error": {
    "error_code": 614,
    "message": "The request could not be authenticated. Only HTTP GET method is allowed."
  }
}

cURL (Bash)

JQuery (Javascript)

PHP (cURL)

curl -X GET 'https://app.realvalidito.com/dnclookup/getcredits/RWK0JWVM3Gp2QmtG09TStoWjhjNlB/f606925fd8f72ebc15a5c27e7be040' \

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "status": "success",
  "data": {
     "available_credits": 5000
   }
}

var api_key = 'RWK0JWVM3Gp2QmtG09TStoWjhjNlB';
var api_secret = 'f606925fd8f72ebc15a5c27e7be040';
$.ajax({
    url: 'https://app.realvalidito.com/dnclookup/getcredits/' + api_key + '/' + api_secret,
    method: 'GET',
    dataType: 'json',
    success: function(data) {
        console.log(data);       
    }
});

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "status": "success",
  "data": {

     "available_credits": 5000
   }
}

$api_key = 'RWK0JWVM3Gp2QmtG09TStoWjhjNlB';
$api_secret = 'f606925fd8f72ebc15a5c27e7be040';
$ch = curl_init('https://app.realvalidito.com/dnclookup/getcredits/' . api_key . '/' + api_secret);  
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = curl_exec($ch);
curl_close($ch);
echo $data;

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "status": "success",
  "data": {
     "available_credits": 5000
   }
}

POST /dnclookup/validate

Request body

Object

api_key

string required

API Key

Example:

RWK0JWVM3Gp2QmtG09TStoWjhjNlB

api_secret

string required

API Secret

Example:

f606925fd8f72ebc15a5c27e7be040

numbers

array required

Phone number(s) to validate

Example:

['1234567890', '812*******', '908*******', '704*******', '757*******']

Array of 10 digit, numeric phone number of USA / CANADA only. No spaces, special characters, etc. No leading +1.

Maximum of 1,000 phone numbers are permitted.

Responses

200 OK

Success

Failed


{
  "status": "success",
  "data": {
    "cleaned_number": [
      "908*******",
      "704*******"
    ],
    "tcpa_litigator": [
      "757*******",
      "812*******"
    ],
    "invalid": [
      "1234567890"
    ]
  }
}



Unauthorized
{
  "status": "failed",
  "error": {
    "error_code": 600,
    "message": "Invalid API Key or API Secret."
  }
}

{
  "status": "failed",
  "error": {
    "error_code": 601,
    "message": "API Key & API Secret are required."
  }
}

{
  "status": "failed",
  "error": {
    "error_code": 602,
    "message": "The request could not be authenticated. Only HTTP POST method is allowed."
  }
}



Payment Required
{
  "status": "failed",
  "error": {
    "error_code": 603,
    "message": "Insufficient credits are available to cover the cost of the requested operation."
  }
}

{
  "status": "failed",
  "error": {
    "error_code": 604,
    "message": "No credits are available to cover the cost of the requested operation."
  }
}



Inactive Account
{
  "status": "failed",
  "error": {
    "error_code": 605,
    "message": "Your account is not activated to use this services."
  }
}



Invalid File Format
{
  "status": "failed",
  "error": {
    "error_code": 606,
    "message": "Invalid file format, supported file format - (csv)."
  }
}



Unknown Error
{
  "status": "failed",
  "error": {
    "error_code": 607,
    "message": "Unknown error : The cause of the error is unknown but details have been passed to our support staff who will investigate. Please send error message on Support Team for immediate response."
  }
}



Phone Number(s) Required
{
  "status": "failed",
  "error": {
    "error_code": 608,
    "message": "The request doesn't contain Phone Number(s)."
  }
}



Too Many Phone Numbers
{
  "status": "failed",
  "error": {
    "error_code": 609,
    "message": "The request must not contain more then 1000 Phone Number(s)."
  }
}

cURL (Bash)

JQuery

PHP (cURL)

NodeJS

Python

Go

C#

curl \
-H "Content-Type: application/json" \
-X POST \
-d '{"api_key": "RWK0JWVM3Gp2QmtG09TStoWjhjNlB","api_secret": "f606925fd8f72ebc15a5c27e7be040","numbers": ['1234567890', '812*******', '908*******', '704*******', '757*******']}' \
"https://app.realvalidito.com/dnclookup/validate"

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "status": "success",
  "data": {
    "cleaned_number": [
      "908*******",
      "704*******"
    ],
    "tcpa_litigator": [
      "757*******",
      "812*******"
    ],
    "invalid": [
      "1234567890"
    ]
  }
}

var url = 'https://app.realvalidito.com/dnclookup/validate';
var api_key = 'RWK0JWVM3Gp2QmtG09TStoWjhjNlB';
var api_secret = 'f606925fd8f72ebc15a5c27e7be040';
var request = {
	api_key: api_key,
	api_secret: api_secret,
	numbers: ['1234567890', '812*******', '908*******', '704*******', '757*******']
};

$.ajax(url, {
    data : JSON.stringify(request),
    contentType : 'application/json',
    type : 'POST',
    dataType: 'json',
    success: function (data,status,xhr) {
        console.log(data);
    }
});

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "status": "success",
  "data": {
    "cleaned_number": [
      "908*******",
      "704*******"
    ],
    "tcpa_litigator": [
      "757*******",
      "812*******"
    ],
    "invalid": [
      "1234567890"
    ]
  }
}

$url = "https://app.realvalidito.com/dnclookup/validate";
$api_key = 'RWK0JWVM3Gp2QmtG09TStoWjhjNlB';
$api_secret = 'f606925fd8f72ebc15a5c27e7be040';
$header = array('Content-Type:application/json');
$request_array = array(
	'api_key' => $api_key,
	'api_secret' => $api_secret,
	'numbers' => array('1234567890', '812*******', '908*******', '704*******', '757*******'),
);
$request = json_encode($request_array);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch,CURLOPT_POST, 1);
curl_setopt($ch,CURLOPT_POSTFIELDS, $request);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_TIMEOUT, 30);
curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
$data = curl_exec($ch);
curl_close($ch);
echo $data;

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "status": "success",
  "data": {
    "cleaned_number": [
      "908*******",
      "704*******"
    ],
    "tcpa_litigator": [
      "757*******",
      "812*******"
    ],
    "invalid": [
      "1234567890"
    ]
  }
}

var request = require("request");
var options = {
 method: 'POST',
 url: 'https://app.realvalidito.com/dnclookup/validate',
 headers: {
   'Content-Type': 'application/json',
 },
 body: {
	 "api_key": "RWK0JWVM3Gp2QmtG09TStoWjhjNlB",
	 "api_secret": "f606925fd8f72ebc15a5c27e7be040",
	 "numbers": ['1234567890', '812*******', '908*******', '704*******', '757*******']
 },
 json: true
};

request(options, function (err, response, body) {
  if (err) throw new Error(err);
  console.log(body);
});

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "status": "success",
  "data": {
    "cleaned_number": [
      "908*******",
      "704*******"
    ],
    "tcpa_litigator": [
      "757*******",
      "812*******"
    ],
    "invalid": [
      "1234567890"
    ]
  }
}

import requests
import array
import json
url = "https://app.realvalidito.com/dnclookup/validate"
numbers = [1234567890,812*******,908*******,704*******,757*******]
payload = {
	"api_key": "RWK0JWVM3Gp2QmtG09TStoWjhjNlB",
	"api_secret": "f606925fd8f72ebc15a5c27e7be040",
	"numbers": numbers
}
headers = {
	'Content-Type': "application/json",
}
response = requests.request("POST", url, json=payload, headers=headers)
response = response.json()
print('Response: ', response, '\n')

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "status": "success",
  "data": {
    "cleaned_number": [
      "908*******",
      "704*******"
    ],
    "tcpa_litigator": [
      "757*******",
      "812*******"
    ],
    "invalid": [
      "1234567890"
    ]
  }
}

package main

import (
"fmt"
"io/ioutil"
"net/http"
"strings"
"encoding/json"
)

type HttpResponseData struct {
 Data struct {
   International string `json:"international_format"`
   LineType string `json:"line_type"`
   Carrier string `json:"carrier"`
   Country string `json:"country_name"`
   Location string `json:"location"`
 } `json:"data"`
}

func main() {
  url := "https://app.realvalidito.com/dnclookup/validate"
  request := strings.NewReader('{"api_key": "RWK0JWVM3Gp2QmtG09TStoWjhjNlB","api_secret": "f606925fd8f72ebc15a5c27e7be040","numbers": ['1234567890', '812*******', '908*******', '704*******', '757*******']}')
  req, _ := http.NewRequest("POST", url, request)

  req.Header.Add("Content-Type", "application/json")

  res, err := http.DefaultClient.Do(req)
  if err != nil {
      fmt.Println(err)
  } else {
    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    var response HttpResponseData
    err = json.Unmarshal(body, &response)
    if err != nil {
      fmt.Println(err)
    }
    fmt.Println(response)
  }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "status": "success",
  "data": {
    "cleaned_number": [
      "908*******",
      "704*******"
    ],
    "tcpa_litigator": [
      "757*******",
      "812*******"
    ],
    "invalid": [
      "1234567890"
    ]
  }
}

using System;
using System.IO;
using System.Net;
using System.Text;
using Newtonsoft.Json.Linq;

namespace Examples.System.Net
{
    public class InstantVerifyExample
    {
        public static void Main()
        {
            WebRequest request = WebRequest.Create("https://app.realvalidito.com/dnclookup/validate");
            request.Method = "POST";
            string postData = "{\"api_key\": \"RWK0JWVM3Gp2QmtG09TStoWjhjNlB\",\"api_secret\": \"f606925fd8f72ebc15a5c27e7be040\",\"numbers\": [\"1234567890\", \"812*******\", \"908*******\", \"704*******\", \"757*******\"]}";
            byte[] byteArray = Encoding.UTF8.GetBytes(postData);
            request.ContentType = "application/json";
            request.ContentLength = byteArray.Length;

            Stream dataStream = request.GetRequestStream();
            dataStream.Write(byteArray, 0, byteArray.Length);
            dataStream.Close();
            WebResponse response = request.GetResponse();
            dataStream = response.GetResponseStream();
            StreamReader reader = new StreamReader(dataStream);
            string responseFromServer = reader.ReadToEnd();
            JObject joResponse = JObject.Parse(responseFromServer);

            Console.WriteLine(joResponse);

            reader.Close();
            dataStream.Close();
            response.Close();
        }
    }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "status": "success",
  "data": {
    "cleaned_number": [
      "908*******",
      "704*******"
    ],
    "tcpa_litigator": [
      "757*******",
      "812*******"
    ],
    "invalid": [
      "1234567890"
    ]
  }
}

Get Available Credits

GET /genderlookup/getcredits/{api_key}/{api_secret}

Gender Lookup

POST /genderlookup/validate

GET /genderlookup/getcredits/{api_key}/{api_secret}

Path variables

api_key

string required

API Key

Example:

RWK0JWVM3Gp2QmtG09TStoWjhjNlB

api_secret

string required

API Secret

Example:

f606925fd8f72ebc15a5c27e7be040

Responses

200 OK

Success

Failed


{
  "status": "success",
  "data": {
     "available_credits": 5000
   }
}



Unauthorized
{
  "status": "failed",
  "error": {
    "error_code": 600,
    "message": "Invalid API Key or API Secret."
  }
}

{
  "status": "failed",
  "error": {
    "error_code": 614,
    "message": "The request could not be authenticated. Only HTTP GET method is allowed."
  }
}

cURL (Bash)

JQuery (Javascript)

PHP (cURL)

curl -X GET 'https://app.realvalidito.com/genderlookup/getcredits/RWK0JWVM3Gp2QmtG09TStoWjhjNlB/f606925fd8f72ebc15a5c27e7be040' \

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "status": "success",
  "data": {
     "available_credits": 5000
   }
}

var api_key = 'RWK0JWVM3Gp2QmtG09TStoWjhjNlB';
var api_secret = 'f606925fd8f72ebc15a5c27e7be040';
$.ajax({
    url: 'https://app.realvalidito.com/genderlookup/getcredits/' + api_key + '/' + api_secret,
    method: 'GET',
    dataType: 'json',
    success: function(data) {
        console.log(data);       
    }
});

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "status": "success",
  "data": {

     "available_credits": 5000
   }
}

$api_key = 'RWK0JWVM3Gp2QmtG09TStoWjhjNlB';
$api_secret = 'f606925fd8f72ebc15a5c27e7be040';
$ch = curl_init('https://app.realvalidito.com/genderlookup/getcredits/' . api_key . '/' + api_secret);  
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = curl_exec($ch);
curl_close($ch);
echo $data;

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "status": "success",
  "data": {
     "available_credits": 5000
   }
}

POST /genderlookup/validate

Request body

Object

api_key

string required

API Key

Example:

RWK0JWVM3Gp2QmtG09TStoWjhjNlB

api_secret

string required

API Secret

Example:

f606925fd8f72ebc15a5c27e7be040

names

array required

Customer's Name(s)

Example:

['Aabel', 'Delain', 'Kecha', 'Vincenzzo', 'Shade', 'Cracker', 'Yes']

Array of Customer's Name(s).

Maximum of 1,000 names are permitted.

Responses

200 OK

Success

Failed


{
  "status": "success",
  "data": {
    "valid_names": {
      "Aabel": "Male",
      "Delain": "Unisex",
      "Kecha": "Female",
      "Vincenzzo": "Male",
      "Shade": "Unisex"
    },
    "salacious_names": [
      "Cracker"
    ],
    "random_names": [
      "Yes"
    ],
    "incomplete_names": []
  }
}



Unauthorized
{
  "status": "failed",
  "error": {
    "error_code": 600,
    "message": "Invalid API Key or API Secret."
  }
}

{
  "status": "failed",
  "error": {
    "error_code": 601,
    "message": "API Key & API Secret are required."
  }
}

{
  "status": "failed",
  "error": {
    "error_code": 602,
    "message": "The request could not be authenticated. Only HTTP POST method is allowed."
  }
}



Payment Required
{
  "status": "failed",
  "error": {
    "error_code": 603,
    "message": "Insufficient credits are available to cover the cost of the requested operation."
  }
}

{
  "status": "failed",
  "error": {
    "error_code": 604,
    "message": "No credits are available to cover the cost of the requested operation."
  }
}



Inactive Account
{
  "status": "failed",
  "error": {
    "error_code": 605,
    "message": "Your account is not activated to use this services."
  }
}



Invalid File Format
{
  "status": "failed",
  "error": {
    "error_code": 606,
    "message": "Invalid file format, supported file format - (csv)."
  }
}



Unknown Error
{
  "status": "failed",
  "error": {
    "error_code": 607,
    "message": "Unknown error : The cause of the error is unknown but details have been passed to our support staff who will investigate. Please send error message on Support Team for immediate response."
  }
}



Name(s) Required
{
  "status": "failed",
  "error": {
    "error_code": 610,
    "message": "The request doesn't contain Name(s)."
  }
}



Too Many Names
{
  "status": "failed",
  "error": {
    "error_code": 611,
    "message": "The request must not contain more then 1000 Name(s)."
  }
}

cURL (Bash)

JQuery

PHP (cURL)

NodeJS

Python

Go

C#

curl \
-H "Content-Type: application/json" \
-X POST \
-d '{"api_key": "RWK0JWVM3Gp2QmtG09TStoWjhjNlB","api_secret": "f606925fd8f72ebc15a5c27e7be040","names": ['Aabel', 'Delain', 'Kecha', 'Vincenzzo', 'Shade', 'Cracker', 'Yes']}' \
"https://app.realvalidito.com/genderlookup/validate"

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "status": "success",
  "data": {
    "valid_names": {
      "Aabel": "Male",
      "Delain": "Unisex",
      "Kecha": "Female",
      "Vincenzzo": "Male",
      "Shade": "Unisex"
    },
    "salacious_names": [
      "Cracker"
    ],
    "random_names": [
      "Yes"
    ],
    "incomplete_names": []
  }
}

var url = 'https://app.realvalidito.com/genderlookup/validate';
var api_key = 'RWK0JWVM3Gp2QmtG09TStoWjhjNlB';
var api_secret = 'f606925fd8f72ebc15a5c27e7be040';
var request = {
	api_key: api_key,
	api_secret: api_secret,
	names: ['Aabel', 'Delain', 'Kecha', 'Vincenzzo', 'Shade', 'Cracker', 'Yes']
};

$.ajax(url, {
    data : JSON.stringify(request),
    contentType : 'application/json',
    type : 'POST',
    dataType: 'json',
    success: function (data,status,xhr) {
        console.log(data);
    }
});

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "status": "success",
  "data": {
    "valid_names": {
      "Aabel": "Male",
      "Delain": "Unisex",
      "Kecha": "Female",
      "Vincenzzo": "Male",
      "Shade": "Unisex"
    },
    "salacious_names": [
      "Cracker"
    ],
    "random_names": [
      "Yes"
    ],
    "incomplete_names": []
  }
}

$url = "https://app.realvalidito.com/genderlookup/validate";
$api_key = 'RWK0JWVM3Gp2QmtG09TStoWjhjNlB';
$api_secret = 'f606925fd8f72ebc15a5c27e7be040';
$header = array('Content-Type:application/json');
$request_array = array(
	'api_key' => $api_key,
	'api_secret' => $api_secret,
	'names' => array('Aabel', 'Delain', 'Kecha', 'Vincenzzo', 'Shade', 'Cracker', 'Yes'),
);
$request = json_encode($request_array);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch,CURLOPT_POST, 1);
curl_setopt($ch,CURLOPT_POSTFIELDS, $request);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_TIMEOUT, 30);
curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
$data = curl_exec($ch);
curl_close($ch);
echo $data;

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "status": "success",
  "data": {
    "valid_names": {
      "Aabel": "Male",
      "Delain": "Unisex",
      "Kecha": "Female",
      "Vincenzzo": "Male",
      "Shade": "Unisex"
    },
    "salacious_names": [
      "Cracker"
    ],
    "random_names": [
      "Yes"
    ],
    "incomplete_names": []
  }
}

var request = require("request");
var options = {
 method: 'POST',
 url: 'https://app.realvalidito.com/genderlookup/validate',
 headers: {
   'Content-Type': 'application/json',
 },
 body: {
	 "api_key": "RWK0JWVM3Gp2QmtG09TStoWjhjNlB",
	 "api_secret": "f606925fd8f72ebc15a5c27e7be040",
	 "names": ['Aabel', 'Delain', 'Kecha', 'Vincenzzo', 'Shade', 'Cracker', 'Yes']
 },
 json: true
};

request(options, function (err, response, body) {
  if (err) throw new Error(err);
  console.log(body);
});

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "status": "success",
  "data": {
    "valid_names": {
      "Aabel": "Male",
      "Delain": "Unisex",
      "Kecha": "Female",
      "Vincenzzo": "Male",
      "Shade": "Unisex"
    },
    "salacious_names": [
      "Cracker"
    ],
    "random_names": [
      "Yes"
    ],
    "incomplete_names": []
  }
}

import requests
import array
import json
url = "https://app.realvalidito.com/genderlookup/validate"
names = ["Aabel", "Delain", "Kecha", "Vincenzzo", "Shade", "Cracker", "Yes"]
payload = {
	"api_key": "RWK0JWVM3Gp2QmtG09TStoWjhjNlB",
	"api_secret": "f606925fd8f72ebc15a5c27e7be040",
	"names": names
}
headers = {
	'Content-Type': "application/json",
}
response = requests.request("POST", url, json=payload, headers=headers)
response = response.json()
print('Response: ', response, '\n')

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "status": "success",
  "data": {
    "valid_names": {
      "Aabel": "Male",
      "Delain": "Unisex",
      "Kecha": "Female",
      "Vincenzzo": "Male",
      "Shade": "Unisex"
    },
    "salacious_names": [
      "Cracker"
    ],
    "random_names": [
      "Yes"
    ],
    "incomplete_names": []
  }
}

package main

import (
"fmt"
"io/ioutil"
"net/http"
"strings"
"encoding/json"
)

type HttpResponseData struct {
 Data struct {
   International string `json:"international_format"`
   LineType string `json:"line_type"`
   Carrier string `json:"carrier"`
   Country string `json:"country_name"`
   Location string `json:"location"`
 } `json:"data"`
}

func main() {
  url := "https://app.realvalidito.com/genderlookup/validate"
  request := strings.NewReader('{"api_key": "RWK0JWVM3Gp2QmtG09TStoWjhjNlB","api_secret": "f606925fd8f72ebc15a5c27e7be040","names": ['Aabel', 'Delain', 'Kecha', 'Vincenzzo', 'Shade', 'Cracker', 'Yes']}')
  req, _ := http.NewRequest("POST", url, request)

  req.Header.Add("Content-Type", "application/json")

  res, err := http.DefaultClient.Do(req)
  if err != nil {
      fmt.Println(err)
  } else {
    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    var response HttpResponseData
    err = json.Unmarshal(body, &response)
    if err != nil {
      fmt.Println(err)
    }
    fmt.Println(response)
  }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "status": "success",
  "data": {
    "valid_names": {
      "Aabel": "Male",
      "Delain": "Unisex",
      "Kecha": "Female",
      "Vincenzzo": "Male",
      "Shade": "Unisex"
    },
    "salacious_names": [
      "Cracker"
    ],
    "random_names": [
      "Yes"
    ],
    "incomplete_names": []
  }
}

using System;
using System.IO;
using System.Net;
using System.Text;
using Newtonsoft.Json.Linq;

namespace Examples.System.Net
{
    public class InstantVerifyExample
    {
        public static void Main()
        {
            WebRequest request = WebRequest.Create("https://app.realvalidito.com/genderlookup/validate");
            request.Method = "POST";
            string postData = "{\"api_key\": \"RWK0JWVM3Gp2QmtG09TStoWjhjNlB\",\"api_secret\": \"f606925fd8f72ebc15a5c27e7be040\",\"names\": [\"Aabel\", \"Delain\", \"Kecha\", \"Vincenzzo\", \"Shade\", \"Cracker\", \"Yes\"]}";
            byte[] byteArray = Encoding.UTF8.GetBytes(postData);
            request.ContentType = "application/json";
            request.ContentLength = byteArray.Length;

            Stream dataStream = request.GetRequestStream();
            dataStream.Write(byteArray, 0, byteArray.Length);
            dataStream.Close();
            WebResponse response = request.GetResponse();
            dataStream = response.GetResponseStream();
            StreamReader reader = new StreamReader(dataStream);
            string responseFromServer = reader.ReadToEnd();
            JObject joResponse = JObject.Parse(responseFromServer);

            Console.WriteLine(joResponse);

            reader.Close();
            dataStream.Close();
            response.Close();
        }
    }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "status": "success",
  "data": {
    "valid_names": {
      "Aabel": "Male",
      "Delain": "Unisex",
      "Kecha": "Female",
      "Vincenzzo": "Male",
      "Shade": "Unisex"
    },
    "salacious_names": [
      "Cracker"
    ],
    "random_names": [
      "Yes"
    ],
    "incomplete_names": []
  }
}

Get Available Credits

GET /ziplookup/getcredits/{api_key}/{api_secret}

ZIP Code Lookup

POST /ziplookup/validate

GET /ziplookup/getcredits/{api_key}/{api_secret}

Path variables

api_key

string required

API Key

Example:

RWK0JWVM3Gp2QmtG09TStoWjhjNlB

api_secret

string required

API Secret

Example:

f606925fd8f72ebc15a5c27e7be040

Responses

200 OK

Success

Failed


{
  "status": "success",
  "data": {
     "available_credits": 5000
   }
}



Unauthorized
{
  "status": "failed",
  "error": {
    "error_code": 600,
    "message": "Invalid API Key or API Secret."
  }
}

{
  "status": "failed",
  "error": {
    "error_code": 614,
    "message": "The request could not be authenticated. Only HTTP GET method is allowed."
  }
}

cURL (Bash)

JQuery (Javascript)

PHP (cURL)

curl -X GET 'https://app.realvalidito.com/ziplookup/getcredits/RWK0JWVM3Gp2QmtG09TStoWjhjNlB/f606925fd8f72ebc15a5c27e7be040' \

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "status": "success",
  "data": {
     "available_credits": 5000
   }
}

var api_key = 'RWK0JWVM3Gp2QmtG09TStoWjhjNlB';
var api_secret = 'f606925fd8f72ebc15a5c27e7be040';
$.ajax({
    url: 'https://app.realvalidito.com/ziplookup/getcredits/' + api_key + '/' + api_secret,
    method: 'GET',
    dataType: 'json',
    success: function(data) {
        console.log(data);       
    }
});

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "status": "success",
  "data": {

     "available_credits": 5000
   }
}

$api_key = 'RWK0JWVM3Gp2QmtG09TStoWjhjNlB';
$api_secret = 'f606925fd8f72ebc15a5c27e7be040';
$ch = curl_init('https://app.realvalidito.com/ziplookup/getcredits/' . api_key . '/' + api_secret);  
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = curl_exec($ch);
curl_close($ch);
echo $data;

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "status": "success",
  "data": {
     "available_credits": 5000
   }
}

POST /ziplookup/validate

Request body

Object

api_key

string required

API Key

Example:

RWK0JWVM3Gp2QmtG09TStoWjhjNlB

api_secret

string required

API Secret

Example:

f606925fd8f72ebc15a5c27e7be040

zipcodes

array required

Zip Code(s) to validate

Example:

['12345', 'Y1A 6V6', '99835', '49032', '00000', '35004','11111']

Array of zip/postal codes of USA / CANADA only. No special characters, etc.

Maximum of 1,000 zip codes are permitted.

Responses

200 OK

Success

Failed


{
  "status": "success",
  "data": {
    "valid_zipcodes": {
      "12345": {
        "state": "New York (NY)",
        "county": "Schenectady County",
        "country": "US",
        "timezone": "America/New_York",
        "type": "UNIQUE",
        "area_codes": "518",
        "latitude": "42.8",
        "longitude": "-73.92",
        "estimated_population": "48",
        "city": "Schenectady"
      },
      "35004": {
        "state": "Alabama (AL)",
        "county": "St. Clair County",
        "country": "US",
        "timezone": "America/Chicago",
        "type": "STANDARD",
        "area_codes": "205",
        "latitude": "33.59",
        "longitude": "-86.49",
        "estimated_population": "10440",
        "city": "Moody"
      },
      "49032": {
        "state": "Michigan (MI)",
        "county": "St. Joseph County",
        "country": "US",
        "timezone": "America/Detroit",
        "type": "STANDARD",
        "area_codes": "269",
        "latitude": "41.92",
        "longitude": "-85.52",
        "estimated_population": "2780",
        "city": "Centreville"
      },
      "99835": {
        "state": "Alaska (AK)",
        "county": "Sitka City and Borough",
        "country": "US",
        "timezone": "America/Sitka",
        "type": "STANDARD",
        "area_codes": "907",
        "latitude": "56.73",
        "longitude": "-135",
        "estimated_population": "7550",
        "city": "Sitka"
      },
      "Y1A 6V6": {
        "state": "Yukon (YT)",
        "county": "",
        "country": "CA",
        "timezone": "Pacific Standard Time (PST)",
        "type": "",
        "area_codes": "",
        "latitude": "60.706299",
        "longitude": "-135.115264",
        "estimated_population": "",
        "city": "WHITEHORSE"
      }
    },
    "invalid_zipcodes": [
      "11111"
    ]
  }
}



Unauthorized
{
  "status": "failed",
  "error": {
    "error_code": 600,
    "message": "Invalid API Key or API Secret."
  }
}

{
  "status": "failed",
  "error": {
    "error_code": 601,
    "message": "API Key & API Secret are required."
  }
}

{
  "status": "failed",
  "error": {
    "error_code": 602,
    "message": "The request could not be authenticated. Only HTTP POST method is allowed."
  }
}



Payment Required
{
  "status": "failed",
  "error": {
    "error_code": 603,
    "message": "Insufficient credits are available to cover the cost of the requested operation."
  }
}

{
  "status": "failed",
  "error": {
    "error_code": 604,
    "message": "No credits are available to cover the cost of the requested operation."
  }
}



Inactive Account
{
  "status": "failed",
  "error": {
    "error_code": 605,
    "message": "Your account is not activated to use this services."
  }
}



Invalid File Format
{
  "status": "failed",
  "error": {
    "error_code": 606,
    "message": "Invalid file format, supported file format - (csv)."
  }
}



Unknown Error
{
  "status": "failed",
  "error": {
    "error_code": 607,
    "message": "Unknown error : The cause of the error is unknown but details have been passed to our support staff who will investigate. Please send error message on Support Team for immediate response."
  }
}



Zip Code(s) Required
{
  "status": "failed",
  "error": {
    "error_code": 612,
    "message": "The request doesn't contain Zip Code(s)."
  }
}



Too Many Zip Codes
{
  "status": "failed",
  "error": {
    "error_code": 613,
    "message": "The request must not contain more then 1000 Zip Code(s)."
  }
}

cURL (Bash)

JQuery

PHP (cURL)

NodeJS

Python

Go

C#

curl \
-H "Content-Type: application/json" \
-X POST \
-d '{"api_key": "RWK0JWVM3Gp2QmtG09TStoWjhjNlB","api_secret": "f606925fd8f72ebc15a5c27e7be040","zipcodes": ['12345', '01010', '99835', '49032', '00000', '35004','11111']}' \
"https://app.realvalidito.com/ziplookup/validate"

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "status": "success",
  "data": {
    "valid_zipcodes": {
      "12345": {
        "state": "New York (NY)",
        "county": "Schenectady County",
        "country": "US",
        "timezone": "America/New_York",
        "type": "UNIQUE",
        "area_codes": "518",
        "latitude": "42.8",
        "longitude": "-73.92",
        "estimated_population": "48",
        "city": "Schenectady"
      },
      "35004": {
        "state": "Alabama (AL)",
        "county": "St. Clair County",
        "country": "US",
        "timezone": "America/Chicago",
        "type": "STANDARD",
        "area_codes": "205",
        "latitude": "33.59",
        "longitude": "-86.49",
        "estimated_population": "10440",
        "city": "Moody"
      },
      "49032": {
        "state": "Michigan (MI)",
        "county": "St. Joseph County",
        "country": "US",
        "timezone": "America/Detroit",
        "type": "STANDARD",
        "area_codes": "269",
        "latitude": "41.92",
        "longitude": "-85.52",
        "estimated_population": "2780",
        "city": "Centreville"
      },
      "99835": {
        "state": "Alaska (AK)",
        "county": "Sitka City and Borough",
        "country": "US",
        "timezone": "America/Sitka",
        "type": "STANDARD",
        "area_codes": "907",
        "latitude": "56.73",
        "longitude": "-135",
        "estimated_population": "7550",
        "city": "Sitka"
      },
      "Y1A 6V6": {
        "state": "Yukon (YT)",
        "county": "",
        "country": "CA",
        "timezone": "Pacific Standard Time (PST)",
        "type": "",
        "area_codes": "",
        "latitude": "60.706299",
        "longitude": "-135.115264",
        "estimated_population": "",
        "city": "WHITEHORSE"
      }
    },
    "invalid_zipcodes": [
      "11111"
    ]
  }
}

var url = 'https://app.realvalidito.com/ziplookup/validate';
var api_key = 'RWK0JWVM3Gp2QmtG09TStoWjhjNlB';
var api_secret = 'f606925fd8f72ebc15a5c27e7be040';
var request = {
	api_key: api_key,
	api_secret: api_secret,
	zipcodes: ['12345', '01010', '99835', '49032', '00000', '35004','11111']
};

$.ajax(url, {
    data : JSON.stringify(request),
    contentType : 'application/json',
    type : 'POST',
    dataType: 'json',
    success: function (data,status,xhr) {
        console.log(data);
    }
});

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "status": "success",
  "data": {
    "valid_zipcodes": {
      "12345": {
        "city": "SCHENECTADY",
        "state": "NY"
      },
      "35004": {
        "city": "MOODY",
        "state": "AL"
      },
      "49032": {
        "city": "CENTREVILLE",
        "state": "MI"
      },
      "99835": {
        "city": "SITKA",
        "state": "AK"
      },
      "01010": {
        "city": "BRIMFIELD",
        "state": "MA"
      }
    },
    "invalid_zipcodes": [
      "00000",
      "11111"
    ]
  }
}

$url = "https://app.realvalidito.com/ziplookup/validate";
$api_key = 'RWK0JWVM3Gp2QmtG09TStoWjhjNlB';
$api_secret = 'f606925fd8f72ebc15a5c27e7be040';
$header = array('Content-Type:application/json');
$request_array = array(
	'api_key' => $api_key,
	'api_secret' => $api_secret,
	'zipcodes' => array('1234567890', '470*******', '908*******', '704*******'),
);
$request = json_encode($request_array);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch,CURLOPT_POST, 1);
curl_setopt($ch,CURLOPT_POSTFIELDS, $request);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_TIMEOUT, 30);
curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
$data = curl_exec($ch);
curl_close($ch);
echo $data;

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "status": "success",
  "data": {
    "valid_zipcodes": {
      "12345": {
        "city": "SCHENECTADY",
        "state": "NY"
      },
      "35004": {
        "city": "MOODY",
        "state": "AL"
      },
      "49032": {
        "city": "CENTREVILLE",
        "state": "MI"
      },
      "99835": {
        "city": "SITKA",
        "state": "AK"
      },
      "01010": {
        "city": "BRIMFIELD",
        "state": "MA"
      }
    },
    "invalid_zipcodes": [
      "00000",
      "11111"
    ]
  }
}

var request = require("request");
var options = {
 method: 'POST',
 url: 'https://app.realvalidito.com/ziplookup/validate',
 headers: {
   'Content-Type': 'application/json',
 },
 body: {
	 "api_key": "RWK0JWVM3Gp2QmtG09TStoWjhjNlB",
	 "api_secret": "f606925fd8f72ebc15a5c27e7be040",
	 "zipcodes": ['12345', '01010', '99835', '49032', '00000', '35004','11111']
 },
 json: true
};

request(options, function (err, response, body) {
  if (err) throw new Error(err);
  console.log(body);
});

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "status": "success",
  "data": {
    "valid_zipcodes": {
      "12345": {
        "city": "SCHENECTADY",
        "state": "NY"
      },
      "35004": {
        "city": "MOODY",
        "state": "AL"
      },
      "49032": {
        "city": "CENTREVILLE",
        "state": "MI"
      },
      "99835": {
        "city": "SITKA",
        "state": "AK"
      },
      "01010": {
        "city": "BRIMFIELD",
        "state": "MA"
      }
    },
    "invalid_zipcodes": [
      "00000",
      "11111"
    ]
  }
}

import requests
import array
import json
url = "https://app.realvalidito.com/ziplookup/validate"
zipcodes = [12345,01010,99835,49032,00000,35004,11111]
payload = {
	"api_key": "RWK0JWVM3Gp2QmtG09TStoWjhjNlB",
	"api_secret": "f606925fd8f72ebc15a5c27e7be040",
	"zipcodes": zipcodes
}
headers = {
	'Content-Type': "application/json",
}
response = requests.request("POST", url, json=payload, headers=headers)
response = response.json()
print('Response: ', response, '\n')

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "status": "success",
  "data": {
    "valid_zipcodes": {
      "12345": {
        "city": "SCHENECTADY",
        "state": "NY"
      },
      "35004": {
        "city": "MOODY",
        "state": "AL"
      },
      "49032": {
        "city": "CENTREVILLE",
        "state": "MI"
      },
      "99835": {
        "city": "SITKA",
        "state": "AK"
      },
      "01010": {
        "city": "BRIMFIELD",
        "state": "MA"
      }
    },
    "invalid_zipcodes": [
      "00000",
      "11111"
    ]
  }
}

package main

import (
"fmt"
"io/ioutil"
"net/http"
"strings"
"encoding/json"
)

type HttpResponseData struct {
 Data struct {
   International string `json:"international_format"`
   LineType string `json:"line_type"`
   Carrier string `json:"carrier"`
   Country string `json:"country_name"`
   Location string `json:"location"`
 } `json:"data"`
}

func main() {
  url := "https://app.realvalidito.com/ziplookup/validate"
  request := strings.NewReader('{"api_key": "RWK0JWVM3Gp2QmtG09TStoWjhjNlB","api_secret": "f606925fd8f72ebc15a5c27e7be040","zipcodes": ['12345', '01010', '99835', '49032', '00000', '35004','11111']}')
  req, _ := http.NewRequest("POST", url, request)

  req.Header.Add("Content-Type", "application/json")

  res, err := http.DefaultClient.Do(req)
  if err != nil {
      fmt.Println(err)
  } else {
    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    var response HttpResponseData
    err = json.Unmarshal(body, &response)
    if err != nil {
      fmt.Println(err)
    }
    fmt.Println(response)
  }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "status": "success",
  "data": {
    "valid_zipcodes": {
      "12345": {
        "city": "SCHENECTADY",
        "state": "NY"
      },
      "35004": {
        "city": "MOODY",
        "state": "AL"
      },
      "49032": {
        "city": "CENTREVILLE",
        "state": "MI"
      },
      "99835": {
        "city": "SITKA",
        "state": "AK"
      },
      "01010": {
        "city": "BRIMFIELD",
        "state": "MA"
      }
    },
    "invalid_zipcodes": [
      "00000",
      "11111"
    ]
  }
}

using System;
using System.IO;
using System.Net;
using System.Text;
using Newtonsoft.Json.Linq;

namespace Examples.System.Net
{
    public class InstantVerifyExample
    {
        public static void Main()
        {
            WebRequest request = WebRequest.Create("https://app.realvalidito.com/ziplookup/validate");
            request.Method = "POST";
            string postData = "{\"api_key\": \"RWK0JWVM3Gp2QmtG09TStoWjhjNlB\",\"api_secret\": \"f606925fd8f72ebc15a5c27e7be040\",\"zipcodes\": [\"12345\", \"01010\", \"99835\", \"49032\", \"00000\", \"35004\",\"11111\"]}";
            byte[] byteArray = Encoding.UTF8.GetBytes(postData);
            request.ContentType = "application/json";
            request.ContentLength = byteArray.Length;

            Stream dataStream = request.GetRequestStream();
            dataStream.Write(byteArray, 0, byteArray.Length);
            dataStream.Close();
            WebResponse response = request.GetResponse();
            dataStream = response.GetResponseStream();
            StreamReader reader = new StreamReader(dataStream);
            string responseFromServer = reader.ReadToEnd();
            JObject joResponse = JObject.Parse(responseFromServer);

            Console.WriteLine(joResponse);

            reader.Close();
            dataStream.Close();
            response.Close();
        }
    }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "status": "success",
  "data": {
    "valid_zipcodes": {
      "12345": {
        "city": "SCHENECTADY",
        "state": "NY"
      },
      "35004": {
        "city": "MOODY",
        "state": "AL"
      },
      "49032": {
        "city": "CENTREVILLE",
        "state": "MI"
      },
      "99835": {
        "city": "SITKA",
        "state": "AK"
      },
      "01010": {
        "city": "BRIMFIELD",
        "state": "MA"
      }
    },
    "invalid_zipcodes": [
      "00000",
      "11111"
    ]
  }
}

200

Successful requests will receive a 200 response code

500

Internal Server Error

503

Service unavailable

524

Request Timeout

RealValidito Error Codes

600

Invalid API Key or API Secret.

601

API Key & API Secret are required.

602

The request could not be authenticated. Only HTTP POST method is allowed.

603

Insufficient credits are available to cover the cost of the requested operation.

604

No credits are available to cover the cost of the requested operation.

605

Your account is not activated to use this services.

606

Invalid file format, supported file format - (csv).

607

Unknown error : The cause of the error is unknown but details have been passed to our support staff who will investigate. Please send error message on Support Team for immediate response.

608

The request doesn't contain Phone Number(s).

609

The request must not contain more then 1000 Phone Number(s).

610

The request doesn't contain Name(s).

611

The request must not contain more then 1000 Name(s).

612

The request doesn't contain Zip/Postal Code(s).

613

The request must not contain more then 1000 Zip/Postal Code(s).

614

The request could not be authenticated. Only HTTP GET method is allowed.

615

This old API endpoint is deprecated, please use new Lookup APIs instead.

RealValidito Lookup API Documentation

Introduction

Base URL

https://app.realvalidito.com

Content-Type: application/json

Authentication

Phone Number Validation API

Path variables

Responses

Request body

Responses

DNC Scrub API

Path variables

Responses

Request body

Responses

Gender API

Path variables

Responses

Request body

Responses

ZIP Code Lookup API

Path variables

Responses

Request body

Responses

RealValidito Error Codes