Provero Logo

TPS/CTPS Check

The TPS (Telephone Preference Service) Validation API checks whether a UK landline or mobile number is listed with either the official TPS or Corporate TPS (CTPS) registers. Use this to avoid calling users who have opted out of unsolicited sales and marketing contact.

Endpoint

POST 
https://api.provero.io/api/validate/phone-tps

Headers

Authorization: Bearer REPLACE_WITH_API_TOKEN
Content-Type: application/json
Accept: application/json

Request Body

Field Type Required Description
phone string Yes Phone number to check (in E.164 format, e.g. +441234567890)
Request Body example (JSON)
{
    "phone": "+441302778473"
}

Code Examples

import requests

userPhone = "REPLACE_WITH_PHONE"

url = "https://api.provero.io/api/validate/phone-tps"
payload = {"phone": userPhone}

headers = {
    "Authorization": "Bearer REPLACE_WITH_API_TOKEN",
    "Content-Type": "application/json",
    "Accept": "application/json"
}

response = requests.post(url, headers=headers, json=payload)
print(response.status_code)
print(response.text)
<?php
$userPhone = "REPLACE_WITH_PHONE";

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.provero.io/api/validate/phone-tps",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS => json_encode(["phone" => $userPhone]),
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer REPLACE_WITH_API_TOKEN",
        "Content-Type: application/json",
        "Accept: application/json"
    ],
]);

$response = curl_exec($curl);
if (curl_errno($curl)) {
    echo 'Error:' . curl_error($curl);
}
curl_close($curl);
echo $response;
const userPhone = "REPLACE_WITH_PHONE";

fetch("https://api.provero.io/api/validate/phone-tps", {
    method: "POST",
    headers: {
        "Authorization": "Bearer REPLACE_WITH_API_TOKEN",
        "Content-Type": "application/json",
        "Accept": "application/json"
    },
    body: JSON.stringify({ phone: userPhone })
})
    .then(response => response.text())
    .then(result => console.log(result))
    .catch(error => console.error("Error:", error));
userPhone="REPLACE_WITH_PHONE"

curl -X POST https://api.provero.io/api/validate/phone-tps \
  -H "Authorization: Bearer REPLACE_WITH_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d "{\"phone\": \"$userPhone\"}"

Response Examples

Success - Not On TPS 
{
    "phone": "tel:+44-1234-567890",
    "onTps": false,
    "registeredDate": ""
}
Success - On TPS 
{
    "phone": "tel:+44-1234-567890",
    "onTps": true,
    "registeredDate": "2024-03-22",
    "tpsExpiry": "2026-08-25"
}
General Error 
{
    "requestError": {
        "serviceException": {
            "messageId": "Error message",
            "code": "400"
        }
    }
}
Payment Required - Insufficient Balance 
{
    "message": "Insufficient balance for validation request.",
    "service": "tps",
    "required_amount": "0.0060000000",
    "current_balance": "0.0000000000"
}
Error - Wrong Region 
{
    "message": "The provided phone number is not valid for the GB region.",
    "errors": {
        "phone": [
            "The provided phone number is not valid for the GB region."
        ]
    }
}
Validation Error - Phone Not Provided 
{
    "message": "The phone field is required.",
    "errors": {
        "phone": [
            "The phone field is required."
        ]
    }
}
Validation Error - Phone Invalid 
{
    "message": "The provided phone number is invalid",
    "errors": {
        "phone": [
            "The provided phone number is invalid"
        ]
    }
}
Validation Error - Phone Too Short 
{
    "message": "The string supplied is too short to be a phone number.",
    "errors": {
        "phone": [
            "The string supplied is too short to be a phone number."
        ]
    }
}

Response Body

Success structure

Field Name Type Example Always Present Description
phone string tel:+44-1234-567890 Yes The submitted phone number in normalized format.
onTps boolean false Yes Whether the number is on the TPS or CTPS register.
registeredDate string 2024-03-22 No Date the number was registered on TPS/CTPS when available.
tpsExpiry string 2026-08-25 No Date 28 days after the TPS check, returned only when the number is on TPS/CTPS.

Error structure

Field Name Type Example Always Present Description
message string The phone field is required. No Top-level error message for validation issues, insufficient balance, or other request errors
errors object {"phone": ["The phone field is required."]} No Details of validation field errors
requestError object {"serviceException": {"messageId": "Error message", "code": "400"}} No Object returned for application-level service errors
service string tps No Service alias returned with a 402 insufficient-balance response
required_amount string 0.0060000000 No Credit amount required to process the validation request
current_balance string 0.0000000000 No Current available balance at the time the request was rejected