Twilio allows you to manually transfer both long code and short code phone 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.

Hosted Numbers: We do not currently support a manual process for hosted SMS phone number transfers between account SIDs. Please email Porting@Twilio.com to submit a request to the Porting Team to transfer Hosted Numbers to a different account SID.

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.

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.

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.