Twilio allows you to manually transfer both long code and short code phone numbers between projects and their subaccounts, or between two subaccounts under the same project. This guide explains how this process is done.
Notice: We do not currently support a manual process for phone number transfers between two projects, or a project and an unrelated subaccount. For full details on how to submit these requests, see Moving Twilio phone numbers to another Twilio project.
You can transfer phone number between a project 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 project or subaccount that is giving up the phone number.
- Gaining Account SID: The AC SID for the project 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 project or subaccount that will be receiving the phone number.
- Project credentials: The Account SID and Auth Token for your Twilio project.
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 project
AC00000000000000000000000000000001 to subaccount
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 Project'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 project 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 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 projects, or a project 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 project 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 project'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.
Moving phone numbers between projects and subaccounts is not available in Console at this time.