Skip to main content
Phone numbers are required for sending SMS and WhatsApp messages. You can search for available numbers, purchase them, and manage them through the API.

​
Search Available Numbers

Find phone numbers available for purchase: 
$result = $client->phoneNumbers->searchAvailable([
    'countryCode' => 'US',
    'type' => 'local',
    'limit' => 10,
]);

foreach ($result->items as $number) {
    echo $number->phoneNumber . " " . $number->locality . " " . $number->region . "\n";
    echo "Monthly: " . $number->pricing->monthlyPrice . "\n";
    echo "Free eligible: " . ($number->pricing->isFreeEligible ? 'yes' : 'no') . "\n";
}

​
Search Parameters

$result = $client->phoneNumbers->searchAvailable([
    'countryCode' => 'US',      // Required: Two-letter country code
    'type' => 'local',          // Optional: local, mobile, tollFree
    'contains' => '555',        // Optional: Pattern to search for
    'limit' => 20,              // Optional: Max results (default: 10, max: 50)
]);

​
Purchase a Phone Number

$phoneNumber = $client->phoneNumbers->purchase([
    'phoneNumber' => '+14155551234',
    'name' => 'Customer Support',
]);

echo $phoneNumber->phoneNumber->id . "\n";           // pn_abc123
echo $phoneNumber->phoneNumber->phoneNumber . "\n";  // +14155551234
echo $phoneNumber->phoneNumber->status . "\n";       // active
Your first US phone number is free. The isFreeEligible field in search results indicates eligible numbers.

​
List Phone Numbers

$result = $client->phoneNumbers->list([]);

foreach ($result->items as $number) {
    echo $number->id . " " . $number->phoneNumber . " " . $number->name . "\n";
    echo "Status: " . $number->status . "\n";
    echo "Assigned to: " . $number->senderId . "\n";
}

// With filters
$result = $client->phoneNumbers->list([
    'status' => 'active',
    'limit' => 50,
    'cursor' => 'cursor_xxx',
]);

​
Get Phone Number

$result = $client->phoneNumbers->get([
    'phoneNumberId' => 'pn_abc123',
]);

echo $result->phoneNumber->phoneNumber . "\n";
echo $result->phoneNumber->name . "\n";
echo implode(', ', $result->phoneNumber->capabilities) . "\n";
echo $result->phoneNumber->pricing->monthlyPrice . "\n";
echo $result->phoneNumber->nextRenewalDate . "\n";

​
Update Phone Number

Update the name or sender assignment: 
// Update name
$result = $client->phoneNumbers->update([
    'phoneNumberId' => 'pn_abc123',
    'name' => 'Marketing Line',
]);

// Assign to a sender
$result = $client->phoneNumbers->update([
    'phoneNumberId' => 'pn_abc123',
    'senderId' => 'snd_xyz789',
]);

// Unassign from sender
$result = $client->phoneNumbers->update([
    'phoneNumberId' => 'pn_abc123',
    'senderId' => null,
]);

​
Release Phone Number

Release a phone number you no longer need: 
$client->phoneNumbers->release([
    'phoneNumberId' => 'pn_abc123',
]);
You cannot release a phone number assigned to a sender. Unassign it first.

​
Get Regulatory Requirements

Check what documentation is required to purchase phone numbers in a specific country: 
$result = $client->phoneNumbers->getRequirements([
    'countryCode' => 'DE',
    'type' => 'local',
]);

foreach ($result->items as $requirement) {
    echo $requirement->countryCode . " " . $requirement->phoneNumberType . "\n";
    foreach ($requirement->requirementTypes as $reqType) {
        echo "  - " . $reqType->name . ": " . $reqType->description . "\n";
    }
}

​
Error Handling

use Zavudev\APIError;

try {
    $number = $client->phoneNumbers->purchase([
        'phoneNumber' => '+14155551234',
    ]);
} catch (APIError $e) {
    if ($e->status === 402) {
        echo "Add funds to your account\n";
    } elseif ($e->status === 400) {
        echo "Phone number is no longer available\n";
    }
}