Phone Numbers

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:

TypeScript
const result = await client.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:", number.pricing.monthlyPrice);
  console.log("Free eligible:", number.pricing.isFreeEligible);
}

Search Parameters

TypeScript
const result = await 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

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

console.log(phoneNumber.phoneNumber.id);               // pn_abc123
console.log(phoneNumber.phoneNumber.phoneNumber);      // +14155551234
console.log(phoneNumber.phoneNumber.status);           // active

List Phone Numbers

TypeScript
const result = await client.phoneNumbers.list({});

for (const number of result.items) {
  console.log(number.id, number.phoneNumber, number.name);
  console.log("Status:", number.status);
  console.log("Assigned to:", number.senderId);
}

// With filters
const filtered = await client.phoneNumbers.list({
  status: "active",
  limit: 50,
  cursor: "cursor_xxx",
});

Get Phone Number

TypeScript
const { phoneNumber: number } = await client.phoneNumbers.retrieve("pn_abc123");

console.log(number.phoneNumber);
console.log(number.name);
console.log(number.capabilities);
console.log(number.pricing.monthlyPrice);
console.log(number.nextRenewalDate);

Update Phone Number

Update the name or sender assignment:

TypeScript
// Update name
await client.phoneNumbers.update("pn_abc123", { name: "Marketing Line" });

// Assign to a sender
await client.phoneNumbers.update("pn_abc123", { senderId: "snd_xyz789" });

// Unassign from sender
await client.phoneNumbers.update("pn_abc123", { senderId: null });

Release Phone Number

Release a phone number you no longer need:

TypeScript
await client.phoneNumbers.release("pn_abc123");

Response Types

Phone Number Object

TypeScript
interface PhoneNumber {
  id: string;
  phoneNumber: string;
  name?: string;
  capabilities: string[];        // ["sms", "voice", "mms"]
  status: "active" | "suspended" | "pending";
  // Not in the SDK types yet; present in the API response.
  regulatoryStatus: "approved" | "pending_review" | "rejected";
  senderId?: string;
  pricing: {
    monthlyPrice: number;
    upfrontCost: number;
    monthlyCost: number;
    isFreeNumber: boolean;
  };
  nextRenewalDate?: string;
  createdAt: string;
  updatedAt?: string;
}

Available Phone Number Object

TypeScript
interface AvailablePhoneNumber {
  phoneNumber: string;
  friendlyName?: string;
  locality?: string;
  region?: string;
  capabilities: {
    sms: boolean;
    voice: boolean;
    mms: boolean;
  };
  pricing: {
    monthlyPrice: number;
    upfrontPrice: number;
    isFreeEligible: boolean;
  };
}

Error Handling

TypeScript
import { APIError } from "@zavudev/sdk";

try {
  await client.phoneNumbers.purchase({ phoneNumber: "+14155551234" });
} catch (error) {
  if (error instanceof APIError) {
    const code = (error.error as { code?: string } | undefined)?.code;
    if (code === "insufficient_balance") {
      console.log("Add funds to your account");
    } else if (code === "number_unavailable") {
      console.log("Phone number is no longer available");
    } else if (code === "regulatory_compliance_required") {
      console.log("This number needs regulatory information");
    }
  }
}