Skip to contentSkip to navigationSkip to topbar
On this page

Port phone numbers using Twilio APIs


(new)

Public Beta

The Porting API is in Public Beta. The information in this document could change. We might add or update features before the product becomes Generally Available. Beta products don't have a Service Level Agreement (SLA). Learn more about beta product support(link takes you to an external page).

If you'd like to keep your own phone number and move its messaging and voice capabilities to Twilio, you can port your number to Twilio. In this case, Twilio will be the new carrier of the phone number.

This guide describes a step-by-step walkthrough of the automated porting process using the Porting API. With the API, you can create a port-in request for US non-toll-free phone numbers (up to 1,000 numbers per request).

Check the portability status of the phone numbers using the Portability API (in Public Beta) prior to submitting a port-in request for these numbers.

(information)

Info

The public beta version of the Porting API doesn't support email notifications. You can configure webhooks to receive updates about your port-in request.

With this port-in process, you won't need to manually create a PDF document with a Letter of Authorization (LOA) to port a number. Twilio generates an electronic LOA with the information you provide in the port-in request and sends it to the authorized representative's email for a digital signature.

Once a port-in request is complete, you need to fulfill all messaging and voice compliance requirements(link takes you to an external page) before using a phone number for Twilio services.


Phone number port-in process

phone-number-port-in-process page anchor
Port In Process Swimlanes.

The high-level steps for creating a port-in request using the API are as follows:

  1. Check the portability for all phone numbers in the request.
  2. Upload utility bills showing proof of ownership for phone numbers to be ported.
  3. Create a new port-in request for the phone numbers.
  4. Twilio creates an LOA with all portable numbers from the port-in request and sends it to the authorized representative's email (added in the API) for digital signature.
  5. The authorized representative of the number signs the LOA.
  6. Twilio submits the request to the losing carrier.
  7. Any port rejections are handled based on responses from the losing carrier.
  8. Twilio confirms the date for the port with the losing carrier.
  9. Twilio and the losing carrier complete the number port on the agreed date, and Twilio adds the phone numbers to your account.
(information)

About webhooks

See Porting webhooks for more information about what notifications you can subscribe to as part of the port-in process.


The following tables list possible statuses for your port-in request and port in phone numbers.

port-in request statuses

port-in-request-statuses page anchor

The port-in request status represents the overall status of the request, and updates as the request progresses through the port-in process.

Status nameDescription
In ReviewThe port-in request is currently being reviewed by Twilio. The request will progress to the next status automatically.
Waiting for SignatureThe port-in request has been accepted by Twilio and an LOA has been sent to the authorized representative's email.
The authorized representative has 30 days to sign this document or the port-in request will be canceled automatically.
In ProgressThe port-in request has been submitted to the losing carrier and if accepted will get ported on the agreed date. The request will progress to the next status automatically.
It is only possible to make changes to the target port date of the port-in request at this point.
Action RequiredAt least one number in the port-in request has been rejected by the losing carrier. To resolve the rejection:
  1. Review the rejection reason code.
  2. Do one of the following:
    • Cancel the rejected phone number from the port-in request.
    • Cancel the entire port-in request.
  3. Resubmit the port-in request with the corrected information.
All phone numbers that were not rejected will continue with the port-in process unless the port-in request is canceled or the phone number is canceled.
CompletedAll phone numbers in the port-in request have been successfully ported to Twilio or canceled. There are no further actions to take.
CancelingThe port-in request is in the cancellation process. Some scenarios require you to reach out to the losing carrier or other partners to ensure the cancellation for all phone numbers in the request.
CanceledAll phone numbers in the port-in request have been canceled. You can choose to retry this request by submitting it again. Be sure to review the details of this request to determine why it was canceled.

port-in request status transition

port-in-request-status-transition page anchor
port-in request Status Transition.

Port in phone number statuses

port-in-phone-number-statuses page anchor

A port-in request allows you to port multiple phone numbers at once. Each phone number in the request has its own status.

StatusDescription
In ReviewThe port in phone number is currently being reviewed by Twilio. The phone number will progress to the next status automatically.
Waiting for SignatureThe LOA for the port-in request is waiting for a signature from the authorized representative. The phone number will progress to the next status as soon as the LOA is signed.
Port SubmittedThe phone number has been submitted to the losing carrier for port approval. The phone number will progress to the next status automatically.
Port PendingThe phone number port has been accepted by the losing carrier. At this point there should be a date assigned to the port-in request for this phone number. The phone number will progress to the next status automatically on the port in date.
Port RejectedThe phone number has been rejected by the losing carrier. To resolve the rejection:
  1. Review the rejection reason code.
  2. Do one of the following:
    • Cancel the rejected phone number from the port-in request.
    • Cancel the entire port-in request.
  3. Resubmit the port-in request with the corrected information.
CompletedThe phone number has been successfully ported to Twilio.
CancelingThe phone number is pending cancellation. Some scenarios require you to reach out to the losing carrier or other partners to ensure cancellation. This is not a terminal status.
CanceledThe phone number was canceled during the port-in process. This can happen automatically if the number is not portable or it can be done via the API.

Port in phone numbers status transitions

port-in-phone-numbers-status-transitions page anchor
Port In Phone numbers Status Transitions.

To authenticate requests to the Twilio APIs, Twilio supports HTTP Basic authentication(link takes you to an external page). Use your API key as the username and your API key secret as the password. You can create an API key either in the Twilio Console or using the API.

Note: Twilio recommends using API keys for authentication in production apps. For local testing, you can use your Account SID as the username and your Auth token as the password. You can find your Account SID and Auth Token in the Twilio Console(link takes you to an external page).

Learn more about Twilio API authentication.


When you create a port-in request and provide a notification email, Twilio creates a Zendesk ticket for your request. This ticket tracks your port-in request status.

To create the ticket, add the email addresses as values of the NotificationEmails parameter. All included email addresses receive notifications about the port-in request status.

To communicate with Twilio about your request, you can use the ticket or reply to the email to add a new comment.