> ## 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 Go 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:

```go theme={null}
result, err := client.PhoneNumbers.SearchAvailable(context.TODO(), zavudev.PhoneNumberSearchAvailableParams{
	CountryCode: zavudev.String("US"),
	Type:        zavudev.String("local"),
	Limit:       zavudev.Int(10),
})
if err != nil {
	panic(err)
}

for _, number := range result.Items {
	fmt.Println(number.PhoneNumber, number.Locality, number.Region)
	fmt.Println("Monthly:", number.Pricing.MonthlyPrice)
	fmt.Println("Free eligible:", number.Pricing.IsFreeEligible)
}
```

### Search Parameters

```go theme={null}
result, err := client.PhoneNumbers.SearchAvailable(context.TODO(), zavudev.PhoneNumberSearchAvailableParams{
	CountryCode: zavudev.String("US"),    // Required: Two-letter country code
	Type:        zavudev.String("local"), // Optional: local, mobile, tollFree
	Contains:    zavudev.String("555"),   // Optional: Pattern to search for
	Limit:       zavudev.Int(20),         // Optional: Max results (default: 10, max: 50)
})
```

## Purchase a Phone Number

```go theme={null}
result, err := client.PhoneNumbers.Purchase(context.TODO(), zavudev.PhoneNumberPurchaseParams{
	PhoneNumber: zavudev.String("+14155551234"),
	Name:        zavudev.String("Customer Support"),
})
if err != nil {
	panic(err)
}

fmt.Println(result.PhoneNumber.ID)          // pn_abc123
fmt.Println(result.PhoneNumber.PhoneNumber) // +14155551234
fmt.Println(result.PhoneNumber.Status)      // active
```

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

## List Phone Numbers

```go theme={null}
result, err := client.PhoneNumbers.List(context.TODO(), zavudev.PhoneNumberListParams{})
if err != nil {
	panic(err)
}

for _, number := range result.Items {
	fmt.Println(number.ID, number.PhoneNumber, number.Name)
	fmt.Println("Status:", number.Status)
	fmt.Println("Assigned to:", number.SenderID)
}

// With filters
result, err := client.PhoneNumbers.List(context.TODO(), zavudev.PhoneNumberListParams{
	Status: zavudev.String("active"),
	Limit:  zavudev.Int(50),
	Cursor: zavudev.String("cursor_xxx"),
})
```

## Get Phone Number

```go theme={null}
result, err := client.PhoneNumbers.Get(context.TODO(), "pn_abc123")
if err != nil {
	panic(err)
}

fmt.Println(result.PhoneNumber.PhoneNumber)
fmt.Println(result.PhoneNumber.Name)
fmt.Println(result.PhoneNumber.Capabilities)
fmt.Println(result.PhoneNumber.Pricing.MonthlyPrice)
fmt.Println(result.PhoneNumber.NextRenewalDate)
```

## Update Phone Number

Update the name or sender assignment:

```go theme={null}
// Update name
result, err := client.PhoneNumbers.Update(context.TODO(), "pn_abc123", zavudev.PhoneNumberUpdateParams{
	Name: zavudev.String("Marketing Line"),
})

// Assign to a sender
result, err := client.PhoneNumbers.Update(context.TODO(), "pn_abc123", zavudev.PhoneNumberUpdateParams{
	SenderID: zavudev.String("snd_xyz789"),
})

// Unassign from sender
result, err := client.PhoneNumbers.Update(context.TODO(), "pn_abc123", zavudev.PhoneNumberUpdateParams{
	SenderID: nil,
})
```

## Release Phone Number

Release a phone number you no longer need:

```go theme={null}
err := client.PhoneNumbers.Release(context.TODO(), "pn_abc123")
if err != nil {
	panic(err)
}
```

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

## Response Types

### Phone Number Object

```go theme={null}
type OwnedPhoneNumber struct {
	ID           string                  `json:"id"`
	PhoneNumber  string                  `json:"phoneNumber"`
	Name         *string                 `json:"name"`
	Capabilities []string                `json:"capabilities"` // ["sms", "voice", "mms"]
	Status       string                  `json:"status"`       // active, suspended, pending
	SenderID     *string                 `json:"senderId"`
	Pricing      OwnedPhoneNumberPricing `json:"pricing"`
	NextRenewalDate *string              `json:"nextRenewalDate"`
	CreatedAt    string                  `json:"createdAt"`
	UpdatedAt    *string                 `json:"updatedAt"`
}

type OwnedPhoneNumberPricing struct {
	MonthlyPrice float64 `json:"monthlyPrice"`
	UpfrontCost  float64 `json:"upfrontCost"`
	MonthlyCost  float64 `json:"monthlyCost"`
	IsFreeNumber bool    `json:"isFreeNumber"`
}
```

### Available Phone Number Object

```go theme={null}
type AvailablePhoneNumber struct {
	PhoneNumber  string                      `json:"phoneNumber"`
	FriendlyName *string                     `json:"friendlyName"`
	Locality     *string                     `json:"locality"`
	Region       *string                     `json:"region"`
	Capabilities PhoneNumberCapabilities     `json:"capabilities"`
	Pricing      AvailablePhoneNumberPricing `json:"pricing"`
}

type PhoneNumberCapabilities struct {
	SMS   bool `json:"sms"`
	Voice bool `json:"voice"`
	MMS   bool `json:"mms"`
}

type AvailablePhoneNumberPricing struct {
	MonthlyPrice   float64 `json:"monthlyPrice"`
	UpfrontPrice   float64 `json:"upfrontPrice"`
	IsFreeEligible bool    `json:"isFreeEligible"`
}
```

## Error Handling

```go theme={null}
result, err := client.PhoneNumbers.Purchase(context.TODO(), zavudev.PhoneNumberPurchaseParams{
	PhoneNumber: zavudev.String("+14155551234"),
})
if err != nil {
	var apiErr *zavudev.APIError
	if errors.As(err, &apiErr) {
		switch apiErr.Code {
		case "insufficient_balance":
			fmt.Println("Add funds to your account")
		case "not_found":
			fmt.Println("Phone number is no longer available")
		default:
			fmt.Println("Error:", apiErr.Message)
		}
	}
	return
}
```