Twilio allows you to manually transfer long code, short code and hosted numbers between accounts and their subaccounts, or between two subaccounts under the same account. This guide explains how this process is done.
Notice: We do not currently support a manual process for phone number transfers between two accounts, or an account and an unrelated subaccount. For full details on how to submit these requests, see Moving Twilio phone numbers to another Twilio project.
WhatsApp Activated Numbers: If you would like to maintain the active WhatsApp Sender IDs on the gaining account SIDs please be sure to reach out to Support to transfer the related WhatsApp Senders first. If you do not transfer the WhatsApp Senders before the number you will need to re-register the number for WhatsApp use.
Table of Contents
Twilio Functions
Using Twilio's Quick Deploy Applications feature in Code Exchange you can create and use Twilio Function applications within minutes. With Twilio Functions you can quickly create a web app that allows you to complete an account transfer for your numbers and more!
With Quick Deploy in Code Exchange, the Twilio Function only takes about 5 minutes to set up. There is no coding required.
- The app is powered by Twilio Functions within your Twilio account.
- The app will allow you, and anyone on your team that you provide the app link and password, to view or export your active numbers listing from your account SID or a related subaccount.
Create your Transfer Twilio Numbers application now with Code Exchange!
- Before creating the app on your Twilio account, you can test it on our Demo account.
For how to create your Twilio Functions App directly in Console head over to our Blog Post where we provide you with the walkthrough steps and instructional video which shows how to quickly setup the app on your Twilio account.
Blog: Quickly export a list of active Twilio numbers, transfer them, and check their usage
API request
You can transfer phone number between an account and its subaccounts by making an HTTP POST request to the IncomingPhoneNumber REST API resource of the phone number you want to move. In this request, you will need to include the following pieces of information:
- Phone Number SID: The PN SID (long code) or SC SID (short code) for the phone number you wish to move.
- Losing Account SID: The AC SID for the account or subaccount that is giving up the phone number.
- Gaining Account SID: The AC SID for the account or subaccount that will be receiving the phone number.
- Regulatory Requirements (if required): A Bundle (BU SID), Address (AD SID), or both may be needed for regulatory compliance on the account or subaccount that will be receiving the phone number.
- Account credentials: The Account SID and Auth Token for your Twilio account.
Here’s an example cURL script:
curl -X POST https://api.twilio.com/2010-04-01/Accounts/AC00000000000000000000000000000001/IncomingPhoneNumbers/PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json \
--data-urlencode "AccountSid=AC00000000000000000000000000000002" \
--data-urlencode "BundleSid=BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
--data-urlencode "AddressSid=ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-u AC00000000000000000000000000000001:your_auth_token
This example requests to move PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX from account AC00000000000000000000000000000001 to subaccount AC00000000000000000000000000000002.
To make this script work for you, make the following updates, and then paste it into a terminal window:
- Line 1 update with the Account SID that currently owns the phone number, and the phone number's SID.
- Line 2 update with your Account SID you want to move the phone number to.
- Lines 3 & 4 either remove or update with a valid Bundle SID, Address SID, or both as needed for regulatory compliance.
- Line 5 update with your account's Account SID and Auth Token.
For full details, including code samples for our Helper Libraries, see Exchanging Phone Numbers between accounts (Twilio Docs).
Notice Many countries require identity documentation with Phone Numbers for regulatory compliance. Requests to move phone numbers based in countries that have enacted these regulations will fail if they don't include the required AddressSid and / or BundleSid created on the receiving account or subaccount. To see which countries and phone number types are affected by these requirements, please see our Phone Number Regulations site.
After your phone number has been successfully transferred, the gaining Account SID will be charged for the full monthly price of the phone number. For more details, please see How much does a phone number cost.
API Request Troubleshooting
API requests to move phone numbers may result in an error if performed incorrectly. If you run into an error with this request, please validate the following:
- Requests to move phone numbers between different accounts, or a account and an unrelated subaccount will result in an Error 21473 response. For help submitting these requests, see Moving Twilio phone numbers to another Twilio project.
- Requests to move phone numbers without valid regulatory requirements on the receiving account or subaccount may result in an Error 21613 or Error 21649 response.
- Requests to move phone numbers using the wrong credentials may result in Error 20003. Even if moving phone numbers from one subaccount to another, you'll need to use the main account's Account SID and Auth Token.
Notice: A short code SC SID request may result in a false positive error response from the API, but the request will still complete correctly.
Console process
Moving phone numbers between accounts and subaccounts is not available in Console at this time.