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 Body

Successful screening requests return a results array. The fields in each result depend on the lists and optional response headers selected in your request.

Field	Returned when	Description
results	Always	An array containing one result for each returned phone number.
credits_remaining	Always	Your remaining credit balance after the request.
original_phone_number	Every result	The value exactly as it was supplied in the request.
screened_phone_number	Valid numbers	The normalized phone number used for screening.
on_tps	check-tps: true	Whether the number is registered on the TPS.
on_ctps	check-ctps: true	Whether the number is registered on the CTPS.
prettier_phone_number	return-prettier-numbers: true	A formatted version of a valid phone number.
date_added_tps / date_added_ctps	return-date-added: true	The date the number was added to each selected list. A date field is omitted when the number is not on that list.
error	Invalid phone numbers	A message explaining why that individual number could not be screened.

200 response: TPS and CTPS check

{
  "results": [
    {
      "original_phone_number": "01256 001001",
      "screened_phone_number": "01256001001",
      "prettier_phone_number": "01256 001001",
      "on_tps": false,
      "on_ctps": true
    },
    {
      "original_phone_number": "not-a-number",
      "error": "Not recognized as a valid phone number."
    }
  ],
  "credits_remaining": 998
}

Error response

{
  "error": "Unauthorized, token is invalid."
}

List fields: TPS-only responses include on_tps, CTPS-only responses include on_ctps, and combined checks include both.

Invalid numbers: Individual invalid numbers are returned with an error field while the overall request can still return HTTP 200.

Callable-only responses: With return-callable-numbers-only: true, numbers found on a selected list and invalid numbers are omitted. The results array can therefore be empty.

Response Codes

Response Code	Meaning
200	The request was processed. Results are returned in the JSON response body; individual invalid numbers may still contain an error field.
400	The request is invalid or could not be processed. The JSON error message gives more detail, such as a missing check header or phone_numbers array.
401	Authorization failed because the header is missing, the token is invalid, the account is disabled, or the account has insufficient credits. The JSON error message identifies the reason.
413	The request exceeds the maximum of 10,000 phone numbers or the maximum JSON payload size of 2 MB.
415	The JSON request uses an unsupported character encoding. Send the request as application/json using UTF-8.

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