> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zavu.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Phone Numbers

> Manage phone numbers with the PHP SDK

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:

```php theme={null}
$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

```php theme={null}
$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

```php theme={null}
$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
```

<Info>
  Your first US phone number is free. The `isFreeEligible` field in search results indicates eligible numbers.
</Info>

## List Phone Numbers

```php theme={null}
$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

```php theme={null}
$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:

```php theme={null}
// 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:

```php theme={null}
$client->phoneNumbers->release([
    'phoneNumberId' => 'pn_abc123',
]);
```

<Warning>
  You cannot release a phone number assigned to a sender. Unassign it first.
</Warning>

## Get Regulatory Requirements

Check what documentation is required to purchase phone numbers in a specific country:

```php theme={null}
$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

```php theme={null}
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";
    }
}
```