API Documentation

1. Introduction

TPSCheck.uk is a robust API that allows businesses to verify and secure their calls by checking if a phone number is registered with the Telephone Preference Service (TPS) or Corporate Telephone Preference Service (CTPS). It provides real-time verification and valuable insights on the validity, location, type, and provider of the phone number.

What are TPS and CTPS?

The Telephone Preference Service (TPS) and Corporate Telephone Preference Service (CTPS) are official UK registries that enable individuals and businesses to opt out of unsolicited sales and marketing calls. By registering their numbers, they indicate a preference against receiving cold calls. Organisations must legally respect these registrations to ensure a disturbance-free communication environment.

API Integration

TPSCheck.uk offers a robust API that ensures seamless integration for businesses of all sizes. The API provides real-time verification of phone numbers against the TPS/CTPS database, along with details on validity, location, type, and provider. Designed for scalability, it can efficiently handle both individual and bulk requests. With a strong emphasis on data security and backed by a dedicated support team, TPSCheck.uk's API offers a reliable, efficient, and secure solution for all your phone number verification needs.

2. Getting Started

Follow these simple steps to start using the TPSCheck.uk API. The entire process takes just a few minutes, and you'll be making your first API calls in no time.

Quick Setup Process

• Create your free account here - No credit card required for your free plan
• Get your API key from your profile page here - This unique key authenticates all your API requests
• Make your first API call using the base URL https://api.tpscheck.uk/ with your API key in the Authorization header
• Test with a single number using the check endpoint to verify everything is working correctly

What You Can Do

Once you have your API key, you'll be able to:

• Check individual phone numbers against TPS/CTPS registries in real-time
• Process bulk uploads of up to 1,000 numbers per request
• Get detailed information about phone number validity, location, and provider
• Monitor your API usage and remaining credits

3. Authentication

The TPSCheck.uk API uses API key authentication to secure all requests. Every API call must include your unique API key to verify your identity and track usage against your account limits.

Using Your API Key

Include your API key in the Authorization header of every request using the Token prefix:

Authorization: Token YOUR_API_KEY

Security Best Practices

• Keep your API key secure - Never expose it in client-side code or public repositories
• Use environment variables - Store your API key in environment variables, not hardcoded in your application
• Regenerate if compromised - Contact support if you suspect your API key has been exposed
• Use HTTPS only - Always make requests over HTTPS to encrypt your API key in transit

Authentication Errors

If authentication fails, you'll receive a 401 Unauthorized response. Common causes include:

• Missing or malformed Authorization header
• Invalid or expired API key
• Account suspended or deactivated

4. Status Endpoint

Check the API health and current version. This endpoint is public and does not require authentication—perfect for monitoring and health checks.

# Check API status (no authentication required)
curl -X GET "https://api.tpscheck.uk/status"

{
  "status": "ok",
  "version": "1.0.0"
}

5. Check Endpoint

The primary endpoint for checking a single phone number against the TPS/CTPS registry:

curl -X POST \
  "https://api.tpscheck.uk/check?version=2" \
  -H "Authorization: Token YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "01829 830730"}'

{
  "phone": "01829 830730"
}

{
  "input": "01829 830730",
  "e164": "+441829830730",
  "valid": true,
  "line": {
    "type": "landline",
    "original_carrier": "BT",
    "location": "Tarporley",
    "country": "England",
    "prefix": "01829"
  },
  "reachability": {
    "status": "unknown",
    "confidence": "medium"
  },
  "tps": false,
  "ctps": false
}

{
  "phone": "01829 830730",
  "valid": true,
  "type": "Landline",
  "location": "Tarporley",
  "provider": "BT",
  "tps": false,
  "ctps": false
}

6. Batch Endpoint

Check multiple phone numbers in a single request (up to 100 numbers):

curl -X POST \
  "https://api.tpscheck.uk/batch?version=2" \
  -H "Authorization: Token YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phones": ["01564 331484", "01953 498974", "07954 844224"]}'

{
  "phones": [
    "01564 331484",
    "01953 498974",
    "07954 844224"
  ]
}

{
  "total": 3,
  "results": [
    {
      "input": "01564 331484",
      "e164": "+441564331484",
      "valid": true,
      "line": { "type": "landline", "original_carrier": "Gamma Telecom Holdings Ltd", "location": "Lapworth", "country": "England", "prefix": "01564" },
      "reachability": { "status": "unknown", "confidence": "medium" },
      "tps": false,
      "ctps": false
    },
    {
      "input": "01953 498974",
      "e164": "+441953498974",
      "valid": true,
      "line": { "type": "landline", "original_carrier": "BT", "location": "Wymondham", "country": "England", "prefix": "01953" },
      "reachability": { "status": "unknown", "confidence": "medium" },
      "tps": true,
      "ctps": false
    },
    {
      "input": "07954 844224",
      "e164": "+447954844224",
      "valid": true,
      "line": { "type": "mobile", "original_carrier": "EE Limited", "location": "Bristol", "country": "England", "prefix": "07954" },
      "reachability": { "status": "unknown", "confidence": "medium" },
      "tps": false,
      "ctps": false
    }
  ]
}

{
  "results": [
    {
      "phone": "01564 331484",
      "valid": true,
      "type": "Landline",
      "location": "Lapworth",
      "provider": "Gamma Telecom Holdings Ltd",
      "tps": false,
      "ctps": false
    },
    {
      "phone": "01953 498974",
      "valid": true,
      "type": "Landline",
      "location": "Wymondham",
      "provider": "BT",
      "tps": true,
      "ctps": false
    },
    {
      "phone": "07954 844224",
      "valid": true,
      "type": "Mobile",
      "location": "Bristol",
      "provider": "EE Limited",
      "tps": false,
      "ctps": false
    }
  ]
}

7. Credits Endpoint

Check your API usage and remaining requests for the current billing period:

# Check your remaining credits
curl -X GET \
  "https://api.tpscheck.uk/credits" \
  -H "Authorization: Token YOUR_API_KEY"

{
  "requests_used": 245,
  "requests_remaining": 9755,
  "monthly_limit": 10000,
  "plan": "Starter",
  "reset_date": "2025-07-01T00:00:00Z"
}

8. Response Codes

The API uses standard HTTP response codes to indicate the success or failure of requests.

9. Rate Limits

The API has the following rate limits based on your plan:

10. Data Freshness & Update Frequency

Data freshness refers to how often our TPS/CTPS database is refreshed with the latest registration data from official sources. This directly impacts the accuracy and compliance of your phone number checks.

Why Data Freshness Matters

The TPS and CTPS registers are dynamic - phone numbers are constantly being added or removed. Using outdated data can lead to:

• Compliance violations - Calling numbers that were recently registered on TPS/CTPS
• Missed opportunities - Skipping numbers that were recently removed from the registers
• Regulatory fines - ICO guidance recommends screening at least every 28 days before calling

Update Frequency by Plan

Different plans offer different data update frequencies to match your compliance needs:

The 28-Day Screening Interval

ICO guidance recommends screening at least every 28 days before making marketing calls. Organisations should check phone numbers against the TPS register within this interval.

How We Keep Data Fresh

Our database synchronization process works differently depending on your plan:

• Monthly/Weekly Updates - Our system performs scheduled bulk synchronizations with the official TPS/CTPS registers
• Daily Updates - Database is refreshed every 24 hours with the latest registration changes
• Real-time Updates (Enterprise only) - Direct integration with official sources provides instant access to the most current data

Best Practices

To maintain optimal compliance:

• Choose the right plan - Match your update frequency to your calling cadence
• Re-check regularly - Don't rely on checks older than 28 days
• Enable automation - Use 28-Day Re-check Automation to eliminate manual tracking
• Maintain audit logs - Keep timestamped evidence of all checks for regulatory compliance

Data Use and Access Act 2025 — Key Changes

The Data Use and Access Act 2025 (Royal Assent June 2025) introduced significant changes to UK direct marketing regulation. Organisations relying on TPS/CTPS checking should be aware of the following:

11. Code Examples

Ready-to-use code examples in multiple programming languages. Examples request the v2 response format. Omit ?version=2 to use the default v1 response format.

curl --request POST \
  --url https://api.tpscheck.uk/check?version=2 \
  --header 'Authorization: Token YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "phone": "01829 830730"
}'

<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tpscheck.uk/check?version=2",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"phone\":\"01829 830730\"}",
  CURLOPT_HTTPHEADER => [
    "Authorization: Token YOUR_API_KEY",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
?>

import requests
import json

url = "https://api.tpscheck.uk/check?version=2"

payload = json.dumps({
  "phone": "01829 830730"
})
headers = {
  'Authorization': 'Token YOUR_API_KEY',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    Authorization: 'Token YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    phone: '01829 830730'
  })
};

fetch('https://api.tpscheck.uk/check?version=2', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

12. TPS & CTPS Checking

TPS & CTPS Checking verifies phone numbers against the UK's official do-not-call registers, ensuring compliance with UK Privacy and Electronic Communications Regulations (PECR).

What are TPS and CTPS?

• TPS (Telephone Preference Service) - The consumer register where individuals opt out of unsolicited marketing calls
• CTPS (Corporate Telephone Preference Service) - The business register where organisations opt out of unsolicited sales and marketing calls

How It Works

1. Submit a phone number - Provide the UK phone number you wish to verify
2. Instant register check - The system queries the official TPS and CTPS databases
3. Receive registration status - Get a clear result showing whether the number is registered on TPS, CTPS, both, or neither
4. Access additional intelligence - Each check also returns line type, carrier, and geographic location

13. Phone Intelligence

Phone Intelligence provides additional information about every phone number you check, delivered automatically alongside your TPS and CTPS results at no extra cost.

Data Returned

Use Cases

• Segment Contact Lists - Separate mobile and landline contacts for tailored communication strategies
• Validate Lead Lists - Assess data quality before investing time in new lead sources
• Geographic Targeting - Filter landline contacts by area for regional campaigns
• Fraud Detection - Identify VoIP and personal numbering ranges that may indicate risk
• Data Cleansing - Remove premium rate and invalid numbers from databases

14. Bulk Checking

Bulk Checking allows you to validate multiple phone numbers against the TPS and CTPS registers in a single request, rather than checking them one at a time. Available on Starter, Pro, Business, and Enterprise plans.

How It Works

1. Prepare your numbers - Gather up to 100 phone numbers per request
2. Submit your batch - Send all numbers in a single API call
3. Receive complete results - Get TPS/CTPS status for every number in your batch
4. For larger datasets - Batches over 100 numbers are processed asynchronously

Batch Limits by Plan

Common Use Cases

• CRM Database Cleansing - Validate entire customer databases before campaigns
• Lead List Validation - Verify purchased lists immediately to avoid compliance risks
• Regular Data Hygiene - Re-check contact lists at least every 28 days in line with ICO guidance
• Pre-Campaign Checks - Final compliance validation before dialling begins

See the Batch Endpoint section for technical implementation details.

15. 28-Day Re-check Automation

28-Day Re-check Automation continuously monitors your phone number lists and automatically re-checks them against TPS/CTPS registers before the recommended compliance window expires. Available on Growth, Business, and Enterprise plans.

Why It Matters

ICO guidance recommends screening at least every 28 days before making marketing calls. Manual tracking is error-prone and impractical for large contact lists.

How It Works

1. Register Your Numbers - Add numbers to monitor via dashboard or bulk upload
2. Automatic Tracking - System records last check date and calculates compliance deadline
3. Proactive Re-checking - Numbers automatically re-checked on Day 25 (3-day safety buffer)
4. Status Change Alerts - Immediate notifications if TPS status changes
5. Compliance Dashboard - View all monitored numbers and their check status

Key Benefits

16. Audit Logs & Compliance Reports

Audit Logs maintain a complete, tamper-evident record of every TPS check your organisation performs. Available on Pro, Business, and Enterprise plans.

Why It Matters

If the Information Commissioner's Office (ICO) investigates your organisation for PECR violations, saying "we checked TPS" is not sufficient. The ICO requires timestamped evidence demonstrating proper verification.

What Gets Logged

Export Formats

• CSV - For data analysis and bulk record keeping
• PDF - For formal regulatory submissions and client reporting

Retention Period

Audit logs are retained for 12 to 24 months (configurable), exceeding the 28-day screening interval (ICO guidance) and ensuring evidence for the full period regulators may investigate.

Use Cases

• ICO Audit Response - Export complete reports showing systematic compliance
• Internal Reviews - Quarterly compliance audits and process verification
• Client Reporting - Provide formal compliance reports to clients
• Dispute Resolution - Retrieve timestamped evidence to resolve consumer complaints

17. Webhook Notifications

Webhook Notifications automatically send real-time alerts to your systems when important events occur. Available on Pro, Business, and Enterprise plans.

Events That Trigger Notifications

How It Works

1. Configure - Add your webhook URL in the TPSCheck dashboard
2. Select - Choose which events you want to receive
3. Receive - TPSCheck sends notifications when events occur
4. Act - Your system processes notifications and takes action

Key Benefits

• Real-time Integration - Connect with existing business systems
• Automation-Ready - Hands-off compliance management
• No Polling Required - Eliminates constant status checking
• Reliable Delivery - Built for business-critical workflows

Use Cases

• CRM Updates - Automatically update contact records when TPS status changes
• Batch Completion Alerts - Notify teams when large processing jobs finish
• Credit Management - Trigger automatic top-ups when balance is low
• Team Notifications - Integrate with Slack, Teams, or internal dashboards

18. Compliance Risk Scoring

Compliance Risk Scoring provides an overall risk score from 0 to 100 for each phone number you check. Available on Business and Enterprise plans only. The risk field is returned only when you use ?version=2 on check or batch requests; v1 responses do not include risk.

Why It Matters

TPS status alone does not tell the full compliance story. A number may not be on TPS, but could be invalid, flagged for spam, or your check might be outdated beyond the 28-day interval recommended by ICO guidance.

Risk Factors Considered

Risk Levels

Not legal or compliance advice. You are responsible for your own compliance with applicable laws.

Use Cases

• Prioritise Calling Lists - Sort by risk score to work through safest numbers first
• Flag High-Risk Numbers - Route numbers above threshold to manual review
• Demonstrate Due Diligence - Show ICO you went beyond basic TPS checking

19. White-Label Options

White-Label Options allow agencies and resellers to offer TPS checking services under their own brand. Available on Enterprise plans only.

White-Label Capabilities

• Custom API Domain - Host API on your domain (e.g., api.yourbrand.com)
• Branded API Responses - All responses stripped of TPSCheck branding
• Custom Documentation Portal - API docs styled with your brand
• Reseller Dashboard - Manage sub-accounts and monitor client usage
• Branded Reports - Exports carry your logo and branding

Use Cases

• Marketing Agencies - Offer TPS checking as part of campaign management
• CRM Vendors - Integrate compliance directly into your platform
• Compliance Consultancies - Bundle TPS checking with advisory services
• Data Providers - Expand data enrichment to include TPS status

Business Model Options

Contact our Enterprise team to discuss white-label partnership options.

20. 99.9% Uptime SLA

Our Service Level Agreement (SLA) provides a contractual guarantee of service availability with financial compensation if we fail to meet our commitment. Available on Business and Enterprise plans.

Our Commitment

We guarantee 99.9% uptime for the TPSCheck API, which means:

• Maximum of 43.8 minutes unplanned downtime per month
• Availability measured on API endpoint responsiveness
• Scheduled maintenance (announced in advance) excluded from calculations

Service Credits

If we fall short, you automatically qualify for service credits:

Service Monitoring

Track our service status in real-time at status.tpscheck.uk

• Current system health
• Historical uptime data
• Scheduled maintenance announcements
• Incident reports and resolution updates

21. Support & Assistance

When compliance is on the line, you need fast answers. Priority Support ensures paying customers receive faster response times and dedicated support channels.

Support Tiers

What's Included

• Technical Integration Assistance - Help connecting your systems to TPSCheck
• Troubleshooting - Resolve API errors and unexpected behaviour
• Best Practices Guidance - Advice on compliance and workflow optimization
• Account & Billing Support - Questions about subscriptions and usage

Business Hours

Support is available during UK business hours: Monday to Friday, 9:00 AM - 5:30 PM GMT/BST

Enterprise customers can discuss extended support hours as part of their service agreement.

Enterprise Extras

Enterprise customers receive a dedicated support team and named account manager who understands your business and provides proactive compliance guidance.

22. Getting Started & Onboarding

This section covers everything you need to successfully integrate TPSCheck into your systems and workflows.

Quick Start Checklist

1. Create Account - Sign up for a free account (no credit card required)
2. Get API Key - Retrieve your API key from your profile page
3. Test Integration - Make your first API call using the examples above
4. Verify Results - Confirm you're receiving expected data
5. Choose Plan - Upgrade based on your volume needs

Integration Support

Need help integrating TPSCheck with your specific systems? We provide guidance for:

• CRM Systems - Salesforce, HubSpot, Microsoft Dynamics, Zoho
• Marketing Platforms - Mailchimp, ActiveCampaign, Marketo
• Call Centre Software - Five9, Genesys, Twilio, Aircall
• Custom Applications - Direct API integration support

API Integration Resources

• Code Examples - See the Code Examples section for Python, PHP, JavaScript, and cURL
• Webhook Setup - See Webhook Notifications for real-time integration
• Bulk Processing - See Bulk Checking for handling large datasets
• Support Contact - Email support@tpscheck.uk for technical assistance

API Overview

The TPSCheck API is a RESTful service that accepts JSON payloads and returns JSON responses. All endpoints require authentication via API key in the Authorization header.

Key features include:

• RESTful Design - Standard HTTP methods and status codes
• JSON Format - Easy to parse and integrate with modern systems
• API Key Authentication - Simple, secure token-based auth
• Rate Limiting - Fair usage policies per plan tier
• Comprehensive Responses - TPS status plus phone intelligence data

23. Single Sign-On (SSO)

Single Sign-On (SSO) enables Enterprise customers to authenticate their users through their existing identity provider, streamlining access management and enhancing security. Available on Enterprise plans only.

Supported Protocols

• SAML 2.0 - Industry-standard enterprise authentication
• OAuth 2.0 - Modern authorization framework
• OpenID Connect - Identity layer on top of OAuth 2.0

Compatible Identity Providers

• Microsoft Azure Active Directory
• Okta
• Google Workspace
• OneLogin
• Auth0
• Custom SAML 2.0 providers

Benefits

• Centralized Access Control - Manage user access from your existing identity platform
• Enhanced Security - Enforce your organization's authentication policies
• Simplified User Experience - Users log in with familiar corporate credentials
• Automated Provisioning - Automatically create/disable user accounts based on your directory

Contact our Enterprise team at enterprise@tpscheck.uk to configure SSO for your organization.