RealValidito Lookup API Documentation

RealValidito provides a real-time REST API for phone number validation, DNC lookup, carrier detection, and line type identification across US and Canada numbers. Each API call returns a JSON response in under 200ms — covering active status, line type (mobile, landline, VoIP, toll-free), carrier name, porting history, time zone, and Do Not Call registry status. All endpoints use standard HTTP methods with API key authentication. New accounts receive 1,000 free credits — no credit card required.

Use the API to validate numbers at point of entry in signup forms, enrich CRM records in real time, clean bulk contact lists, or build TCPA-compliant outreach workflows. Code examples are available in 7 languages including Python, Node.js, PHP, Ruby, Java, Go, and cURL. For bulk validation without API integration, use the CSV upload tool in the dashboard.

Common use cases

TCPA & DNC compliance — scrub mobile numbers against the national Do Not Call Registry before outbound calls or SMS campaigns
Carrier & line type detection — identify mobile, landline, VoIP, toll-free, and prepaid numbers to route messages correctly and avoid wasted credits
Lead validation — verify that a phone number is real, active, and reachable before it enters your CRM
SMS deliverability — filter out VoIP and landline numbers before bulk sends to improve delivery rates and sender reputation
Fraud prevention — flag disposable VoIP numbers at account sign-up to block synthetic identity fraud

RealValidito covers US and Canada numbers. The same API call returns carrier name, line type, DNC status, TCPA litigator flag, region, and number status.

Getting started is free — your account comes with 1,000 free credits, no credit card required. Create a free account and run your first lookup in under 5 minutes.

Quick start

After signing up, copy your API key and secret from your console, then run:

cURL — Quick Start

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

Response

{
  "status": "success",
  "data": {
    "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"
    }
  }
}

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. Pass your API key and API secret as fields in the JSON request body (POST endpoints) or as path parameters (GET endpoints).

Find your API key and secret in your console.

Security: Never embed your API key or secret directly in client-side code or public repositories. Store them as environment variables (e.g. REALVALIDITO_API_KEY) and read them server-side.

Your API key and secret are tied to your account. You are responsible for all API calls made with your credentials.

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 than 1,000 phone numbers."
  }
}

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*******"
    ],
    "federal_dnc": [
      "989*******",
      "207*******"
    ],
    "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 than 1,000 phone numbers."
  }
}

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*******"
    ],
    "federal_dnc": [
      "989*******",
      "207*******"
    ],
    "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*******"
    ],
    "federal_dnc": [
      "989*******",
      "207*******"
    ],
    "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*******"
    ],
    "federal_dnc": [
      "989*******",
      "207*******"
    ],
    "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*******"
    ],
    "federal_dnc": [
      "989*******",
      "207*******"
    ],
    "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*******"
    ],
    "federal_dnc": [
      "989*******",
      "207*******"
    ],
    "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*******"
    ],
    "federal_dnc": [
      "989*******",
      "207*******"
    ],
    "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*******"
    ],
    "federal_dnc": [
      "989*******",
      "207*******"
    ],
    "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 than 1,000 names."
  }
}

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 than 1,000 ZIP codes."
  }
}

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 service.

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 does not contain any phone numbers.

609

The request must not contain more than 1,000 phone numbers.

610

The request does not contain any names.

611

The request must not contain more than 1,000 names.

612

The request does not contain any ZIP or postal codes.

613

The request must not contain more than 1,000 ZIP or postal codes.

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.

Related Resources

Phone Lookup — validate individual numbers in your browser
DNC Lookup — check a number against the US Do Not Call Registry
Pricing & Credits — see volume pricing and credit packages
TCPA Compliance 2026 Guide — understand TCPA rules before building your integration
Carrier Lookup API Guide — deep-dive on line type and carrier detection

Get 1,000 Free API Credits — No Credit Card Required

RealValidito Lookup API Documentation

Common use cases

Quick start

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

Related Resources