> ## 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

> Search, purchase and assign phone numbers via the Zavu PHP SDK. Manage SMS, WhatsApp and Voice numbers across countries with one API.

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, national, tollFree. The API also
                        // takes mobile; this SDK does not type it yet, so use REST for it.
    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>
  Buying numbers requires a paid plan (`402 paid_plan_required` on Free). A paid plan includes one number at no charge, once per account: a US or Canadian number (a +1 number) costing \$20 a month or less; `isFreeEligible` in search results marks the number that qualifies.
</Info>

<Info>
  Some numbers require regulatory information before they can be used; the purchase checks the exact number before charging anything. The SDK does not send `type` or `regulatoryRequirements` yet: for those numbers use the REST flow in [Regulatory Requirements](/guides/phone-numbers/regulatory-requirements), then poll the number's regulatory status until it is `approved`. A sender can be assigned before or after approval.
</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->retrieve('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('pn_abc123', name: 'Marketing Line');

// Assign to a sender
$result = $client->phoneNumbers->update('pn_abc123', senderID: 'snd_xyz789');
```

## Release Phone Number

Release a phone number you no longer need:

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

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

## Get Regulatory Requirements

Check what regulatory information is required for a country and number type. The purchase checks the exact number, which the REST endpoint answers with `?phoneNumber=`; see [Regulatory Requirements](/guides/phone-numbers/regulatory-requirements).

```php theme={null}
$result = $client->phoneNumbers->requirements(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\Core\Exceptions\APIStatusException;

try {
    $client->phoneNumbers->purchase(phoneNumber: '+14155551234');
} catch (APIStatusException $e) {
    if ($e->status === 402) {
        echo "Add funds to your account\n";
    } elseif ($e->status === 400) {
        echo "Invalid request, number unavailable, or regulatory information needed\n";
    }
}
```