API Services - Telephone Status
Look up the status of a phone call or SMS by providing a reference ID. The API will return the status of the call.


URL

http://api.proxstop.com/telephonestatus.format


Formats

json, xml


HTTP Methods

GET, POST


Request Data

Required Variable Example Info
Yes key 098f6bcd4621d373cade4e832627b4f6 Your unique API key
Yes referenceid 97A677DD3E0A42B8EA58D93D05BAC89F Reference ID generated by the ProxStop call or SMS request that references the request. 32-character string.
No code 16322 Verification code that was entered by your end-user. Numeric 3 to 5 digit code; value should be between 100 and 99999.


Example Request

http://api.proxstop.com/telephonestatus.xml?key=098f6bcd4621d373cade4e832627b4f6&referenceid=97A677DD3E0A42B8EA58D93D05BAC89F&code=16322


Response Data

Variable Example Info
status 100 Three-digit code that indicates the status of the call/SMS. Click here for a list of possible statuses.
valid 0 One digit code that indicates whether the code entered by user matches the code generated by the script. 0 indicates correct code was entered. -1 indicates incorrect code was entered.


Good Response Example

<?xml version="1.0" encoding="UTF-8"?>
<response>
	<status>100</status>
	<valid>0</valid>
</response>		
{
	"version": "1.0",
	"encoding": "UTF-8",
	"response": {
		"status": 100
		"valid": 0
	}
}		


Bad Response Example

<?xml version="1.0" encoding="UTF-8"?>
<failed>
	<error_code>INVALID_TELEREFERENCE</error_code>
	<error_msg>The telephone reference ID provided is not valid.</error_msg>
</failed>		
{
	"version": "1.0",
	"encoding": "UTF-8",
	"failed": {
		"error_code": "INVALID_TELEREFERENCE",
		"error_msg": "The telephone reference ID 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
$referenceid = '97A677DD3E0A42B8EA58D93D05BAC89F'; // Reference ID generated by the ProxStop call or SMS request that references the request. 32-character string.
$code = '16322'; // Verification code that was entered by your end-user. Numeric 3 to 5 digit code; value should be between 100 and 99999.
$result = $ProxStop->telephoneStatus($referenceid,$code);

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

// Pin entered good?
else if((string)$result->valid==='0')
{
	echo 'PIN entered correctly.';
}
	
// Pin entered invalid?
else
{
	echo 'PIN entered incorrectly.';
}		
$apiUrl = 'http://api.proxstop.com/telephonestatus.xml';
$apiKey = '098f6bcd4621d373cade4e832627b4f6'; // Replace with your API key
$referenceid = '97A677DD3E0A42B8EA58D93D05BAC89F'; // Reference ID generated by the ProxStop call or SMS request that references the request. 32-character string.
$code = '16322'; // Verification code that was entered by your end-user. Numeric 3 to 5 digit code; value should be between 100 and 99999.

$result = file_get_contents($apiUrl.'?key='.$apiKey.'&referenceid='.$referenceid.'&code='.$code);
$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->status))
{
	echo 'The service seems to be temporarily unavailable.';
}
else if((string)$result->status==='0')
{
	// Do what you need here
	echo 'PIN entered correctly.';
}
else
{
	// Do what you need here
	echo 'PIN entered incorrectly.';
}		
string apiUrl = "http://api.proxstop.com/telephonestatus.xml";
string apiKey = "098f6bcd4621d373cade4e832627b4f6"; // Replace with your API key
string varReferenceid = "97A677DD3E0A42B8EA58D93D05BAC89F"; // Reference ID generated by the ProxStop call or SMS request that references the request. 32-character string.
string varCode = "16322"; // Verification code that was entered by your end-user. Numeric 3 to 5 digit code; value should be between 100 and 99999.

string results = new System.Net.WebClient().DownloadString(apiUrl+"?key="+apiKey+"&referenceid="+varReferenceid+"&code="+varCode);
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/status")==null)
{
	Response.Write("The service seems to be temporarily unavailable.");
}
else if(doc.SelectSingleNode("//response/status/text()").Value==="0")
{
	// Do what you need here
	Response.Write("PIN entered correctly.");
}
else
{
	// Do what you need here
	Response.Write("PIN entered incorrectly.");
}		
require 'net/http'
require 'rexml/document'

apiUrl = 'http://api.proxstop.com/telephonestatus.xml'
apiKey = '098f6bcd4621d373cade4e832627b4f6' #Replace with your API key
referenceid = '97A677DD3E0A42B8EA58D93D05BAC89F' #Reference ID generated by the ProxStop call or SMS request that references the request. 32-character string.
code = '16322' #Verification code that was entered by your end-user. Numeric 3 to 5 digit code; value should be between 100 and 99999.

xml_data = Net::HTTP.get_response(URI.parse(apiUrl+'?key='+apiKey+'&referenceid='+referenceid+'&code='+code)).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/status']
	print 'The service seems to be temporarily unavailable.'

elsif doc.elements['response/status'].text==='0'
	#Do what you need here
	print 'PIN entered correctly.'

else
	#Do what you need here
	print 'PIN entered incorrectly.'

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

apiUrl = 'http://api.proxstop.com/telephonestatus.xml'
apiKey = '098f6bcd4621d373cade4e832627b4f6' #Replace with your API key
referenceid = '97A677DD3E0A42B8EA58D93D05BAC89F' #Reference ID generated by the ProxStop call or SMS request that references the request. 32-character string.
code = '16322' #Verification code that was entered by your end-user. Numeric 3 to 5 digit code; value should be between 100 and 99999.

dom = minidom.parse(urlopen(apiUrl+'?key='+apiKey+'&referenceid='+referenceid+'&code='+code))

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.')

elif (dom.getElementsByTagName('status')[0].firstChild.data==='0'):
	#Do what you need here
	print ('PIN entered correctly.')

else:
	#Do what you need here
	print ('PIN entered incorrectly.')		
const http = require('http');

var apiHost = 'api.proxstop.com';
var apiPath = '/telephonestatus.json';
var apiKey = '098f6bcd4621d373cade4e832627b4f6'; //Replace with your API key
var varReferenceid = '97A677DD3E0A42B8EA58D93D05BAC89F'; //Reference ID generated by the ProxStop call or SMS request that references the request. 32-character string.
var varCode = '16322'; //Verification code that was entered by your end-user. Numeric 3 to 5 digit code; value should be between 100 and 99999.

http.get({host:apiHost,port:80,path:apiPath+'?key='+apiKey+'&referenceid='+varReferenceid+'&code='+varCode,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 if(json.response.status==='0') {
			//Do what you need here
			console.log('PIN entered correctly.');
		} else {
			//Do what you need here
			console.log('PIN entered incorrectly.');
		}
	});
});		
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 = "http://api.proxstop.com/telephonestatus.xml";
		String apiKey = "098f6bcd4621d373cade4e832627b4f6"; //Replace with your API key
		String varReferenceid = "97A677DD3E0A42B8EA58D93D05BAC89F"; //Reference ID generated by the ProxStop call or SMS request that references the request. 32-character string.
		String varCode = "16322"; //Verification code that was entered by your end-user. Numeric 3 to 5 digit code; value should be between 100 and 99999.

		try {
			DocumentBuilderFactory dbFactory = DocumentBuilderFactory.newInstance();
			DocumentBuilder dBuilder = dbFactory.newDocumentBuilder();
			Element docEle = dBuilder.parse(apiUrl+"?key="+apiKey+"&referenceid="+varReferenceid+"&code="+varCode).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 if(docEle.getElementsByTagName("status").item(0).getChildNodes().item(0).getNodeValue()==="0") {
				//Do what you need here
				System.out.println("PIN entered correctly.");
			} else {
				//Do what you need here
				System.out.println("PIN entered incorrectly.");
			}
		} catch (SAXParseException err) {
		} catch (SAXException e) {
		} catch (Throwable t) {
		}
	}
}		


Price

Free