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
   
Home
Online TPS Checking
How to use this site -
in 5 easy steps
Pricing calculator
Stay legally compliant
Frequently asked questions
Registration
 (New Clients)
Login
 (Existing Clients)
Other Services & Resources
121prodata services
What our clients say
Document download area
Terms & conditions
Privacy & Cookies Policy
Links
Getting in touch
Contact us


   

TPS Single Number API Integration Documentation

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

 

Integrating the Single Number API

 

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 validate.
  • 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 encryped 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 validate. Our system will sanitise it but it will not validate it. This means it will ignore non-numeric characters and TPS-check the number, but will not tell you if it's a valid phone number.

You must include the leading zero. Phone numbers will generally be 8, 10 or 11 digits.

A phone number such as +44 (0) 1982 774 888 should be sent as 01982774888.

 

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.

 

 

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 anough 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$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