Create Account

Wednesday 17th July 2019 | Telephone numbers on TPS: 18,866,101 | Telephone numbers on CTPS: 2,165,376 | Total numbers registered: 21,031,477

API documentation - multiple numbers

A request for a bulk number check can be carried out over http by means of different POST variables.




API Input

Endpoint: https://www.121prodata.co.uk/api/

Method: POST

Various options need to be submitted by way of POST variables appended to the URL above.

Parameter Description Accepted Values Example Required Default
token

This is an encrypted token assigned to your account specifically. This is required to validate your request. It is important that you keep this confidential.

Once your account is enabled for API access you will be able to see this information within your account area. You will also have the facility to reset your API token should you need to.

  a6759ab14f79cbf159r803b4a4x3aa45 Yes
data The actual data for processing. This varies in format depending on the input_format you specify. Please see below for more information.   See below. Yes  
input_format We currently offer three forms of input: JSON, XML and plain text (CSV). We recommend JSON as the optimal method for processing. text
json
xml
json No json
test_mode Whether to make this API call in test mode. Test mode will accept real data, exactly as if you were making a real call, but instead of actually checking the data we will randomly append a value to each number of either "listed TEST" or "safe TEST" true or yes
false or no
yes No no
reference Your own internal reference.   2012_03_23__refabc No  
output_format We currently offer three forms of output: JSON, XML and plain text (CSV). We recommend JSON as the optimal method for processing. text
json
xml
json No json


data format

The POST [‘data’] value can be formatted as JSON, XML or CSV. JSON and XML offer the most flexibility while CSV is quite limited. The three methods are summarised below.



JSON

{
"data":[
  {
    "number":"01234567890",
    "specific_reference":"abc123"
  },
  {
    "number":"01234567890"
  },
  {
    "number":"01234567890"
  },
  {
    "number":"01234567890"
  }
]
}

The “data” element must contain an array of JSON objects. Each object must contain a key named “number”. This is the only required key and should contain a telephone number for checking. Any number of optional keys can be included within each object. They will be returned untouched.



XML

<?xml version="1.0" encoding="UTF-8"?>
<data>
  <numbers>
    <number specific_reference="abc123">01234567890</number>
    <number>01234567890</number>
    <number>01234567890</number>
    <number>01234567890</number>
  </numbers>
</data>

The XML must contain a parent element named “data”. This will have a sub-element called “numbers”. Each number will then be sent within a “number” element. Each number element can include any number of attributes. They will be returned untouched.



CSV
01234567890,abc123
01234567890,
01234567890,
01234567890,

The CSV must contain a number in column zero. Any number of columns can be passed and will remain untouched.



API Output

Every response will be accompanied by a header. All header output will be plain text with an HTTP response code.

200: This is a good response and means everything went OK. The output will be in the format you requested.

400: This is an error response. The error detail will be specified in the plain text output. The following is a table of expected error messages.

HTTP Code Message Explanation
400 no API method specified We are unable to detect if you are submitting a bulk or single number API call. This means no POST or GET variables were found.
400 https required You have submitted a request via standard http. All requests must be made over https.
400 token required The token has not been found within your request. Please ensure you include a "token" argument.
400 system in maintenance mode The system is currently synchronising it's TPS/CTPS lists and is out of action until complete. Please try again in approximately 30 minutes.
400 failed to validate token Your token was invalid. It was not found in our system. Please ensure its accuracy.
400 not enough credit You do not have enough credit to run this single number check.
400 input data required Your POST['data'] element was empty
400 invalid input data Your POST['data'] element was incorrectly formatted. This is specific to the type of input you submit (XML, JSON, CSV)


Every JSON and XML response will contain the following default elements. Unfortunately CSV (text) will not contain as much information.

HTTP Code Message Explanation
Parameter Description Example
data The full response data in the format specified by POST['output_format']. Please see below for more information. See below.
reference The internal 121ProData transaction reference. json
matches The number of matches found in this transaction. yes
credits The number of credits used to run this transaction. 2012_03_23__refabc
valid_until The date the results of this check are valid until. In UTC format. 2014-11-05T13:15:30Z


Example Output

output format

The output response can be formatted as JSON, XML or CSV (as specified by POST [‘output_format’]). A number will be classified as safe or listed.

JSON
{
"data":[
  {
    "number":"01234567890",
    "specific_reference":"abc123",
    "result":"listed"
  },
  {
    "number":"01234567890",
    "result":"safe"
  },
  {
    "number":"01234567890",
    "result":"listed"
  },
  {
    "number":"01234567890",
    "result":"safe"
  }
],
"reference":"5598085e745ba",
"matches":2,
"credits":4,
"valid_until":"2014-11-05T13:15:30Z"
}
XML
<?xml version="1.0" encoding="UTF-8"?>
<data>
  <numbers>
    <number specific_reference="abc123" result="safe">01234567890</number>
    <number result="listed">01234567890</number>
    <number result="safe">01234567890</number>
    <number result="listed">01234567890</number>
  </numbers>
  <reference>5598085ebc98b</reference>
  <matches>2</matches>
  <credits>4</credits>
  <valid_until>2014-11-05T13:15:30Z</valid_until>
</data>

The XML will contain all of your original data. On each "number" element an attribute will be added named "result" with a safe or listed value.

CSV
01234567890,abc123,listed
01234567890,,safe
01234567890,,listed
01234567890,,safe

The CSV will contain all of the original columns but the number status will be appended as the last column of each row. The value wil be safe or listed.



PHP Code Sample

<?php

/**
 * Example of the 121ProData Bulk Number API check.
 * JSON input.
 */

$url = 'https://121prodata.co.uk/api/';

//this data will be sent via POST so the 'token' element will become POST['token']
$post_data = array(
	//your API token
	'token' => 'f4324e898f284eb411a02f033468787e',
	//the format of the data you are sending
	'input_format' => 'json',
	//optional - will return in the same format as received
	'output_format' => 'json',
	//test mode can be either true|false
	'test_mode' => true,
	//your optional internal reference to be passed to the check
	'reference' => '',
	//the actual data to eb processed
	'data' => '{
        "data":[
            {"number":"01234567890","specific_reference":"abc123"},
            {"number":"01234567890"},
            {"number":"01234567890"},
            {"number":"01234567890"}
        ]
    }',
);

try {

	list($httpResponse, $resultText) = checkNumber($url, $post_data);

	echo $resultText;

} catch (Exception $e) {

	//catch any exceptions
	die($e->getMessage());

}


function checkNumber($url, $data)
{

	//check curl exists
	if (!function_exists('curl_version')) {
		throw new Exception('curl not installed');
	}

	//connect to URL given
	$ch = curl_init($url);
	if ($ch === FALSE) {
		throw new Exception('Couldnt connect');
	}

	//set multiple cURL options
	curl_setopt_array(
		$ch,
		array(
			//return the response given by the 121 server
			CURLOPT_RETURNTRANSFER => TRUE,
			//amount of time to allow the connection to run for
			//if you're running big checks this may need to be increased
			CURLOPT_TIMEOUT => 60,
			//ensures the hostname matches the certificate
			CURLOPT_SSL_VERIFYHOST => 2,
			//set cURL to use POST method
			CURLOPT_POST => true,
			//the data to be sent via POST
			CURLOPT_POSTFIELDS => $data,
			/**
			 * This code will be more secure if the following is set to TRUE however it can
			 * cause the code to fail.
			 *
			 * You may get an error as follows:
			 *        SSL certificate problem, verify that the CA cert is OK.
			 */
			CURLOPT_SSL_VERIFYPEER => FALSE,
			CURLOPT_SSL_VERIFYHOST => FALSE,
		)
	);

	//execute cURL connection
	$result = curl_exec($ch);

	//cURL failed for some reason
	if ($result === FALSE) {
		throw new Exception('Curl error: ' . curl_error($ch));
	}

	//get the HTTP response code
	$http_status = curl_getinfo($ch, CURLINFO_HTTP_CODE);

	//return the HTTP response and the result for processing
	return array($http_status, $result);

}