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:

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

Search Parameters

Response

JSONCopy
{
  "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
      }
    }
  ]
}

Empty results and errors

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:

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

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

Purchase Parameters

Response

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

Listing Your Phone Numbers

View all phone numbers owned by your project:

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

Getting Phone Number Details

Retrieve details for a specific phone number:

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

Updating a Phone Number

Update the name of a phone number:

TypeScriptcURLCopy
const number = await zavu.phoneNumbers.update("pn_abc123", {
  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.

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

To unassign a phone number from a sender:

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

Releasing a Phone Number

Release a phone number you no longer need:

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

Phone Number Statuses

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

A number on its way out carries releaseAt: the date it goes back to the carrier, after a paid plan ended or at the end of the 7-day grace after a renewal could not be paid. Paying, or returning to a paid plan, before that date keeps it. A released number cannot be recovered.

When a paid plan ends

Without a paid plan a team keeps one number:

• Which one. The one chosen in the dashboard when cancelling. Without a choice, the number the plan included; without one, the oldest number the team bought. Numbers you brought yourself are never released.
• How it is paid. Monthly from the balance, at its listed price. A number the plan included is charged its first month when the plan ends; a bought number keeps its renewal date. A renewal the balance cannot pay suspends it, and it is released at the end of the 7-day grace.
• Every other number keeps working, unbilled, and is released 7 days after the plan ends. releaseAt carries the exact date (00:00 UTC of the day after the window closes).
• Coming back to a paid plan. Before releaseAt, the numbers on their way out stay and bill as paid numbers again. The kept number is the included one again if it was the included one; otherwise it stays a paid number.

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.

Pricing

Phone number pricing varies by country and type:

Best Practices

Next Steps