> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zavu.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Phone Numbers

> Manage phone numbers with the TypeScript SDK

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 theme={null}
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 theme={null}
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

```typescript theme={null}
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
```

<Info>
  Your first US phone number is free. The `isFreeEligible` field in search results indicates eligible numbers.
</Info>

## List Phone Numbers

```typescript theme={null}
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

```typescript theme={null}
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:

```typescript theme={null}
// 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:

```typescript theme={null}
await client.phoneNumbers.release({
  phoneNumberId: "pn_abc123",
});
```

<Warning>
  You cannot release a phone number assigned to a sender. Unassign it first.
</Warning>

## Response Types

### Phone Number Object

```typescript theme={null}
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

```typescript theme={null}
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 theme={null}
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");
  }
}
```