A request for a single number check can be carried out over http by means of different query string variables.
Endpoint: https://121prodata.co.uk/api/
Method: GET
Various options need to be submitted by way of GET variables appended to the URL above.
These options are discussed in more detail below.
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.
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.
We currently offer three forms of output: JSON, XML and plain text.
This will produce output as follows:
{"status":"listed"}
This will produce output as follows:
<?xml version="1.0" encoding="UTF-8"?> <result> <status>safe</status> </result>
This will produce output as follows:
safe
Please note: we recommend a 2 second delay between API calls.
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.
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. |
These are non-working examples to explain the URL structure.
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
/**
* 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);
}
