Skip to main content
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: 
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

const result = await client.phoneNumbers.searchAvailable({
  countryCode: "US",      // Required: Two-letter country code
  type: "local",          // Optional: local, mobile, tollFree
  contains: "555",        // Optional: Pattern to search for
  limit: 20,              // Optional: Max results (default: 10, max: 50)
});

​
Purchase a Phone Number

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

console.log(phoneNumber.id);           // pn_abc123
console.log(phoneNumber.phoneNumber);  // +14155551234
console.log(phoneNumber.status);       // active
Your first US phone number is free. The isFreeEligible field in search results indicates eligible numbers.

​
List Phone Numbers

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 result = await client.phoneNumbers.list({
  status: "active",
  limit: 50,
  cursor: "cursor_xxx",
});

​
Get Phone Number

const number = await client.phoneNumbers.get({
  phoneNumberId: "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: 
// Update name
const number = await client.phoneNumbers.update({
  phoneNumberId: "pn_abc123",
  name: "Marketing Line",
});

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

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

​
Release Phone Number

Release a phone number you no longer need: 
await client.phoneNumbers.release({
  phoneNumberId: "pn_abc123",
});
You cannot release a phone number assigned to a sender. Unassign it first.

​
Response Types

​
Phone Number Object

interface PhoneNumber {
  id: string;
  phoneNumber: string;
  name?: string;
  capabilities: string[];        // ["sms", "voice", "mms"]
  status: "active" | "suspended" | "pending";
  senderId?: string;
  pricing: {
    monthlyPrice: number;
    upfrontCost: number;
    monthlyCost: number;
    isFreeNumber: boolean;
  };
  nextRenewalDate?: string;
  createdAt: string;
  updatedAt?: string;
}

​
Available Phone Number Object

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

try {
  const number = await client.phoneNumbers.purchase({
    phoneNumber: "+14155551234",
  });
} catch (error) {
  if (error.code === "insufficient_balance") {
    console.log("Add funds to your account");
  } else if (error.code === "not_found") {
    console.log("Phone number is no longer available");
  }
}