TPS and CTPS API documentation for 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);

}

Interest	Explanation
Maintaining and using our business relationships; understanding and keeping in touch with our clients and suppliers.	We have an interest in maintaining and making use of our relationship with you. For example, if you work for one of our clients we may need to contact you in connection with one of the services that your employer has purchased from us. Or if you work for one of our suppliers we may need to contact you about a service that your employer supplies to us. We also have an interest in understanding what kinds of people use our services and how they use them.
Marketing	We have an interest in promoting our services to our clients and potential clients by email, telephone and post.
Helping people learn about services that might be of use to them	Our clients and potential clients have an interest in learning about services that they might find useful.
Commercial interests	Like any commercial organisation, we seek to earn revenue through the services that we provide to our clients.

API documentation - multiple numbers

API Input

data format

JSON

XML

CSV

API Output

Example Output

output format

JSON

XML

CSV

PHP Code Sample