Twilio phone numbers are billed on a monthly basis. Unless you are actively using a number, or you want to keep a number reserved for future use, you can reduce your costs by releasing your unused numbers. This guide explains the process.
Emergency Address
Before a number can be released any registered emergency address will need to be removed either in Console or via API. Please see the following resources for how to unregister your emergency address if needed:
Console: How to Unregister an Emergency Address from a Twilio Phone Number
API: Emergency Calling for SIP Trunking
Release a Phone Number via Console
- Access the Active Numbers page in Console.
- Click the desired phone number you wish to release.
- Click on the Properties tab under the number
- Under the Actions section in the Release phone number box click Release phone number.
- Confirm the release on the popup screen, by clicking Release this number.
- You will be taken to the Released Numbers page where you can repurchase the number within 10 days if needed.
Release a Phone Number via the REST API
Your Twilio phone number can be released by submitting an HTTP DELETE request to the IncomingPhoneNumber REST API Resource. Here's an example cURL script:
curl -X DELETE https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/IncomingPhoneNumbers/PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json \
-u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token'This example will release the phone number PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX from your Twilio account. To make this script work for you, make the following updates, and then paste it into a terminal window:
-
Line 1: update with your Twilio Account SID (
ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX) and the incoming phone number's SID (PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX). - Line 2: update with your Account SID and Auth Token.
For additional help, please see our Delete an IncomingPhoneNumber REST API resource documentation.
Phone Numbers in Subaccounts
If you have set up subaccounts of your account, the phone numbers owned by your subaccounts will not appear on the Active Numbers Console page of your main account. You will need to go to the Active Numbers page for your specific subaccount to see release these numbers.
For help switching between subaccounts, please see View and Create New Twilio Subaccounts.
After Releasing a Phone Number
Once you release a number, it goes through a period of recycling and testing in order to make it look as good as new for the next owner. You also have the option of reclaiming the number back in Console within 10 days of the release. For more information, please see Restoring a previously released phone number.
It is important to keep in mind that numbers which are reclaimed to your account in this manner will have their billing cycles restarted. Essentially, you will need to buy the number again.
Please be very sure that you know what you are doing before you release a number.