> ## 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.
# Purchasing Phone Numbers
> Search for and purchase phone numbers to send messages
Phone numbers are required to send SMS and WhatsApp messages. Zavu lets you search for available numbers and purchase them directly through the API or dashboard.
## Free US Phone Number
Every new team gets their **first US phone number free**. This is a great way to get started with messaging without any upfront cost.
The free phone number offer applies to the first US phone number purchased by a team. Monthly fees still apply after the first month.
## Searching for Available Numbers
Before purchasing, search for available numbers in your target country:
```typescript TypeScript theme={null}
const result = await zavu.phoneNumbers.searchAvailable({
countryCode: "US",
type: "local",
limit: 10,
});
for (const number of result.items) {
console.log(number.phoneNumber, number.locality, number.region);
console.log("Monthly price:", number.pricing.monthlyPrice);
console.log("Free eligible:", number.pricing.isFreeEligible);
}
```
```python Python theme={null}
result = zavu.phone_numbers.search_available(
country_code="US",
type="local",
limit=10
)
for number in result.items:
print(number.phone_number, number.locality, number.region)
print("Monthly price:", number.pricing.monthly_price)
print("Free eligible:", number.pricing.is_free_eligible)
```
```ruby Ruby theme={null}
result = client.phone_numbers.search_available(
country_code: "US",
type: "local",
limit: 10
)
result.items.each do |number|
puts "#{number.phone_number} #{number.locality} #{number.region}"
puts "Monthly price: #{number.pricing.monthly_price}"
puts "Free eligible: #{number.pricing.is_free_eligible}"
end
```
```go Go theme={null}
result, _ := client.PhoneNumbers.SearchAvailable(context.TODO(), zavudev.PhoneNumberSearchAvailableParams{
CountryCode: zavudev.String("US"),
Type: zavudev.String("local"),
Limit: zavudev.Int(10),
})
for _, number := range result.Items {
fmt.Println(number.PhoneNumber, number.Locality, number.Region)
fmt.Println("Monthly price:", number.Pricing.MonthlyPrice)
fmt.Println("Free eligible:", number.Pricing.IsFreeEligible)
}
```
```php 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 price: {$number->pricing->monthlyPrice}\n";
echo "Free eligible: {$number->pricing->isFreeEligible}\n";
}
```
```bash cURL theme={null}
curl "https://api.zavu.dev/v1/phone-numbers/available?countryCode=US&type=local&limit=10" \
-H "Authorization: Bearer $ZAVU_API_KEY"
```
### Search Parameters
| Parameter | Type | Required | Description |
| ------------- | ------- | -------- | ---------------------------------------------------------------- |
| `countryCode` | string | Yes | Two-letter ISO country code (e.g., "US", "GB") |
| `type` | string | No | Number type: `local`, `mobile`, or `tollFree` (default: `local`) |
| `contains` | string | No | Search for numbers containing this pattern (e.g., "555") |
| `limit` | integer | No | Max results to return (default: 10, max: 50) |
### Response
```json theme={null}
{
"items": [
{
"phoneNumber": "+14155551234",
"friendlyName": "(415) 555-1234",
"locality": "San Francisco",
"region": "CA",
"capabilities": {
"sms": true,
"voice": true,
"mms": true
},
"pricing": {
"monthlyPrice": 1.25,
"upfrontPrice": 1.00,
"isFreeEligible": true
}
}
]
}
```
## Regulatory Requirements
Some countries require additional documentation before phone numbers can be activated. Check the [Regulatory Requirements](/guides/phone-numbers/regulatory-requirements) guide for details on:
* Which countries require documentation
* How to create and verify addresses
* How to upload identity documents
* Including requirements in your purchase request
US and Canada phone numbers typically don't require additional documentation.
## Purchasing a Phone Number
Once you've found a number you want, purchase it:
```typescript TypeScript theme={null}
const phoneNumber = await zavu.phoneNumbers.purchase({
phoneNumber: "+14155551234",
name: "Customer Support",
});
console.log("Purchased:", phoneNumber.phoneNumber);
console.log("ID:", phoneNumber.id);
```
```python Python theme={null}
phone_number = zavu.phone_numbers.purchase(
phone_number="+14155551234",
name="Customer Support"
)
print("Purchased:", phone_number.phone_number)
print("ID:", phone_number.id)
```
```ruby Ruby theme={null}
phone_number = client.phone_numbers.purchase(
phone_number: "+14155551234",
name: "Customer Support"
)
puts "Purchased: #{phone_number.phone_number}"
puts "ID: #{phone_number.id}"
```
```go Go theme={null}
phoneNumber, _ := client.PhoneNumbers.Purchase(context.TODO(), zavudev.PhoneNumberPurchaseParams{
PhoneNumber: zavudev.String("+14155551234"),
Name: zavudev.String("Customer Support"),
})
fmt.Println("Purchased:", phoneNumber.PhoneNumber)
fmt.Println("ID:", phoneNumber.ID)
```
```php PHP theme={null}
$phoneNumber = $client->phoneNumbers->purchase([
'phoneNumber' => '+14155551234',
'name' => 'Customer Support',
]);
echo "Purchased: {$phoneNumber->phoneNumber}\n";
echo "ID: {$phoneNumber->id}\n";
```
```bash cURL theme={null}
curl -X POST https://api.zavu.dev/v1/phone-numbers \
-H "Authorization: Bearer $ZAVU_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phoneNumber": "+14155551234",
"name": "Customer Support"
}'
```
### Purchase Parameters
| Parameter | Type | Required | Description |
| ------------- | ------ | -------- | ----------------------------------------------------- |
| `phoneNumber` | string | Yes | Phone number in E.164 format |
| `name` | string | No | Custom name for the phone number (max 100 characters) |
### Response
```json theme={null}
{
"phoneNumber": {
"id": "pn_abc123",
"phoneNumber": "+14155551234",
"name": "Customer Support",
"capabilities": ["sms", "voice"],
"status": "active",
"pricing": {
"monthlyPrice": 1.25,
"upfrontCost": 100,
"monthlyCost": 125,
"isFreeNumber": true
},
"nextRenewalDate": "2025-02-15T00:00:00.000Z",
"createdAt": "2025-01-15T10:30:00.000Z"
}
}
```
Purchasing a phone number deducts the upfront cost from your account balance. Ensure you have sufficient funds before purchasing.
## Listing Your Phone Numbers
View all phone numbers owned by your project:
```typescript TypeScript theme={null}
const result = await zavu.phoneNumbers.list();
for (const number of result.items) {
console.log(number.id, number.phoneNumber, number.name);
console.log("Status:", number.status);
}
// Filter by status
const activeNumbers = await zavu.phoneNumbers.list({
status: "active",
});
```
```python Python theme={null}
result = zavu.phone_numbers.list()
for number in result.items:
print(number.id, number.phone_number, number.name)
print("Status:", number.status)
# Filter by status
active_numbers = zavu.phone_numbers.list(status="active")
```
```ruby Ruby theme={null}
result = client.phone_numbers.list
result.items.each do |number|
puts "#{number.id} #{number.phone_number} #{number.name}"
puts "Status: #{number.status}"
end
# Filter by status
active_numbers = client.phone_numbers.list(status: "active")
```
```go Go theme={null}
result, _ := client.PhoneNumbers.List(context.TODO(), zavudev.PhoneNumberListParams{})
for _, number := range result.Items {
fmt.Println(number.ID, number.PhoneNumber, number.Name)
fmt.Println("Status:", number.Status)
}
// Filter by status
activeNumbers, _ := client.PhoneNumbers.List(context.TODO(), zavudev.PhoneNumberListParams{
Status: zavudev.String("active"),
})
```
```php 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";
}
// Filter by status
$activeNumbers = $client->phoneNumbers->list(['status' => 'active']);
```
```bash cURL theme={null}
curl "https://api.zavu.dev/v1/phone-numbers" \
-H "Authorization: Bearer $ZAVU_API_KEY"
# Filter by status
curl "https://api.zavu.dev/v1/phone-numbers?status=active" \
-H "Authorization: Bearer $ZAVU_API_KEY"
```
## Getting Phone Number Details
Retrieve details for a specific phone number:
```typescript TypeScript theme={null}
const number = await zavu.phoneNumbers.retrieve("pn_abc123");
console.log(number.phoneNumber);
console.log("Assigned to sender:", number.senderId);
console.log("Next renewal:", number.nextRenewalDate);
```
```python Python theme={null}
number = zavu.phone_numbers.retrieve("pn_abc123")
print(number.phone_number)
print("Assigned to sender:", number.sender_id)
print("Next renewal:", number.next_renewal_date)
```
```ruby Ruby theme={null}
number = client.phone_numbers.retrieve("pn_abc123")
puts number.phone_number
puts "Assigned to sender: #{number.sender_id}"
puts "Next renewal: #{number.next_renewal_date}"
```
```go Go theme={null}
number, _ := client.PhoneNumbers.Get(context.TODO(), "pn_abc123")
fmt.Println(number.PhoneNumber)
fmt.Println("Assigned to sender:", number.SenderID)
fmt.Println("Next renewal:", number.NextRenewalDate)
```
```php PHP theme={null}
$number = $client->phoneNumbers->retrieve('pn_abc123');
echo "{$number->phoneNumber}\n";
echo "Assigned to sender: {$number->senderId}\n";
echo "Next renewal: {$number->nextRenewalDate}\n";
```
```bash cURL theme={null}
curl "https://api.zavu.dev/v1/phone-numbers/pn_abc123" \
-H "Authorization: Bearer $ZAVU_API_KEY"
```
## Updating a Phone Number
Update the name of a phone number:
```typescript TypeScript theme={null}
const number = await zavu.phoneNumbers.update("pn_abc123", {
name: "Marketing Line",
});
```
```python Python theme={null}
number = zavu.phone_numbers.update(
"pn_abc123",
name="Marketing Line"
)
```
```ruby Ruby theme={null}
number = client.phone_numbers.update("pn_abc123",
name: "Marketing Line"
)
```
```go Go theme={null}
number, _ := client.PhoneNumbers.Update(context.TODO(), "pn_abc123", zavudev.PhoneNumberUpdateParams{
Name: zavudev.String("Marketing Line"),
})
```
```php PHP theme={null}
$number = $client->phoneNumbers->update('pn_abc123', [
'name' => 'Marketing Line',
]);
```
```bash cURL theme={null}
curl -X PATCH https://api.zavu.dev/v1/phone-numbers/pn_abc123 \
-H "Authorization: Bearer $ZAVU_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Marketing Line"
}'
```
## Assigning to a Sender
Connect a phone number to a sender profile for use in messaging:
```typescript TypeScript theme={null}
const number = await zavu.phoneNumbers.update("pn_abc123", {
senderId: "snd_xyz789",
});
```
```python Python theme={null}
number = zavu.phone_numbers.update(
"pn_abc123",
sender_id="snd_xyz789"
)
```
```ruby Ruby theme={null}
number = client.phone_numbers.update("pn_abc123",
sender_id: "snd_xyz789"
)
```
```go Go theme={null}
number, _ := client.PhoneNumbers.Update(context.TODO(), "pn_abc123", zavudev.PhoneNumberUpdateParams{
SenderID: zavudev.String("snd_xyz789"),
})
```
```php PHP theme={null}
$number = $client->phoneNumbers->update('pn_abc123', [
'senderId' => 'snd_xyz789',
]);
```
```bash cURL theme={null}
curl -X PATCH https://api.zavu.dev/v1/phone-numbers/pn_abc123 \
-H "Authorization: Bearer $ZAVU_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"senderId": "snd_xyz789"
}'
```
To unassign a phone number from a sender:
```typescript theme={null}
const number = await zavu.phoneNumbers.update("pn_abc123", {
senderId: null,
});
```
## Releasing a Phone Number
Release a phone number you no longer need:
```typescript TypeScript theme={null}
await zavu.phoneNumbers.release("pn_abc123");
```
```python Python theme={null}
zavu.phone_numbers.release("pn_abc123")
```
```ruby Ruby theme={null}
client.phone_numbers.release("pn_abc123")
```
```go Go theme={null}
client.PhoneNumbers.Release(context.TODO(), "pn_abc123")
```
```php PHP theme={null}
$client->phoneNumbers->release('pn_abc123');
```
```bash cURL theme={null}
curl -X DELETE https://api.zavu.dev/v1/phone-numbers/pn_abc123 \
-H "Authorization: Bearer $ZAVU_API_KEY"
```
You cannot release a phone number that is assigned to a sender. Unassign it first by setting `senderId` to `null`.
## Phone Number Statuses
| Status | Description |
| ----------- | ----------------------------------------------- |
| `active` | Ready to use for messaging |
| `pending` | Purchase in progress |
| `suspended` | Temporarily disabled (e.g., for payment issues) |
## Using Phone Numbers with Channels
Phone numbers can be used with different messaging channels:
### SMS
Phone numbers are directly used as the sender ID for SMS messages. Simply assign the phone number to a sender and start sending.
### WhatsApp
For WhatsApp, you need to register your phone number with WhatsApp Business API. The phone number is used to receive the verification code during WhatsApp Business Account setup.
WhatsApp Business registration requires a phone number that can receive SMS. Your Zavu phone number works perfectly for this.
## Pricing
Phone number pricing varies by country and type:
| Component | Description |
| ---------------- | --------------------------------------------------- |
| `upfrontPrice` | One-time purchase cost |
| `monthlyPrice` | Recurring monthly fee |
| `isFreeEligible` | Whether this qualifies for the free first US number |
Prices are displayed in USD. Monthly fees are automatically charged from your account balance.
## Best Practices
Give descriptive names to phone numbers so you can easily identify their purpose.
Regularly check the status of your phone numbers to ensure they're active.
Purchase numbers based on your messaging volume and geographic needs.
Local numbers often have higher delivery rates than toll-free numbers for certain use cases.
## Next Steps
Connect your phone number to a sender profile
Start sending SMS messages