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.

Plans and the Included Number

Buying phone numbers requires a paid plan: on the Free plan the purchase is refused with 402 paid_plan_required. A paid plan includes one number at no charge, once per account: it must be a US or Canadian number (a +1 number) costing $20 a month or less. The included number is one per account, across every team its owner owns, and is granted once: releasing it does not make another number free. Search results mark the numbers that qualify with pricing.isFreeEligible.

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: "US",
	Type:        zavudev.PhoneNumberTypeLocal,
	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`, `national`, `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 numbers require regulatory information (an address, a document, or text) before they can be used. Which ones is decided per number, and the purchase checks it for the exact number before charging anything. Look it up with GET /v1/phone-numbers/requirements?phoneNumber=%2B... before buying. A number with requirements is bought with type and regulatoryRequirements, starts with regulatoryStatus: pending_review, and can send messages and place calls once it is approved. The Regulatory Requirements guide covers:

Looking up the requirements for a number
Creating addresses and uploading documents
Including requirements in your purchase request
Reusing information submitted before
Following review and assigning the number to a sender

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.phoneNumber);
console.log("ID:", phoneNumber.phoneNumber.id);

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

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

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

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

phoneNumber, _ := client.PhoneNumbers.Purchase(context.TODO(), zavudev.PhoneNumberPurchaseParams{
	PhoneNumber: "+14155551234",
	Name:        zavudev.String("Customer Support"),
})

fmt.Println("Purchased:", phoneNumber.PhoneNumber.PhoneNumber)
fmt.Println("ID:", phoneNumber.PhoneNumber.ID)

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

echo "Purchased: {$phoneNumber->phoneNumber->phoneNumber}\n";
echo "ID: {$phoneNumber->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)
`type`	string	With `regulatoryRequirements`	The type the number was found under: `local`, `national`, `mobile`, or `tollFree`. A number not listed under it is refused with `400 number_unavailable`
`regulatoryRequirements`	array	For numbers with requirements	`{ requirementType, fieldValue }` entries. See Regulatory Requirements. Not in the SDKs yet: use REST

Response

{
  "phoneNumber": {
    "id": "pn_abc123",
    "phoneNumber": "+14155551234",
    "name": "Customer Support",
    "capabilities": ["sms", "voice"],
    "status": "active",
    "regulatoryStatus": "approved",
    "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 and the first month 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.PhoneNumberStatusActive,
})

$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 { phoneNumber: 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").phone_number

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

puts number.phone_number
puts "Assigned to sender: #{number.sender_id}"
puts "Next renewal: #{number.next_renewal_date}"

res, _ := client.PhoneNumbers.Get(context.TODO(), "pn_abc123")
number := res.PhoneNumber

fmt.Println(number.PhoneNumber)
fmt.Println("Assigned to sender:", number.SenderID)
fmt.Println("Next renewal:", number.NextRenewalDate)

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

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. A number still under regulatory review (regulatoryStatus: pending_review) can be assigned too: it is connected to the sender when review approves it. A number rejected in review cannot be assigned, and the call answers 400.

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`	Owned and billing. Usable for messaging when `regulatoryStatus` is also `approved`
`suspended`	Temporarily disabled (e.g., for payment issues)
`releasing`	Being released; it can no longer send
`released`	Released; it can no longer send
`pending`	Legacy. Accepted by the `status` filter, never written to a number today

The SDK status enums carry active, suspended and pending only; read releasing and released from the REST response until their next release.

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 number qualifies as the one included in your paid plan

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

Plans and the Included 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

​Plans and the Included 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

Plans and the Included 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