This tutorial uses the Twilio Lookup API in PHP to validate phone numbers, determine their line type (mobile, landline, or VoIP), and retrieve carrier information before sending messages or making calls. It targets PHP developers who want to pre-filter recipient lists to avoid spending budget on landlines that cannot receive SMS. You will query the Lookup v2 API with a single phone number, inspect the line type intelligence fields, and make a routing decision based on whether the number is a mobile line.
Prerequisites and Setup
Install the Twilio SDK with composer require twilio/sdk vlucas/phpdotenv and configure your Account SID and Auth Token in a .env file. The Lookup API charges a small per-request fee, so cache results in a database or a cache layer like Redis keyed by phone number with a TTL of several days rather than calling the API on every send. The Lookup v2 endpoint is accessed through $client->lookups->v2->phoneNumbers($number)->fetch() with an options array specifying the fields you want returned. Pass 'fields' => 'line_type_intelligence' to include carrier and line type data in the response; omitting this option returns only basic validity information.
composer require twilio/sdk vlucas/phpdotenv
# .env
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_auth_token_here
The Complete Code
The fetch call returns a result object whose lineTypeIntelligence property is an associative array containing a type key with values like mobile, landline, voip, or nonFixedVoip. The top-level valid boolean indicates whether the number format is correct and the number exists before you inspect the line type. Catching a RestException and returning a safe default array prevents uncaught exceptions from crashing your application when an invalid number is submitted. The helper function returns a plain PHP array with the fields your application needs, keeping the calling code decoupled from the Twilio SDK object structure.
<?php
require_once 'vendor/autoload.php';
use TwilioRestClient;
use TwilioExceptionsRestException;
$dotenv = DotenvDotenv::createImmutable(__DIR__);
$dotenv->load();
$client = new Client($_ENV['TWILIO_ACCOUNT_SID'], $_ENV['TWILIO_AUTH_TOKEN']);
function lookupNumber(Client $client, string $phone): array {
try {
$result = $client->lookups->v2->phoneNumbers($phone)
->fetch(['fields' => 'line_type_intelligence']);
$lti = $result->lineTypeIntelligence ?? [];
return [
'valid' => $result->valid,
'phoneNumber' => $result->phoneNumber,
'countryCode' => $result->countryCode,
'lineType' => $lti['type'] ?? null,
'carrier' => $lti['carrier_name'] ?? null,
];
} catch (RestException $e) {
return ['valid' => false, 'error' => $e->getMessage()];
}
}
$info = lookupNumber($client, '+15551234567');
print_r($info);
if ($info['valid'] && $info['lineType'] === 'mobile') {
echo 'Safe to send SMS to this number.' . PHP_EOL;
} else {
echo 'Skipping: not a mobile line.' . PHP_EOL;
}
Testing and Debugging
Test with a known mobile number, a landline, and a VoIP number such as a Google Voice number to verify the lineType value differs correctly between each category. If lineTypeIntelligence is null in the result, you likely omitted the fields option in the fetch call; add it and retry. A RestException with status 404 means the number format is invalid or the number does not exist; validate E.164 format locally with a regex before calling the API to catch obvious errors cheaply. Monitor your Twilio account usage in the Console to ensure lookup volume stays within your budget, particularly when batch-validating large contact lists.
Taking It Further
Build a pre-send filter function that accepts an array of phone numbers, runs lookups in a loop with a one-second sleep between requests, and returns separate arrays of mobile and non-mobile numbers for different downstream actions. Add CNAM lookup by including caller_name in the fields option string to retrieve the registered caller name for additional context on each number. Cache each lookup result in a Redis hash or a database table keyed by phone number with a 7-day expiry, since carrier assignments change infrequently, to avoid redundant API calls and reduce cost. Combine lookup with the Verify API to build a registration flow that rejects non-mobile numbers with a clear error before sending an OTP.
Contact Telphi Consulting to build smart number validation pipelines in PHP that improve deliverability and reduce wasted messaging spend.
Ready to Transform Your Business Communications?
Get a free consultation with our VoIP experts and discover how we can help you save costs, improve efficiency, and scale your business.
Comments (0)
Join the discussion and share your thoughts (AI-moderated for quality)
Be the first to comment
No comments yet. Share your thoughts below.