Hosted Number Orders - API Quickstart

The Twilio Hosted Numbers API makes it easy for customers to enable Twilio’s Programmable SMS with their existing US & Canada voice landline and toll-free numbers. The voice traffic will remain with the current voice provider, while Twilio’s SMS routing profile will be applied for inbound and outbound SMS traffic on Twilio. As well as providing the capability to send outbound voice calls from the same number.

The Hosted Number Orders API provides a way to SMS enable a number and host on Twilio without having to purchase or port a number to Twilio. The API enables the ability to host a number using a structured API that provides a low-touch and secure workflow for you and your customers.

The Hosted Number Orders API is in Developer Preview and works for US & Canada landline and toll-free numbers that are not currently enabled for messaging. Hosted Numbers costs $0.50 a month. Request early access to the Hosted Numbers SMS Enablement developer preview to get your account access.

Quick Start Tutorial

The Hosted Number Orders API allows you to: submit an SMS enablement request, get immediate hosting eligibility validation of the number, track Hosted Number Order status transitions, and automate configuring a Hosted Number before the number is active on Twilio's Super Network.

Suppose you wanted to SMS enable your number +18444905863 and host on Twilio. Your first step would be to create a new Hosted Number Order with the phone number in +E.164 format.

Twilio will check if the number meets the criteria for SMS enablement and, if valid, will create the Hosted Number Order and return a JSON resource of the instance resource:

Ownership Verification

Once a number has passed the pre-validation check and is moved to the received status, the next phase will be to move the number to pending-verification where Twilio will call the number and ask for a security token. The phone call will prompt for the token four times before the call hangs up, and up to three verifications can be performed before the number moves to action-required, when a Twilio admin must be involved. If in `action-required` for more than 7 days, the Hosted Number Order will be marked as `failed` and a new Hosted Number Order will need to be created to go through the process again.

Twilio must verify that the end-user answering the phone call is the one requesting the text provisioning on the phone number. This verification step ensures that all requests are from legitimate end-users to ensure the authenticity of ownership.

To navigate pass IVRs, you can include an Extension parameter along with a `w`. Each ‘w’ character tells Twilio to wait 0.5 seconds instead of playing a digit. This lets you adjust the timing of when the digits begin playing to suit the phone system you are dialing.

For example, the extension “wwww2wwwwww5wwwwww9′′ waits two seconds before sending the digit 2, followed by a three-second wait before sending the 5, and finally another three-second wait before sending a 9. You will need to tune the extension to the IVR system to be able to programmatically verify numbers behind IVR menus.

Create new LOA and Sign

Carriers require a signed Letter of Authorization (LOA) by the authorized end user of the phone number to enable SMS capabilities. Twilio will generate this document with the address information and phone numbers you passed, to be sent for your or your customer's review and signature. To trigger the LOA email, issue a POST request to the Hosted Numbers Authorization Documents list resource with the required information. The new Authorization Document will be moved to `signing`, along with the Hosted Number Orders attached to the Authorization Document moving to `pending-loa`.

A Document SID is provided to you in the response. By performing a GET on the HostedNumberOrders endpoint, you can keep up-to-date status to track the Hosted Number Order during the signature process with the Hosted Number Order SID.

Configure Hosted Number

You don’t have to wait for the Hosted Number Order to complete in order to configure your number with an incoming SMS webhook. The Incoming Phone Numbers API provides a programmatic way to pre-configure the number with the Incoming Phone Number SID.

Remove Hosted Number from your inventory and remove Twilio's SMS Routing Profile

When you no longer want to host your phone number for SMS on Twilio, you can send a DELETE request to the phone number instance on the Incoming Phone Numbers resource. The Hosted Number takes 3 days before fully retiring from our system. If you accidentally released your Hosted Number, please write to hostedsms@twilio.com to request restoration. After 3 days, Twilio will unregister the number for SMS, and the number will turn into a landline or Toll-Free with no SMS routing.

Thanks for reading! Sign up for early access here.