Twilio Porting API overview and tips

General
Porting Process
Pricing

General

Geographic coverage of the Twilio Porting API

The Twilio Porting API is currently only available for porting United States landline and wireless numbers. We plan to expand to other regions soon. Please note that while using the Twilio Porting API is recommended, you may continue to request all types of US ports through the Console. You can also email us at porting@twilio.com to port Canadian numbers. 

Type of US numbers that can be ported using the Twilio Porting API

Initially, you will be able to use the API to port to Twilio Landline, Mobile/Wireless, Google, and VoIP numbers in the US, but not Toll-Free numbers. However, you will be able to continue to port all types of US numbers (including Toll-Free numbers) through the Console. There are a few rural area codes that are not currently covered by our network; consequently, you will not be able to port numbers in these areas. If a number is not portable, the API will return an error with code 21827.

Voice and SMS Capabilities for US numbers ported using the Twilio Porting API

US local numbers ported using the Twilio Porting API will have both voice and SMS capabilities. However, it may take up to 2 hours after port completion for SMS routing to be updated. Messaging will continue routing on the previous provider until it is updated with Twilio. Voice capability, on the other hand, will be available at the port date and time.

SMS routing on US toll free numbers ported into Twilio will complete within 2 hours after port completion in most cases; however, in some instances, updating the SMS to Twilio can take 1-2 days. In these cases, SMS will continue routing through the existing provider. 

Using the Twilio Porting API to port numbers away from Twilio

The API does not support porting numbers away from Twilio. To port numbers away from Twilio, please refer to “How do I port my phone numbers away from Twilio?” for instructions.

Porting Process

Time taken to complete porting using the Twilio Porting API

The time taken to complete a port request depends on both the type of number and the accuracy of the information that you are able to provide us at the outset.

In general, Wireless phone numbers can be ported within the same day (typically, 3 hours after signing the Letter of Authorization) and Landline numbers within 2 weeks. However, port requests require accurate information, such as address and name of the authorized party, that exactly matches the information that your current carrier has on file. Therefore, to ensure that a port happens quickly, we recommend that you always contact your current carrier and specifically ask for the “Customer Service Record” information for your phone numbers. See “How can I obtain a CSR?” for instructions and “Reducing rejections during the porting process” for further background.

Submitting a signed Letter of Authorization using the Twilio Porting API

Once a port request is successfully submitted to Twilio using the API, Twilio will conduct portability checks to verify that Twilio can in fact support porting of the requested phone number. If successful, when you update the correspoding Twilio Port LOAs instance resource by setting its status to "Signing", Twilio will generate an electronic Letter of Authorization (LOA) document using the information that was submitted in the port request. Twilio will then send an email to the address specified in the port request containing the URL to the LOA, for the owner to review and sign electronically.

It is a legal requirement that Twilio have an LOA signed by the owner of the phone number(s) on whose behalf Twilio will port. As the name implies, an LOA authorizes Twilio to take all necessary actions on behalf of the owner of the porting phone numbers to complete the port request. To ensure smooth porting experience, remember that each of the following is important when initiating a new port request using the API:

  • Be sure to POST to the Port Orders list resource the name of the actual owner of the phone number(s). If the signatory does not match the owner of the phone number on file with the current carrier, then the port request will be rejected.
  • Be sure to POST to the Port Orders list resource the service address exactly as it appears in the “Customer Service Record” (CSR) of the current carrier. The service address must be a physical address – not a PO Box – that your current carrier associates with the porting phone number. In some cases, the service address may be different than the address that appears on your billing statement. As the owner of the phone number, you may have to contact your current carrier to find out the exact service address listed in the CSR for the porting phone number(s). Moreover, the service address must be associated with every phone number listed on an LOA. The API will automatically group together port requests comprising porting phone numbers that share the same owner and service address and generate one electronic LOA document that will list these phone numbers in it. If the service address doesn’t match the service address in the CSR of the phone number on file with your current carrier, then the port request will be rejected.
  • Be sure to POST to the Port Orders list resource the correct account number and PIN for any Wireless phone numbers in the port request. If the account number and PIN don’t match the account number and PIN of the phone number(s) on file with your current carrier, then the port request will be rejected.

Setting when the port will occur using the Twilio Porting API

When creating a new port request through POST or updating an existing request through POST or PUT, you can use the attribute “activation_date” of the Port Orders instance resource to set the desired FOC date and time.

Please note, however, that for Landline phone numbers, your requested timing will be overridden if the earliest possible FOC date and time for the port request is at a later date and time. In other words, if you request timing that is too soon for us to complete the port, we will push back the timing of your port to the first possible date and time.

In addition, because a port requires coordination and testing between two carriers, the port may not occur exactly at the requested time, but rather will occur within +/- 2 hours of the confirmed FOC date and time. For Wireless phone numbers, the port will complete within 3 hours of signing the LOA.

Expediting ports using the Twilio Porting API

By using the API, we will be able to port your number more quickly than we could without the API. However, some dependencies still exist. The API will provide the soonest possible date and time at which the number can be ported, assuming that all the information that you submit is accurate. We will not be able to “expedite” the port any more quickly than the soonest possible date and time indicated by the API.

Porting numbers into a subaccount using the Twilio Porting API

To port numbers into a subaccount, you will simply need to use your subaccount’s SID instead of your project’s Account SID when making the port request. You can also transfer numbers between subaccounts, and your project and any one of your subaccounts after the port request is successfully completed – see “Exchanging Phone Numbers Between Accounts” for instructions.

Cancelling a port request for one or more phone numbers using the Twilio Porting API

You can cancel one or more port requests by issuing DELETE to an existing Port Orders instance resource. However, please note that the closer to the date of the port that you cancel, the less likely it is that we will be able to successfully cancel the port, and the more likely it is that you will incur fees and/or increase the risk of a lapse in phone service. Once a port date has been scheduled for your request, we'll no longer be able to process a cancellation. In the event that we are not able to cancel your port request, the API will return an error with code 21830.

Addressing port rejections with the Twilio Porting API

In the event that your port request is rejected, the API will return an error with code 21832 along with the rejection reason. Once a port request is rejected, you will no longer be able to modify the existing Port Orders instance resource that represents this request – rather, you will need to start a new port request (with corrected information, if applicable) to try to port the number again – this will create a new Port Orders instance resource.

There are several common reasons why a port request might be initially rejected by the carrier that is losing the numbers. In nearly all cases, these rejections can be remedied by the rightful user of the phone number such that the port request will be able to proceed. See “Why was my port request rejected?” for more information.

If you have any questions about the rejection and/or need help submitting a new port request, please contact us at porting@twilio.com. To help us resolve the issue as quickly as possible, please provide your project Account SID, the rejected phone number(s) and the corresponding Port Orders and Port LOAs instance resource SIDs, the corresponding rejection reason(s), and any other information that you think might be helpful. For an overview of why numbers might be rejected by your current carrier, or the “losing” carrier, please see “Why was my port request rejected?

Getting support for the Twilio Porting API

Please contact us at porting@twilio.com. To help us resolve the issue as quickly as possible, please provide as much information as possible, including where applicable your project Account SID, the phone number(s) at issue and the corresponding Port Orders and Port LOAs instance resource SIDs, a description of the issue that you are having, screenshots, error code(s) returned by the API, and any other information that you think might be helpful.

Configuring my porting number after using the Twilio Porting API

After you have successfully initiated the port request using the API (i.e., the porting number is deemed portable by Twilio, and the corresponding Port Orders instance resource’s status becomes “Received”), you will be able to configure the porting number in Twilio Console, our web portal, or using Twilio’s Incoming Phone Numbers API – see “REST API: Incoming Phone Numbers” for more information. Please note, however, that the phone number will only be activated after the port successfully completes.

It is recommended that you configure your porting numbers as soon as you have successfully initiated the port request using the API (i.e., the porting number is deemed portable by Twilio, and the corresponding Port Orders instance resource’s status becomes “Received”). Please note that for Landline numbers, not configuring your porting numbers before the FOC (Firm Order Commitment) date and time, i.e., the date and time at which the number will port, will result in dropped traffic. For Wireless phone numbers, since porting will complete within 3 hours of signing the LOA, it is strongly recommended that you configure your porting numbers as soon as possible to avoid dropping traffic.

Pricing

Pricing for the Twilio Porting API

During the Developer Preview stage, there is no charge to port numbers using the Twilio Porting API. Once the API becomes generally available, we will begin charging for ports. We will provide Porting API users an update on pricing well before we begin charging for ports. In addition, we will update Twilio’s Pricing page accordingly.

Billing for numbers while porting is in progress using the Twilio Porting API

You will be billed the monthly charge for phone numbers as soon as we are able to schedule your port date, which is also known as the Firm Order Commitment (FOC) date. Thereafter, these phone numbers will be billed monthly on this same day of the month (i.e., the date the port date was scheduled, not the port date itself) or the last day of the month if that day of the month does not occur in a particular month (e.g., February 28 if Twilio was originally able to schedule your port on January 31).

Have more questions? Submit a request
Powered by Zendesk