Getting Started

We've written some documentation to help you get started with our api.
Don't be afraid to reach out and ask for help! Call us on 0343 005 9302 or ask us on live chat if you're confused.

Our API is nice and simple to use (by our estimation 😅). It is a single route, and you use your request headers to determine which list or lists you would like to screen against. We require your authorization token to be placed into the 'Authorization' header. You do not need to prefix the authorization token with the word bearer or token. The Authorization header should only contain your token.

POST

https://service.tpsapi.com

You MUST include your authorization token in the 'Authorization' header. You can find your authorization token on your account screen when you are logged in. In addition to the authorization header, we require at least one additional header in your request before we will accept it. You must choose at least one list to screen against. The header to screen against the TPS is 'check-tps' and the header to screen against the CTPS is 'check-ctps'. You can use both headers at the same time, which will screen your data against both lists!

Request Headers

Header Key	Purpose	Header Value
content-type	Tells the API your request and response will be using the JSON format.	application/json
authorization	The authorization token given to you by us. This is unique to your account and should not be shared with anyone else.	Found on your account page.
check-tps	Include this header if you want to screen numbers against the TPS list. Can be used with 'check-ctps'.	true
check-ctps	Include this header if you want to screen numbers against the CTPS list. Can be used with 'check-tps'.	true
return-callable-numbers-only	Only numbers that are NOT on the selected list(s) will be returned. If a number is misformatted, it won't be returned.	true
return-prettier-numbers	Returns an additional 'prettier_phone_number' field in the response JSON, formatted according to Offcom guidelines.	true
return-date-added	Returns the date each phone number was added to the TPS, CTPS, or FPS. If not found, no date is returned.	true
no-logging	Prevents storing full numbers in logs; only the first 6 digits will be saved (e.g., 0123456XXXX). Limits support capabilities.	true

Request Body

Your request MUST include a JSON request body. The body needs to include an array with the key "phone_numbers".

Body Key	Purpose	Body Value
phone_numbers	The array of phone numbers that you would like to screen against your chosen list(s).	application/json

Response Codes

Response Code	Meaning
200	Success, you should have your results in the JSON body of the response!
400	The request is missing a header, the response message should give more details on the specifics of which header you are missing.
401	The request is either missing the authorization header, the authorization token in the header is incorrect, or your account does not have sufficient tokens to make this request. The response message will specify which of these errors is the problem.
403	Your account has been disabled.
413	The request contains too many phone numbers. There is a maximum limit of 10,000 numbers per request. This request has exceeded that 10,000 limit.

Axios Example


    const phoneNumbers = ["01256001001", "01256001002"];
    
    const response = await axios.post('https://service.tpsapi.com', 
    {
        phone_numbers: phoneNumbers
    },
    {
        headers: {
            Authorization: 'authorization-code-here', 
            ['check-tps']: true,
            ['check-ctps']: true,
            ['return-prettier-numbers']: true,
        }
    });

Python Example


    import http.client
    conn = http.client.HTTPConnection("https://service.tpsapi.com")
    payload = "{
	"phone_numbers": 
	[ 
		"01256001001",
		"01256001002"
	]
}"
    
    headers = {
        'Content-Type': "application/json",
        'check-tps': "true",
        'check-ctps': "true",
        'return-prettier-numbers': "true",
        'authorization': "authorization-code-here"
    }
    
    conn.request("POST", "/", payload, headers)
    
    res = conn.getresponse()
    data = res.read()
    print(data.decode("utf-8"))

PHP Example


    $client = new httpClient;
    $request = new httpClientRequest;
    $body = new httpMessageBody;
    $body->append('{
        "phone_numbers": 
        [ 
            "01256001001",
            "01256001002"
         ]
    }');
    
    $request->setRequestUrl('https://service.tpsapi.com');
    $request->setRequestMethod('POST');
    $request->setBody($body);
    
    $request->setHeaders([
      'Content-Type' => 'application/json',
      'check-tps' => 'true',
      'check-ctps' => 'true',
      'return-prettier-numbers' => 'true',
      'authorization' => 'authorization-code-here'
    ]);
    
    $client->enqueue($request)->send();
    $response = $client->getResponse();
    
    echo $response->getBody();

Axios Example


    const phoneNumbers = ["01256001001", "01256001002"];
    
    const response = await axios.post('https://service.tpsapi.com', 
    {
        phone_numbers: phoneNumbers
    },
    {
        headers: {
            Authorization: 'authorization-code-here', 
            ['check-tps']: true,
            ['check-ctps']: true,
            ['return-prettier-numbers']: true,
        }
    });

Python Example


    import http.client
    conn = http.client.HTTPConnection("https://service.tpsapi.com")
    payload = "{
	"phone_numbers": 
	[ 
		"01256001001",
		"01256001002"
	]
}"
    
    headers = {
        'Content-Type': "application/json",
        'check-tps': "true",
        'check-ctps': "true",
        'return-prettier-numbers': "true",
        'authorization': "authorization-code-here"
    }
    
    conn.request("POST", "/", payload, headers)
    
    res = conn.getresponse()
    data = res.read()
    print(data.decode("utf-8"))

PHP Example


    $client = new httpClient;
    $request = new httpClientRequest;
    $body = new httpMessageBody;
    $body->append('{
        "phone_numbers": 
        [ 
            "01256001001",
            "01256001002"
         ]
    }');
    
    $request->setRequestUrl('https://service.tpsapi.com');
    $request->setRequestMethod('POST');
    $request->setBody($body);
    
    $request->setHeaders([
      'Content-Type' => 'application/json',
      'check-tps' => 'true',
      'check-ctps' => 'true',
      'return-prettier-numbers' => 'true',
      'authorization' => 'authorization-code-here'
    ]);
    
    $client->enqueue($request)->send();
    $response = $client->getResponse();
    
    echo $response->getBody();