Join Our Mailing List
Call: 01451 860805
Sunday 17th February 2019 - Telephone numbers on TPS = 18,930,863, Telephone numbers on CTPS = 2,280,411, Total numbers registered = 21,211,274 Home - FAQ's - Login - Contact
Online TPS Checking
How to use this site -
in 5 easy steps
Pricing calculator
Stay legally compliant
Frequently asked questions
 (New Clients)
 (Existing Clients)
Other Services & Resources
121prodata services
What our clients say
Document download area
Terms & conditions
Privacy & Cookies Policy
Getting in touch
Contact us


TPS Bulk Number API Integration Documentation

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


Integrating the Bulk Number API


API Input



Method: POST

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


Parameter Description Accepted Values Example Required Default

This is an encryped 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 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 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.




{ "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 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 wil be returned untouched.




01234567890,abc123 01234567890, 01234567890, 01234567890,

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




API Output


Every response will be accompanied by a header. All header output will be the correct content type 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 anough 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.


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.




{ "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" }

The "data" will contain all of your original data with an appended "result" key for each number with a value of safe or listed.




<?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.




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



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

$url '';

#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' => '{

try {
$httpResponse$resultText ) = checkNumber$url$post_data );

} catch( 
Exception $e ) {
#catch any exceptions
die( $e->getMessage() );

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
#return the response given by the 121 server
#amount of time to allow the connection to run for
            #if you're running big checks this may need to be increased
#ensures the hostname matches the certificate
#set cURL to use POST method
#the data to be sent via POST
             * 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.

#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$chCURLINFO_HTTP_CODE );
#return the HTTP response and the result for processing
return array( $http_status$result );



Return to API Documentation Home

Copyright © 2004-2019 121prodata Ltd Terms & Conditions - Privacy Policy - Back to Top