Move Phone Numbers Between Twilio Projects and their Subaccounts (Internal Transfer)

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.

API request

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.
  • Project credentials: The Account SID and Auth Token for your Twilio project.
  • Identity SID or Address SID: Any Identity or Address SID required for Regulatory compliance.

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 "AddressSid=ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -u AC00000000000000000000000000000001:your_auth_token

This example requests to move PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX from project AC00000000000000000000000000000001 to subaccount AC00000000000000000000000000000002.

To make this script work for you, make the following updates, and then paste it into a terminal window:

For full details, including code samples for our Helper Libraries, see Exchanging Phone Numbers between accounts (Twilio Docs).

Notice Many countries require identity documentation for Phone Number compliance. Requests to move phone numbers with these regulations will be required to include a valid AddressSid and/or IdentitySid parameter, or else the request may fail. 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 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 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.

Console process

Moving phone numbers between projects and subaccounts is not available in Console at this time.

Have more questions? Submit a request
Powered by Zendesk