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

# Managing Phone Numbers

> Purchase and assign phone numbers to your applications

Phone numbers must be purchased and assigned to an application before you can send or receive messages.

## Purchasing Phone Numbers

Purchase phone numbers through the Chirp dashboard:

1. Navigate to your organization's Phone Numbers page
2. Click "Purchase Number"
3. Select your desired number type and location
4. Complete the purchase

Phone numbers are billed with a one-time purchase fee and a recurring monthly rental fee. See [Pricing](/getting_started/pricing) for details.

## Assigning Numbers to Applications

After purchasing a phone number, assign it to an application:

**Via Dashboard**

1. Go to your application's Phone Numbers page
2. Click "Assign Number"
3. Select the phone number from your organization's available numbers
4. Confirm the assignment

**Via API**

Use the `POST /v1/phone-numbers` endpoint:

```bash theme={null}
curl -X POST https://api.buildwithchirp.com/v1/phone-numbers \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumberId": "550e8400-e29b-41d4-a716-446655440000"
  }'
```

## Sharing Numbers Across Applications

You can assign the same phone number to multiple applications. This allows you to:

* Reuse numbers across different projects
* Route messages based on the application context
* Maintain separate webhook configurations per application

Each application will use its own API keys and webhook settings when handling messages.

## Removing Numbers

To remove a phone number from an application:

**Via Dashboard**

1. Go to your application's Phone Numbers page
2. Find the number you want to remove
3. Click "Remove" and confirm

**Via API**

Use the `DELETE /v1/phone-numbers/{phoneNumberId}` endpoint.

<Note>
  Removing a number from an application does not delete it from your organization. The number
  remains available for reassignment to other applications.
</Note>

## Number Types

Different number types have different capabilities and pricing:

* **Local Numbers** - Standard geographic numbers
* **Toll-Free Numbers** - 800/888/877 numbers for national reach
* **Short Codes** - 5-6 digit numbers for high-volume messaging (US only)

See [Phone Numbers](/concepts/phone-numbers) for more details on each type.