Skip to main content
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 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: 
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.
Removing a number from an application does not delete it from your organization. The number remains available for reassignment to other applications.

​
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 for more details on each type.
⌘I