README

The official PHP SDK for the HLR Lookup API — HLR, MNP, and Number Validation lookups.

Requirements

• PHP 8.1+
• ext-json

Installation

composer require hlrlookup/php-sdk

Quick Start

use HlrLookup\HlrLookup;
use HlrLookup\Config;

$hlr = new HlrLookup(new Config('your-api-key', 'your-api-secret'));

// Single number lookup
$results = $hlr->hlr('+447540822872');

$result = $results[0];
echo $result->liveStatus->value;          // "LIVE"
echo $result->telephoneNumberType->value; // "MOBILE"
echo $result->isLive();                   // true
echo $result->isPorted();                 // true/false

Lookup Types

// HLR Lookup (full live status check) - 1 credit
$results = $hlr->lookups()->hlr('447540822872');

// MNP Lookup (number portability only) - 0.5 credits
$results = $hlr->lookups()->mnp('447540822872');

// Number Validation
$results = $hlr->lookups()->validate('447540822872');

Multiple Numbers

Up to 80 numbers per request:

$results = $hlr->hlr('447540822872', '441133910781', '17148307000');

foreach ($results as $result) {
    echo $result->detectedTelephoneNumber . ': ' . $result->liveStatus->value . "\n";
}

Per-Request Options

use HlrLookup\DTO\LookupRequest;
use HlrLookup\Enum\SaveToCache;

$request = new LookupRequest(
    telephoneNumber: '447540822872',
    cacheDaysPrivate: 30,
    cacheDaysGlobal: 15,
    saveToCache: SaveToCache::YES,
    outputFormat: 'E164',
    inputFormat: 'GBR',         // ISO3 country code for local numbers
    getPortedDate: true,        // +1 credit
    getLandlineStatus: true,    // +1 credit (UK/Ireland only)
    usaStatus: true,            // +1 credit (USA mobile only)
);

$results = $hlr->hlr($request);

Working with Results

$result = $results[0];

// Status
$result->liveStatus;              // LiveStatus enum: LIVE, DEAD, ABSENT_SUBSCRIBER, etc.
$result->telephoneNumberType;     // TelephoneNumberType enum: MOBILE, LANDLINE, VOIP, etc.
$result->isPorted;                // PortedStatus enum: YES, NO, UNKNOWN
$result->disposableNumber;        // DisposableStatus enum: YES, UNKNOWN

// Convenience methods
$result->isLive();                // bool
$result->isDead();                // bool
$result->isPorted();              // bool
$result->isDisposable();          // bool
$result->hasError();              // bool

// Network details
$result->originalNetworkDetails->name;       // "O2 (UK)"
$result->originalNetworkDetails->mccmnc;     // "23410"
$result->originalNetworkDetails->countryIso3; // "GBR"
$result->currentNetworkDetails->name;        // "EE"

// Other fields
$result->creditsSpent;            // float
$result->detectedTelephoneNumber; // "447540822872"
$result->formattedTelephoneNumber;// "+447540822872" (when output_format set)
$result->uuid;                    // unique identifier
$result->timestamp;               // "2022-10-07T13:06:15Z"
$result->portedDate;              // ISO 8601 date or "NOT_AVAILABLE"

Balance Check

$balance = $hlr->lookups()->balance();
echo $balance->credits; // 150.5

Bulk Operations

use HlrLookup\DTO\BatchArguments;

$bulk = $hlr->bulk();

// Create a batch
$batch = $bulk->create('my-numbers.csv');

// Upload numbers
$bulk->uploadNumbers($batch->id, ['447540822872', '441133910781']);

// Or upload a file
$bulk->uploadFile($batch->id, '/path/to/numbers.csv');

// Start processing
$bulk->start($batch->id);

// Check status
$batch = $bulk->get($batch->id);
echo $batch->status->value; // "PROCESSING", "COMPLETE", etc.

// Download results
$csv = $bulk->resultsCsv($batch->id);
$results = $bulk->resultsJson($batch->id); // LookupResult[]

// Schedule for later
$bulk->schedule($batch->id, new \DateTimeImmutable('2024-01-15T10:00:00Z'));

// Pause / delete
$bulk->pause($batch->id);
$bulk->delete($batch->id); // irreversible

Error Handling

use HlrLookup\Exception\AuthenticationException;
use HlrLookup\Exception\BadRequestException;
use HlrLookup\Exception\RateLimitException;
use HlrLookup\Exception\ServerException;
use HlrLookup\Exception\ValidationException;

try {
    $results = $hlr->hlr('447540822872');
} catch (AuthenticationException $e) {
    // 401 - Invalid credentials
} catch (BadRequestException $e) {
    // 400 - Invalid parameters
} catch (RateLimitException $e) {
    // 429 - Too many requests, retry later
} catch (ServerException $e) {
    // 500 - Server error
} catch (ValidationException $e) {
    // Client-side validation (e.g., >80 numbers)
}

Optional Headers

$config = new Config(
    apiKey: 'your-key',
    apiSecret: 'your-secret',
    referenceId: 'my-ref-123',
    accountId: 'my-account',
);

Testing Suite

We provide a free testing suite at testing.hlrlookup.com so you can develop and test your integration without incurring any charges. The testing suite is pre-populated with example responses and is not connected to real telephone networks — no credits are spent.

$hlr = new HlrLookup(Config::testing());
$results = $hlr->hlr('441133910781');

Config::testing() is preconfigured with the testing suite URL and credentials, so you can start integrating immediately without needing an account.

Test Numbers

The following numbers are available in the testing suite and return realistic responses:

For a complete list of test numbers, see the testing documentation.

Running SDK Tests

# Unit tests (mocked HTTP, no network access)
vendor/bin/phpunit --testsuite unit

# Integration tests (hits the free testing suite at testing.hlrlookup.com)
vendor/bin/phpunit --group integration

License

MIT