# Phone Numbers

> Search, purchase and assign phone numbers via the Zavu TypeScript SDK. Manage SMS, WhatsApp and Voice numbers across countries with one API.

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
```

> **Info:**
> Buying numbers requires a paid plan (`402 paid_plan_required` on Free). A paid plan includes one number at no charge, once per account: a US or Canadian number (a +1 number) costing $20 a month or less; `isFreeEligible` in search results marks the number that qualifies.

> **Info:**
> Some numbers require regulatory information before they can be used; the purchase checks the exact number before charging anything. The SDK does not send `type` or `regulatoryRequirements` yet: for those numbers use the REST flow in [Regulatory Requirements](https://www.zavu.dev/docs/guides/phone-numbers/regulatory-requirements), then poll the number's regulatory status until it is `approved`. A sender can be assigned before or after approval.

## 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");
```

> **Warning:**
> You cannot release a phone number assigned to a sender. Unassign it first.

## 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");
    }
  }
}
```