Create Account

Sunday 17th November 2019 | Telephone numbers on TPS: 18,186,781 | Telephone numbers on CTPS: 2,071,573 | Total numbers registered: 20,258,354

API documentation - single numbers

A request for a single number check can be carried out over http by means of different query string variables.




API Input

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

Method: GET

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

  • token: This is your unique API login token. This is unique to you
  • number: This is the actual telephone number you want to check.
  • output: This is the output format you require.
  • data__{key}: Any number of optional key/value combinations where the key is prefixed with data__.

These options are discussed in more detail below.




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.

It will look something like the following: a6759ab14f79cbf159r803b4a4x3aa45

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.




Number

This is the phone number that you wish to check. Our system will sanitise it for C/TPS screening. This means it will ignore non-numeric characters and C/TPS-check the number, but will not tell you if it’s a valid phone number.

You do not need to include a leading zero but one will be added by the checker for the purposes of C/TPS screening. Your data will remain unchanged. Phone numbers will generally be 8, 10 or 11 digits

International prefixes e.g. +44 and 0044 will be stripped and a leading zero added if required for the purposes of C/TPS screening. Your data will remain unchanged.




Output

We currently offer three forms of output: JSON, XML and plain text.




JSON [default]

This will produce output as follows:

{"status":"listed"}
xml

This will produce output as follows:

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <status>safe</status>
</result>
text

This will produce output as follows:

safe

Please note: we recommend a 2 second delay between API calls.




data__{key}

Any number of extra fields can be appended. They will be stored within the database. As long as the key is prefixed with data__ it will be stored otherwise it will be ignored.

For example: data__test=123 wil result in a key of “test” being stored with a value of “123”.

Keys can be up to 100 characters. Values can be up to 255 characters.

Please do not include personal data.




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 telephone number required The telephone number has not been found within your request. Please ensure you include a "number" 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 incorrect testing number When running a test you can only use the numbers given. If you try to test another number it will generate an error.
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.



Examples

These are non-working examples to explain the URL structure.

  • https://121prodata.co.uk/api/?token=****token****&number=0123456789
  • https://121prodata.co.uk/api/?token=****token****&number=0123456789&output=text



Testing

You can use the following test information to preview the results you will receive. This is free of charge and doesn’t use any of your credits.

token: test-token

safe number: 01435648777

listed number: 02763875666

Text output & safe number: https://121prodata.co.uk/api/?token=test-token&number=14356487&output=text

JSON output & safe number: https://121prodata.co.uk/api/?token=test-token&number=14356487&output=json

XML output & safe number: https://121prodata.co.uk/api/?token=test-token&number=14356487&output=xml

Text output & listed number: https://121prodata.co.uk/api/?token=test-token&number=27638756&output=text

JSON output & listed number: https://121prodata.co.uk/api/?token=test-token&number=27638756&output=json

XML output & listed number: https://121prodata.co.uk/api/?token=test-token&number=27638756&output=xml

Error: https://121prodata.co.uk/api/?token=test-token&number=76334756&output=json




PHP Code Sample

<?php

/**
 * Example of the 121ProData Single Number API check.
 * text output.
 */

//Test mode: safe number
$url = 'https://121prodata.co.uk/api/?token=test-token&number=14356487&output=text';
//Test mode: listed number
$url = 'https://121prodata.co.uk/api/?token=test-token&number=27638756&output=text';
//Test mode: error
$url = 'https://121prodata.co.uk/api/?token=test-token&number=76334756&output=text';


try {

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

	echo $resultText;

} catch (Exception $e) {

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

}


function checkNumber($url)
{

	//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
			CURLOPT_TIMEOUT_MS => 1000,
			//ensures the hostname matches the certificate
			CURLOPT_SSL_VERIFYHOST => 2,
			/**
			 * 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,
		)
	);

	//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);

}