Port In API (Public Beta)
Public Beta
The Port In API is currently available as a Public Beta product and the information contained in this document is subject to change.
Public Beta products are not covered by a Twilio SLA.
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 Twilio's Port In Request API. With this 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 beta of this API does not support email notifications. You will need to 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. An electronic LOA will be generated with the information provided in the Port in Request and sent to the authorized representative's email, so it can be signed digitally. Once a Port in Request is complete, you need to fulfill all messaging and voice compliance requirements before starting using a phone number for Twilio services.
The high-level steps for creating a port in request via API are:
- Check the portability for all phone numbers in the request.
- Upload a Utility Bill(s) showing proof of ownership for phone numbers to be ported.
- Create a new port in request for the phone numbers.
- A Letter of Authorization (LOA) will be created with all portable numbers from the port in request and it will be sent to the authorized representative's email (added in the API) for 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, at which point the phone numbers will be added to your account's inventory.
About webhooks
See the Webhook APIs for more information about what notifications you can subscribe to as part of the Port In process.
See below for the list of possible statuses your Port In Request and Port In Phone Number can have.
The Port In Request status represents the overall status of the request, and it will be updated 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 a Letter of Authorization (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 will have its own status. The statuses for a phone number in a port in request are:
| 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, a Zendesk ticket is created 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 email addresses added 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. Either choice adds a new comment in the Zendesk ticket.