TPS / CTPS API

POST

https://service.tpsapi.com

Introduction

Our JSON API is designed to receive a list of phone numbers in the body of the request, alongside at least one header to indicate which list(s) to screen against. We then return each of those phone numbers back to you, accompanied by whether they are on the list(s).

Request Headers

To make your requests to our API, you will need to attach headers to tell us which list(s) you would like to screen against. At least one list must be provided. You will also need to attach an authorization header, which will allow us to identify you. You also have the option to add headers for additional information, such as the date the numbers were added to their respective lists, or return numbers with formatted spaces. With the exception of the authorization token header, all headers must be provided the value of 'true'.

Header Key	Purpose	Header Value
authorization	The authorization token given to you by us. This is unique to your account and should be not shared with anyone else. In essence, it's a password. We need you to provide it with each request, so we know it's you making the request.	We will provide an authorization token to you.
check-tps	You should include the 'check-tps' header if you would like your numbers to be screened against the tps. The 'check-tps' header can be used in combination with the 'check-ctps' and 'check-fps' headers, to check multiple lists at once.	true
check-ctps	You should include the 'check-ctps' header if you would like your numbers to be screened against the ctps. The 'check-ctps' header can be used in combination with the 'check-tps' and 'check-fps' headers, to check multiple lists at once.	true
check-fps	You should include the 'check-ftps' header if you would like your numbers to be screened against the fps. The 'check-fps' header can be used in combination with the 'check-tps' and 'check-ctps' headers, to check multiple lists at once.	true
return-callable-numbers-only	Only numbers that are confirmed to NOT be on the chosen list(s) will be returned. Please be aware that this means if a number is misformatted and cannot be recognized as a phone number, that number will not be returned, as we cannot confirm or deny its existence on the chosen list(s)	true
return-prettier-numbers	An extra value will be returned in the response JSON with the accompanying key of "prettier_phone_number". The prettier phone number will be formatted correctly with spaces, in accordance with offcom guidelines.	true
return-date-added	This header will return the date each phone number was added to the tps, ctps, and/or fps. If the phone number is not found on the list(s) you are screening, no date will be returned.	true
no-logging	This header will prevent our system from logging your requests phone numbers. CAUTION: This means that in the event you have a query with us, there is a chance we will not be able to help you, because we will not have access to which numbers you screened.	true

Request Body

To make your requests to our API, you will need your request to include a JSON body. Inside the body of the request, you will need to include a "phone_numbers" array. You can screen a maximum of 10,000 phone numbers in one request.

Body Key	Purpose	Body Value
phone_numbers	The array of phone numbers you want to screen.	An array of phone numbers.

Example #1

This is an example of two phone numbers being screened against only the TPS with no additional headers. The post request is made in javascript using a common package called axios. The response is the JSON given in the response from our API.

Example Request #1

const phoneNumbers = ["01256808743", "02920004549"];

const response = await axios.post('https://service.tpsapi.com',
{
    phone_numbers: phoneNumbers
},
{
    headers:
    {
        Authorization: 'YOUR-AUTH-TOKEN-GOES-HERE',
        ['check-tps']: true,
    }
});

Example Response #1

{
    "results": [
        {
            "original_phone_number": "01256808743",
            "screened_phone_number": "01256808743",
            "on_tps": true,
        },
        {
            "original_phone_number": "02920004549",
            "screened_phone_number": "02920004549",
            "on_tps": false,
        },
    ],
    "credits_remaining": 126219
}

Example #2

This is an example of two numbers being screened against both the TPS and the CTPS. In the event a number is on one or both of the lists. The date that the number was added to the list(s) will also be given in the response. A prettier number will also be returned, which includes spaces in accordance with offcom guidelines.

Example Request #2

const phoneNumbers = ["01256808743", "02920004549"];

const response = await axios.post('https://service.tpsapi.com',
{
    phone_numbers: phoneNumbers
},
{
    headers:
    {
        Authorization: 'YOUR-AUTH-TOKEN-GOES-HERE',
        ['check-tps']: true,
        ['check-ctps']: true,
        ['return-prettier-numbers']: true,
        ['return-date-added']: true,
    }
});

Example Response #2

{
    "results": [
        {
            "original_phone_number": "01256808743",
            "screened_phone_number": "01256808743",
            "prettier_phone_number": "01256 808743",
            "on_tps": true,
            "on_ctps": false,
            "date_added_tps": "2024-10-24"
        },
        {
            "original_phone_number": "02920004549",
            "screened_phone_number": "02920004549",
            "prettier_phone_number": "029 2000 4549",
            "on_tps": false,
            "on_ctps": false,
        },
    ],
    "credits_remaining": 126219
}