Purchasing Phone Numbers

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:

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);
}

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)

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

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)
}

$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";
}

curl "https://api.zavu.dev/v1/phone-numbers/available?countryCode=US&type=local&limit=10" \
  -H "Authorization: Bearer $ZAVUDEV_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

{
  "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 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:

const phoneNumber = await zavu.phoneNumbers.purchase({
  phoneNumber: "+14155551234",
  name: "Customer Support",
});

console.log("Purchased:", phoneNumber.phoneNumber);
console.log("ID:", phoneNumber.id);

phone_number = zavu.phone_numbers.purchase(
    phone_number="+14155551234",
    name="Customer Support"
)

print("Purchased:", phone_number.phone_number)
print("ID:", phone_number.id)

phone_number = client.phone_numbers.purchase(
  phone_number: "+14155551234",
  name: "Customer Support"
)

puts "Purchased: #{phone_number.phone_number}"
puts "ID: #{phone_number.id}"

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)

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

echo "Purchased: {$phoneNumber->phoneNumber}\n";
echo "ID: {$phoneNumber->id}\n";

curl -X POST https://api.zavu.dev/v1/phone-numbers \
  -H "Authorization: Bearer $ZAVUDEV_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

{
  "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:

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",
});

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")

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")

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"),
})

$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']);

curl "https://api.zavu.dev/v1/phone-numbers" \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY"

# Filter by status
curl "https://api.zavu.dev/v1/phone-numbers?status=active" \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY"

Getting Phone Number Details

Retrieve details for a specific phone number:

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);

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)

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}"

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)

$number = $client->phoneNumbers->retrieve('pn_abc123');

echo "{$number->phoneNumber}\n";
echo "Assigned to sender: {$number->senderId}\n";
echo "Next renewal: {$number->nextRenewalDate}\n";

curl "https://api.zavu.dev/v1/phone-numbers/pn_abc123" \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY"

Updating a Phone Number

Update the name of a phone number:

const number = await zavu.phoneNumbers.update("pn_abc123", {
  name: "Marketing Line",
});

number = zavu.phone_numbers.update(
    "pn_abc123",
    name="Marketing Line"
)

number = client.phone_numbers.update("pn_abc123",
  name: "Marketing Line"
)

number, _ := client.PhoneNumbers.Update(context.TODO(), "pn_abc123", zavudev.PhoneNumberUpdateParams{
	Name: zavudev.String("Marketing Line"),
})

$number = $client->phoneNumbers->update('pn_abc123', [
    'name' => 'Marketing Line',
]);

curl -X PATCH https://api.zavu.dev/v1/phone-numbers/pn_abc123 \
  -H "Authorization: Bearer $ZAVUDEV_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:

const number = await zavu.phoneNumbers.update("pn_abc123", {
  senderId: "snd_xyz789",
});

number = zavu.phone_numbers.update(
    "pn_abc123",
    sender_id="snd_xyz789"
)

number = client.phone_numbers.update("pn_abc123",
  sender_id: "snd_xyz789"
)

number, _ := client.PhoneNumbers.Update(context.TODO(), "pn_abc123", zavudev.PhoneNumberUpdateParams{
	SenderID: zavudev.String("snd_xyz789"),
})

$number = $client->phoneNumbers->update('pn_abc123', [
    'senderId' => 'snd_xyz789',
]);

curl -X PATCH https://api.zavu.dev/v1/phone-numbers/pn_abc123 \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "senderId": "snd_xyz789"
  }'

To unassign a phone number from a sender:

const number = await zavu.phoneNumbers.update("pn_abc123", {
  senderId: null,
});

Releasing a Phone Number

Release a phone number you no longer need:

await zavu.phoneNumbers.release("pn_abc123");

zavu.phone_numbers.release("pn_abc123")

client.phone_numbers.release("pn_abc123")

client.PhoneNumbers.Release(context.TODO(), "pn_abc123")

$client->phoneNumbers->release('pn_abc123');

curl -X DELETE https://api.zavu.dev/v1/phone-numbers/pn_abc123 \
  -H "Authorization: Bearer $ZAVUDEV_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.

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

Name Your Numbers

Give descriptive names to phone numbers so you can easily identify their purpose.

Monitor Status

Regularly check the status of your phone numbers to ensure they’re active.

Plan Capacity

Purchase numbers based on your messaging volume and geographic needs.

Use Local Numbers

Local numbers often have higher delivery rates than toll-free numbers for certain use cases.

Getting Started

Build agents

Send & receive

Operate

Developer tools

Integrations

Purchasing Phone Numbers

Free US Phone Number

Searching for Available Numbers

Search Parameters

Response

Regulatory Requirements

Purchasing a Phone Number

Purchase Parameters

Response

Listing Your Phone Numbers

Getting Phone Number Details

Updating a Phone Number

Assigning to a Sender

Releasing a Phone Number

Phone Number Statuses

Using Phone Numbers with Channels

SMS

WhatsApp

Pricing

Best Practices

Name Your Numbers

Monitor Status

Plan Capacity

Use Local Numbers

Next Steps

Create a Sender

Send SMS

​Free US Phone Number

​Searching for Available Numbers

​Search Parameters

​Response

​Regulatory Requirements

​Purchasing a Phone Number

​Purchase Parameters

​Response

​Listing Your Phone Numbers

​Getting Phone Number Details

​Updating a Phone Number

​Assigning to a Sender

​Releasing a Phone Number

​Phone Number Statuses

​Using Phone Numbers with Channels

​SMS

​WhatsApp

​Pricing

​Best Practices

Name Your Numbers

Monitor Status

Plan Capacity

Use Local Numbers

​Next Steps

Create a Sender

Send SMS

Free US Phone Number

Searching for Available Numbers

Search Parameters

Response

Regulatory Requirements

Purchasing a Phone Number

Purchase Parameters

Response

Listing Your Phone Numbers

Getting Phone Number Details

Updating a Phone Number

Assigning to a Sender

Releasing a Phone Number

Phone Number Statuses

Using Phone Numbers with Channels

SMS

WhatsApp

Pricing

Best Practices

Next Steps