Hosted Number Orders - API Quickstart

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:

1
curl -XPOST https://preview.twilio.com/HostedNumbers/HostedNumberOrders/HR36f3f0c7c8d5d9210114fdcd8b6bcf19 \
2
  -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token' \
3
  -d "VerificationType=phone-call" \
4
  -d "Status=pending-verification"

1
{
2
    "status": "pending-verification",
3
    "date_updated": "2018-01-21T22:31:43Z",
4
    "verification_code": "310001",
5
    "incoming_phone_number_sid": "PN876a18805574a952ffb73907b24205f0",
6
    "failure_reason": "",
7
    "verification_attempts": 1,
8
    "verification_type": "phone-call",
9
    "capabilities": {
10
        "voice": false,
11
        "mms": false,
12
        "sms": true
13
    },
14
    "sid": "HR36f3f0c7c8d5d9210114fdcd8b6bcf19",
15
    "phone_number": "+18444905863",
16
    "call_delay": 0,
17
    "signing_document_sid": null,
18
    "verification_document_sid": "RI2ad9942e6daa7d8e87a154f6f675f3f8",
19
    "verification_call_sids": [
20
        "CA83f7aa47a1760188e892fe8c2ba86749"
21
    ],
22
    "extension": null,
23
    "url": "https://preview.twilio.com/HostedNumbers/HostedNumberOrders/HR36f3f0c7c8d5d9210114fdcd8b6bcf19",
24
    "friendly_name": "My_Sms_Hosted_Number_Order",
25
    "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
26
    "date_created": "2018-01-21T21:40:55Z"
27
}

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

1
$ curl -X POST https://preview.twilio.com/HostedNumbers/AuthorizationDocuments \
2
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token' \
3
    -d "HostedNumberOrderSids=HR7e42fbbfb47d17baaae45d94c34ec4c3" \
4
    -d "HostedNumberOrderSids=HR18b3fc4bb26c368ceff1587ec26bf892" \
5
    -d "HostedNumberOrderSids=HR842cc9ce52ce257da378c2972f88fecc" \
6
    -d "HostedNumberOrderSids=HRc401d83d7d66901d2b65a4700457272d" \
7
    -d "AddressSid=AD1e20d20a7772e157c8ddbaba36aefef0" \
8
    -d "Email=owner@example.com" \
9
    -d "CcEmails=person1@example.com&CcEmails=person2@example.com"

1
{
2
    "status": "signing",
3
    "date_updated": "2017-10-16T23:54:59Z",
4
    "cc_emails": [
5
        "person1@example.com",
6
        "person2@example.com"
7
    ],
8
    "url": "https://preview.twilio.com/HostedNumbers/AuthorizationDocuments/PX5b7889b420ec6bca465c068f5bc2b67e",
9
    "address_sid": "AD1e20d20a7772e157c8ddbaba36aefef0",
10
    "sid": "PX5b7889b420ec6bca465c068f5bc2b67e",
11
    "date_created": "2017-10-16T23:54:58Z",
12
    "email": "owner@example.com"
13
}

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.

1
$ curl -XPOST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/IncomingPhoneNumbers/PN9c45b3eb69d07536c60a621891420bfc.json \
2
-d "SmsUrl=https://demo.twilio.com/welcome/sms/reply/" \
3
-d "FriendlyName=something new"
4
-u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token'

1
{
2
    "sid": "PN9c45b3eb69d07536c60a621891420bfc",
3
    "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
4
    "friendly_name": "something new",
5
    "phone_number": "+18444725974",
6
    "voice_url": null,
7
    "voice_method": null,
8
    "voice_fallback_url": null,
9
    "voice_fallback_method": null,
10
    "voice_caller_id_lookup": false,
11
    "date_created": "Wed, 25 Oct 2017 22:54:16 +0000",
12
    "date_updated": "Wed, 25 Oct 2017 23:43:35 +0000",
13
    "sms_url": "https://demo.twilio.com/welcome/sms/reply/",
14
    "sms_method": null,
15
    "sms_fallback_url": null,
16
    "sms_fallback_method": null,
17
    "address_requirements": "none",
18
    "beta": false,
19
    "capabilities": {
20
        "voice": false,
21
        "sms": true,
22
        "mms": false,
23
        "fax": false
24
    },
25
    "voice_receive_mode": "voice",
26
    "status_callback": null,
27
    "status_callback_method": null,
28
    "api_version": "2010-04-01",
29
    "voice_application_sid": null,
30
    "sms_application_sid": null,
31
    "origin": "hosted",
32
    "trunk_sid": null,
33
    "emergency_status": "Inactive",
34
    "emergency_address_sid": null,
35
    "address_sid": null,
36
    "identity_sid": null,
37
    "uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/IncomingPhoneNumbers/PN9c45b3eb69d07536c60a621891420bfc.json"
38
}

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.

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.