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 
{
    "phone": "tel:+44-1234-567890",
    "result": false
}
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
result.status string TPS Yes `TPS`, `CTPS`, or `UNLISTED` depending on registry status
result.type string mobile Yes The type of number detected (e.g. `mobile`, `landline`)
result.operator string Vodafone No Detected carrier/operator for the number
result.date string 2024-03-22 No Date the number was registered on TPS/CTPS (if applicable)

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