SUPPORT.TWILIO.COM END OF LIFE NOTICE: This site, support.twilio.com, is scheduled to go End of Life on February 27, 2024. All Twilio Support content has been migrated to help.twilio.com, where you can continue to find helpful Support articles, API docs, and Twilio blog content, and escalate your issues to our Support team. We encourage you to update your bookmarks and begin using the new site today for all your Twilio Support needs.

Move Phone Numbers Between Twilio Accounts and their Subaccounts

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 created functions you can quickly create a web app using Twilio Functions that allows you to complete an account transfer for your numbers and more!

The Twilio Function only takes about 10-15 minutes to set up. There is no coding required, just some copy and pasting on your part.

  • 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.

Before creating the app on your Twilio account, you can test it on our Demo account

When you are ready to set up your App using Functions 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 SIDAddress 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:

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.

Have more questions? Submit a request
Powered by Zendesk