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;

$userPhone = "REPLACE_WITH_PHONE";

$response = Http::withToken('REPLACE_WITH_API_TOKEN')
    ->acceptJson()
    ->post('https://api.provero.io/api/validate/phone-tps', [
        'phone' => $userPhone,
    ]);

return $response->json();

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 or CTPS

{
    "phone": "tel:+44-1234-567890",
    "onTps": false,
    "tpsRegisteredDate": "",
    "onCtps": false,
    "ctpsRegisteredDate": ""
}

Success - On TPS and CTPS

{
    "phone": "tel:+44-1234-567890",
    "onTps": true,
    "tpsRegisteredDate": "2024-03-22",
    "onCtps": true,
    "ctpsRegisteredDate": "2023-05-08",
    "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."
        ]
    }
}

Additional response examples 2

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 register.
`tpsRegisteredDate`	`string`	2024-03-22	Yes	Date the number was registered on TPS when available; otherwise an empty string.
`onCtps`	`boolean`	false	Yes	Whether the number is on the Corporate TPS (CTPS) register.
`ctpsRegisteredDate`	`string`	2023-05-08	Yes	Date the number was registered on CTPS when available; otherwise an empty string.
`tpsExpiry`	`string`	2026-08-25	No	Date 28 days after the check, returned when the number is on TPS or 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