TPS/CTPS screening API

The TPS/CTPS screening API checks whether a UK phone number, mobile or landline, is listed with either the official TPS or Corporate TPS (CTPS) registers. The result reports preference-register status; it does not establish comprehensive permission to contact someone.

Endpoint

POST

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

Headers

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

Request Body

Field	Type	Required	Description
`phone`	`string`	Yes	UK phone number (mobile or landline) to check in national format (for example, 01234567890) or international format with or without a leading + (for example, +441234567890 or 441234567890).

Request Payload Example (JSON)

{
    "phone": "+441234567890"
}

Request Examples

Choose language Bash (cURL) 5 examples

userPhone="01234567890"

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\"}"

import requests

userPhone = "01234567890"

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 = "01234567890";

$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 = "01234567890";

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

return $response->json();

const userPhone = "01234567890";

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

Response Examples

Choose response example Success - Not On TPS or CTPS 8 examples

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

{
    "phone": "tel:+44-1234-567890",
    "onTps": true,
    "tpsRegisteredDate": "2024-03-22",
    "onCtps": true,
    "ctpsRegisteredDate": "2023-05-08",
    "prettierPhoneNumber": "01234 567890",
    "tpsExpiry": "2026-08-25"
}

{
    "requestError": {
        "serviceException": {
            "messageId": "Error message",
            "code": 400
        }
    }
}

{
    "message": "Insufficient balance for validation request.",
    "service": "tps",
    "required_amount": "0.0040000000",
    "current_balance": "0.0000000000"
}

{
    "message": "Invalid phone number for GB region",
    "errors": {
        "phone": [
            "Invalid phone number for GB region"
        ]
    }
}

{
    "message": "The phone field is required.",
    "errors": {
        "phone": [
            "The phone field is required."
        ]
    }
}

{
    "message": "The string supplied did not seem to be a phone number.",
    "errors": {
        "phone": [
            "The string supplied did not seem to be a phone number."
        ]
    }
}

{
    "message": "Invalid phone number",
    "errors": {
        "phone": [
            "Invalid phone number"
        ]
    }
}

Response Body

Success structure

Field Name	Type	Always Returned	Description
`phone`	`string`	Yes	The submitted phone number in normalized format.
`onTps`	`boolean`	Yes	Whether the number is on the TPS register.
`tpsRegisteredDate`	`string`	Yes	Date the number was registered on TPS when available; otherwise an empty string.
`onCtps`	`boolean`	Yes	Whether the number is on the Corporate TPS (CTPS) register.
`ctpsRegisteredDate`	`string`	Yes	Date the number was registered on CTPS when available; otherwise an empty string.
`prettierPhoneNumber`	`string`	Yes	The submitted number formatted for display according to UK numbering conventions; otherwise an empty string.
`tpsExpiry`	`string`	No	Date 28 days after the check, returned when the number is on TPS or CTPS.

Error structure

Field Name	Type	Always Returned	Description
`message`	`string`	No	Top-level error message for validation issues, insufficient balance, or other request errors
`errors`	`object`	No	Details of validation field errors
`requestError`	`object`	No	Object returned for application-level service errors
`service`	`string`	No	Service alias returned with a 402 insufficient-balance response
`required_amount`	`string`	No	Credit amount required to process the validation request. The amount can vary by pricing bracket or custom pricing.
`current_balance`	`string`	No	Current available balance at the time the request was rejected