Port phone numbers using Twilio APIs
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.
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.
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 before using a phone number for Twilio services.
The high-level steps for creating a port-in request using the API are as follows:
- Check the portability for all phone numbers in the request.
- Upload utility bills showing proof of ownership for phone numbers to be ported.
- Create a new port-in request for the phone numbers.
- 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.
- The authorized representative of the number signs the LOA.
- Twilio submits the request to the losing carrier.
- Any port rejections are handled based on responses from the losing carrier.
- Twilio confirms the date for the port with the losing carrier.
- Twilio and the losing carrier complete the number port on the agreed date, and Twilio adds the phone numbers to your account.
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.
The port-in request status represents the overall status of the request, and updates as the request progresses through the port-in process.
| Status name | Description |
|---|---|
| In Review | The port-in request is currently being reviewed by Twilio. The request will progress to the next status automatically. |
| Waiting for Signature | The 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 Progress | The 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 Required | At least one number in the port-in request has been rejected by the losing carrier. To resolve the rejection:
|
| Completed | All phone numbers in the port-in request have been successfully ported to Twilio or canceled. There are no further actions to take. |
| Canceling | The 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. |
| Canceled | All 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. |
A port-in request allows you to port multiple phone numbers at once. Each phone number in the request has its own status.
| Status | Description |
|---|---|
| In Review | The port in phone number is currently being reviewed by Twilio. The phone number will progress to the next status automatically. |
| Waiting for Signature | The 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 Submitted | The phone number has been submitted to the losing carrier for port approval. The phone number will progress to the next status automatically. |
| Port Pending | The 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 Rejected | The phone number has been rejected by the losing carrier. To resolve the rejection:
|
| Completed | The phone number has been successfully ported to Twilio. |
| Canceling | The 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. |
| Canceled | The 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. |
To authenticate requests to the Twilio APIs, Twilio supports HTTP Basic authentication. 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.
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.