Twilio Provisioning

Twilio’s Hosted Numbers API allows you to provision (text-enable) an existing landline phone number, similar to Zipwhip’s Provisioning API. The Twilio 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 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.

Create new Hosted Number order

The first step in provisioning (text-enabling) an existing landline voice number is to create a new Hosted Number Order request. 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.

Parameters

curl -X POST https://preview.twilio.com/HostedNumbers/HostedNumberOrders \
  -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \
  -d "PhoneNumber=+18444905863" \
  -d "SmsCapability=true"  \
  -d "FriendlyName=MyHostedNumberSmsOrder" \
  -d "StatusCallbackUrl=http://example.com/callback" \
  -d "StatusCallbackMethod=POST"

Check status of a Hosted Number order

When a Hosted Number request is submitted, it will progress through a series of statuses:

You can set up a StatusCallbackUrl to receive webhook notifications when the status changes (see example above), or you can fetch the status with the following API call.

Parameters

curl -X GET 'https://preview.twilio.com/HostedNumbers/HostedNumberOrders/$HOSTED_NUMBER_SID' \
  -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Verify ownership with an automated phone call

Once a number has passed the pre-validation check and has progressed to the received status, the next phase will be to move the number to pending-verification to place an automated phone call and ask for a security token. This verification step ensures that all requests are from legitimate end-users to ensure the authenticity of ownership.

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.

Send the following API request to trigger the verfication phone call. Parameters

curl -X POST https://preview.twilio.com/HostedNumbers/HostedNumberOrders/$HOSTED_NUMBER_SID \
  -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN
  -d "VerificationType=phone-call" \
  -d "Status=pending-verification"

Note: When initiating the verification phone call via the API or Console, a 6-digit verification_code will be returned, which must be entered by the end user who answers the phone.

Create and sign new LOA

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.

Parameters

$ curl -X POST https://preview.twilio.com/HostedNumbers/AuthorizationDocuments \
  -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN
  -d "HostedNumberOrderSids=$HOSTED_NUMBER_SID1" \
  -d "HostedNumberOrderSids=$HOSTED_NUMBER_SID2" \
  -d "HostedNumberOrderSids=$HOSTED_NUMBER_SID3" \
  -d "Email=owner@example.com" \
  -d "CcEmails=person1@example.com&CcEmails=person2@example.com"

Preconfigure 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.

Cancel a pending Hosted Number request

You can cancel a pending Hosted Number requst by issuing a DELETE request when the HostedNumberOrder status is in received, pending-verification, verified or pending-loa. If the Hosted Number Order is completed, you can off-board the Twilio platform by issuing a DELETE request to the corresponding IncomingPhoneNumbers API (see Release a Hosted Number below). If the Hosted Number Order is in a failed state due to either current SMS enablement or idle timeout, a new Hosted Number Order can be created. Please note that the Hosted Number Order will keep failing if SMS enablement is not removed from the number.

Parameters

$ curl -DELETE https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/IncomingPhoneNumbers/$PHONE_NUMBER_SID.json \
  -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Release a Hosted Number

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.

Parameters

$ curl -DELETE https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/IncomingPhoneNumbers/$PHONE_NUMBER_SID.json \
  -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN