API Services - Telephone Lookup
Look up information on a telephone number. The API will return detailed information.


URL

https://api.proxstop.com/telephonelookup.format


Formats

json, xml


HTTP Methods

GET, POST


Request Data

Required Variable Example Info
Yes key 098f6bcd4621d373cade4e832627b4f6 Your unique API key
No country 1 Country code associated with the phone number that is being identified. 1 to 3 digits; do not include 00 or 011 [default: 1]. Click here for a list of country phone codes.
Yes phone 5555555555 Phone number, including area code, to be identified. Numeric only; remove spaces, hyphens, parenthesis, etc.


Example Request

https://api.proxstop.com/telephonelookup.xml?key=098f6bcd4621d373cade4e832627b4f6&country=1&phone=5555555555


Response Data

Variable Example Info
countrycode 1 One to three-digit country code associated with the country of the phone number passed to the PhoneLookup API. Should be the same country code passed to ProxStop's API during the PhoneLookup request.
ophone 5555555555 The original phone number passed to ProxStop's PhoneLookup API. Numeric string.
cphone 5555555555 If the phone number was entered in an incorrect format (i.e. the phone number included 00, 011, or the country code was entered twice), the cleansed phone number is returned in this parameter. Numeric string.
ccode 0 One of the Cleansing Codes describing the cleansing operation performed on the phone number. The default value is 100 (No changes were made to the phone number).
city New York A string specifying the name of the city associated with the phone number.
state NY The 2-letter State Abbreviation Code of the state (province, district, or territory) associated with the phone number (North America only).
zip 10075 The 5-digit United States Postal Service ZIP Code associated with the phone number (U.S. only).
county A string specifying the name of the County (or Parish) associated with the phone number (U.S. only).
country US Two-letter ISO country code associated with phone number.
countryname United States Full country name associated with the phone number.
timezone America/New_York Descriptive time zone associated with phone number.
utcmin -5 In the US, the Universal Time of the phone number entered is returned. Internationally, the minimum Universal time for the country associated with the phone number entered is returned. Number that ranges from -12 to +12.
utcmax -5 In the US, utcmax returns the same information as utcmin. Internationally, the maximum Universal time for the country associated with the phone number entered is returned.
lat 42.59390 Latitude associated with phone number.
lon -82.87835 Longitude associated with phone number.
min 10 Minimum phone number length of telephone numbers with the country code/area code combination of phone number.
max 10 Maximum phone number length of telephone numbers with the country code/area code combination of phone number.
type 302 Code indicating type of phone associated with phone number. Click here for a list of telephone types.
carrier Verizon Wireless A string specifying the name of the carrier.


Good Response Example

<?xml version="1.0" encoding="UTF-8"?>
<response>
	<countrycode>1</countrycode>
	<ophone>5555555555</ophone>
	<cphone>5555555555</cphone>
	<ccode>0</ccode>
	<city>New York</city>
	<state>NY</state>
	<zip>10075</zip>
	<county></county>
	<country>US</country>
	<countryname>United States</countryname>
	<timezone>America/New_York</timezone>
	<utcmin>-5</utcmin>
	<utcmax>-5</utcmax>
	<lat>42.59390</lat>
	<lon>-82.87835</lon>
	<min>10</min>
	<max>10</max>
	<type>302</type>
	<carrier>Verizon Wireless</carrier>
</response>		
{
	"version": "1.0",
	"encoding": "UTF-8",
	"response": {
		"countrycode": 1
		"ophone": 5555555555
		"cphone": 5555555555
		"ccode": 0
		"city": New York
		"state": NY
		"zip": 10075
		"county": 
		"country": US
		"countryname": United States
		"timezone": America/New_York
		"utcmin": -5
		"utcmax": -5
		"lat": 42.59390
		"lon": -82.87835
		"min": 10
		"max": 10
		"type": 302
		"carrier": Verizon Wireless
	}
}		


Bad Response Example

<?xml version="1.0" encoding="UTF-8"?>
<failed>
	<error_code>INVALID_TELEPHONE</error_code>
	<error_msg>The telephone number provided is not valid.</error_msg>
</failed>		
{
	"version": "1.0",
	"encoding": "UTF-8",
	"failed": {
		"error_code": "INVALID_TELEPHONE",
		"error_msg": "The telephone number provided is not valid."
	}
}		


Simple Programming Example

This uses our PHP5 class which can be downloaded by clicking here. The downloadable zip archive will also contain more detailed examples with forms.

// Load config & main class
require_once('config.ProxStop.php');

// Perform Lookup
$country = '1'; // Country code associated with the phone number that is being identified. 1 to 3 digits; do not include 00 or 011 [default: 1].  
$phone = '5555555555'; // Phone number, including area code, to be identified. Numeric only; remove spaces, hyphens, parenthesis, etc.
$result = $ProxStop->telephoneLookup($country,$phone);

// The lookup failed, print the error message.
if($result===false)
{
	echo 'The lookup failed with the error "'.$ProxStop->errors['code'].': '.$ProxStop->errors['msg'].'"';
}

// The lookup was good
else
{
	echo 'Below are some details on the phone number:<br />';
	echo 'City: '.$result->city.'<br />';
	echo 'State: '.$result->state.'<br />';
	echo 'Zip: '.$result->zip;
	// Review the documentation for showing more information
}		
$apiUrl = 'https://api.proxstop.com/telephonelookup.xml';
$apiKey = '098f6bcd4621d373cade4e832627b4f6'; // Replace with your API key
$country = '1'; // Country code associated with the phone number that is being identified. 1 to 3 digits; do not include 00 or 011 [default: 1].  
$phone = '5555555555'; // Phone number, including area code, to be identified. Numeric only; remove spaces, hyphens, parenthesis, etc.

$result = file_get_contents($apiUrl.'?key='.$apiKey.'&country='.$country.'&phone='.$phone);
$result = simplexml_load_string($result);

if(isset($result->error_code))
{
	echo 'The lookup failed with the error "'.$result->error_code.': '.$result->error_msg.'"';
}
else if(!isset($result->countrycode))
{
	echo 'The service seems to be temporarily unavailable.';
}
else
{
	// Do what you need here
}		
string apiUrl = "https://api.proxstop.com/telephonelookup.xml";
string apiKey = "098f6bcd4621d373cade4e832627b4f6"; // Replace with your API key
string varCountry = "1"; // Country code associated with the phone number that is being identified. 1 to 3 digits; do not include 00 or 011 [default: 1].  
string varPhone = "5555555555"; // Phone number, including area code, to be identified. Numeric only; remove spaces, hyphens, parenthesis, etc.

string results = new System.Net.WebClient().DownloadString(apiUrl+"?key="+apiKey+"&country="+varCountry+"&phone="+varPhone);
System.Xml.XmlDocument doc = new System.Xml.XmlDocument();
doc.LoadXml(results);

if(doc.SelectSingleNode("//failed/error_code")!=null)
{
	Response.Write("The lookup failed with the error \""+doc.SelectSingleNode("//failed/error_code/text()").Value+": "+doc.SelectSingleNode("//failed/error_msg/text()").Value+"\"");
}
else if(doc.SelectSingleNode("//response/countrycode")==null)
{
	Response.Write("The service seems to be temporarily unavailable.");
}
else
{
	// Do what you need here
}		
require 'net/http'
require 'rexml/document'

apiUrl = 'https://api.proxstop.com/telephonelookup.xml'
apiKey = '098f6bcd4621d373cade4e832627b4f6' #Replace with your API key
country = '1' #Country code associated with the phone number that is being identified. 1 to 3 digits; do not include 00 or 011 [default: 1].  
phone = '5555555555' #Phone number, including area code, to be identified. Numeric only; remove spaces, hyphens, parenthesis, etc.

xml_data = Net::HTTP.get_response(URI.parse(apiUrl+'?key='+apiKey+'&country='+country+'&phone='+phone)).body
doc = REXML::Document.new(xml_data)

if doc.elements['failed/error_code']
	print 'The lookup failed with the error '+doc.elements['failed/error_code'].text+': '+doc.elements['failed/error_msg'].text

elsif !doc.elements['response/countrycode']
	print 'The service seems to be temporarily unavailable.'

else
	#Do what you need here

end		
from urllib.request import urlopen
from xml.dom import minidom

apiUrl = 'https://api.proxstop.com/telephonelookup.xml'
apiKey = '098f6bcd4621d373cade4e832627b4f6' #Replace with your API key
country = '1' #Country code associated with the phone number that is being identified. 1 to 3 digits; do not include 00 or 011 [default: 1].  
phone = '5555555555' #Phone number, including area code, to be identified. Numeric only; remove spaces, hyphens, parenthesis, etc.

dom = minidom.parse(urlopen(apiUrl+'?key='+apiKey+'&country='+country+'&phone='+phone))

if (dom.getElementsByTagName('error_code')):
	print (dom.getElementsByTagName('error_code')[0].firstChild.data+': '+dom.getElementsByTagName('error_msg')[0].firstChild.data)

elif not (dom.getElementsByTagName('response')):
	print ('The service seems to be temporarily unavailable.')

else:
	#Do what you need here
	print ('Success')		
const http = require('http');

var apiHost = 'api.proxstop.com';
var apiPath = '/telephonelookup.json';
var apiKey = '098f6bcd4621d373cade4e832627b4f6'; //Replace with your API key
var varCountry = '1'; //Country code associated with the phone number that is being identified. 1 to 3 digits; do not include 00 or 011 [default: 1].  
var varPhone = '5555555555'; //Phone number, including area code, to be identified. Numeric only; remove spaces, hyphens, parenthesis, etc.

http.get({host:apiHost,port:80,path:apiPath+'?key='+apiKey+'&country='+varCountry+'&phone='+varPhone,agent:false},function(res){
	res.setEncoding('utf8');
	res.on('data',function(chunk){
		var json = JSON.parse(chunk);
		if(json.failed!=undefined) {
			console.log(json.failed.error_code+': '+json.failed.error_msg);
		} else if(json.response==undefined) {
			console.log('The service seems to be temporarily unavailable.');
		} else {
			//Do what you need here
			console.log('Success');
		}
	});
});		
import javax.xml.parsers.DocumentBuilderFactory;
import javax.xml.parsers.DocumentBuilder;
import org.w3c.dom.Document;
import org.w3c.dom.*;
import org.xml.sax.SAXException;
import org.xml.sax.SAXParseException;
import java.io.File;

public class ProxStop {
	public static void main(String[] args) {

		String apiUrl = "https://api.proxstop.com/telephonelookup.xml";
		String apiKey = "098f6bcd4621d373cade4e832627b4f6"; //Replace with your API key
		String varCountry = "1"; //Country code associated with the phone number that is being identified. 1 to 3 digits; do not include 00 or 011 [default: 1].  
		String varPhone = "5555555555"; //Phone number, including area code, to be identified. Numeric only; remove spaces, hyphens, parenthesis, etc.

		try {
			DocumentBuilderFactory dbFactory = DocumentBuilderFactory.newInstance();
			DocumentBuilder dBuilder = dbFactory.newDocumentBuilder();
			Element docEle = dBuilder.parse(apiUrl+"?key="+apiKey+"&country="+varCountry+"&phone="+varPhone).getDocumentElement();

			if (docEle.getNodeName()=="failed") {
				System.out.println(docEle.getElementsByTagName("error_code").item(0).getChildNodes().item(0).getNodeValue()+": "+docEle.getElementsByTagName("error_msg").item(0).getChildNodes().item(0).getNodeValue());
			} else if (docEle.getNodeName()!="response") {
				System.out.println("The service seems to be temporarily unavailable.");
			} else {
				//Do what you need here
				System.out.println("Success.");
			}
		} catch (SAXParseException err) {
		} catch (SAXException e) {
		} catch (Throwable t) {
		}
	}
}		


Price

Please login to your account and navigate to the API page to view pricing.