Menu

Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

REST API: Hosted Number Orders

Hosted Numbers API is currently in Private Developer Preview

The Hosted Number Orders product allows an account to request for their phone numbers to be hosted on Twilio for SMS. Start the Hosted Number onboarding process by sending a POST to the list resource, which will create a new request to host a phone number, or move the Hosted Number Order along the onboarding process by updating the status of the Hosted Number Orders Instance Resource. Upon creation of a Hosted Number Order instance resource, a corresponding IncomingPhoneNumbers instance resource will also be created. Currently, Twilio only has the ability to onboard landline or toll-free US & Canada numbers that are not currently SMS enabled.

After the number's ownership has been verified, the user will then need to create a new Authorization Document that is electronically signed, giving Twilio permission to route SMS to and from Twilio's network. To see how to interact with the Authorization Documents resource, please visit the Public API reference.

Once the process is completed, users will be able to answer phone calls on their existing infrastructure and leverage the same number identity for two-way SMS on Twilio's platform.

Hosted Number Orders Instance Resource

The Hosted Number Orders instance resource represents a request to host a phone number's capability on Twilio's platform.

Resource URI

preview.twilio.com/HostedNumbers/HostedNumberOrders/{HostedNumberOrderSid}

Resource Properties

account_sid
sid<AC> Not PII

A 34 character string that uniquely identifies the account.

address_sid
sid<AD> Not PII

A 34 character string that uniquely identifies the Address resource that represents the address of the owner of this phone number.

call_delay
integer Not PII

A value between 0-30 specifying the number of seconds to delay initiating the ownership verification call.

capabilities
phone_number_capabilities Not PII

Set of booleans describing the capabilities hosted on Twilio's platform. SMS is currently only supported.

cc_emails
string[] PII MTL: 30 DAYS

A list of emails that LOA document for this HostedNumberOrder will be carbon copied to.

date_created
date_time<iso8601> Not PII

The date this resource was created, given as GMT RFC 2822 format.

date_updated
date_time<iso8601> Not PII

The date that this resource was updated, given as GMT RFC 2822 format.

email

Email of the owner of this phone number that is being hosted.

extension
string Not PII

A numerical extension to be used when making the ownership verification call.

failure_reason
string Not PII

A message that explains why a hosted_number_order went to status "action-required"

friendly_name

A 64 character string that is a human-readable text that describes this resource.

incoming_phone_number_sid
sid<PN> Not PII

A 34 character string that uniquely identifies the IncomingPhoneNumber resource that represents the phone number being hosted.

phone_number
phone_number<e164> Not PII

Phone number to be hosted. This must be in E.164 format, e.g., +16175551212

sid
sid<HR> Not PII

A 34 character string that uniquely identifies this HostedNumberOrder.

signing_document_sid
sid<PX> Not PII

A 34 character string that uniquely identifies the Authorization Document the user needs to sign.

status
enum:status Not PII

Status of this resource. It can hold one of the values: 1. Twilio Processing 2. Received, 3. Pending LOA, 4. Carrier Processing, 5. Completed, 6. Action Required, 7. Failed. See the HostedNumberOrders Status Values section for more information on each of these statuses.

unique_name

Provides a unique and addressable name to be assigned to this HostedNumberOrder, assigned by the developer, to be optionally used in addition to SID.

url
url Not PII

The URL of this HostedNumberOrder.

verification_attempts
integer Not PII

The number of attempts made to verify ownership of the phone number that is being hosted.

verification_call_sids
string[] Not PII

A list of 34 character strings that are unique identifiers for the calls placed as part of ownership verification.

verification_code
string Not PII

A verification code provided in the response for a user to enter when they pick up the phone call.

verification_document_sid
sid<RI> Not PII

A 34 character string that uniquely identifies the Identity Document resource that represents the document for verifying ownership of the number to be hosted.

verification_type
enum:verification_type Not PII

The type of ownership verification required to move the number to a verified state. The verification methods are phone-call or phone-bill.

HostedNumberOrders Status Values

Status Description
twilio-processing Twilio is processing your request and will either send to the failed status if the number is not eligible to be hosted, or move the number to received status.
received Twilio has received the HostedNumberOrder request and determined that the phone number in the request can be hosted on Twilio’s platform.
pending-verification Twilio is awaiting the Hosted Number Order to be verified by the end-user by picking up the phone and listening to a security token, or supplying a copy of the phone bill. The verification code is valid for 10 minutes. Subsequent calls to the API within the expiration time will send the same verification code. There can be a max of three verification attempts before the status changes to action_required.
verified Twilio has confirmed with a security token that the person answering the phone has verified their request for Hosted SMS
pending-loa LOA for the HostedNumberOrder has been generated, but the document has not yet been signed by the email recipient specified on the HostedNumberOrder.
carrier-processing LOA for the HostedNumberOrder has been signed, and the phone number has been submitted to Twilio’s underlying provider/carrier to enable the specified capabilities.
testing The phone number is undergoing capability testing for the capabilities specified in this order.
completed HostedNumberOrder onboarding has completed and the phone number is ready for use.
action-required HostedNumberOrder onboarding encountered a failure. An operations specialist will investigate the failure.
failed HostedNumberOrder was rejected by the current provider/carrier of the phone number. At this point, it is no longer possible to re-submit the same request.

HostedNumberOrders Status Callback

When a Hosted Number Order changes status, Twilio will make an asynchronous HTTP request to the StatusCallback URL if you provided one in your API request. By capturing this request, you can determine when the Hosted Number Order changes status.

The Hosted Number Orders status callback request passes the additional parameters listed in the table below:

Status Description
Status The new status of the Hosted Number Order
HostedNumberOrderSid The unique sid of the Hosted Number Order
PhoneNumber The +E.164 format of the Hosted Number Order

HTTP GET

Returns a single, existing Hosted Number Orders instance resource specified by the requested Hosted Number Orders instance resource SID.

Loading Code Sample...
      
      
      
      

      HTTP POST

      Tries to update a single, existing Hosted Number Orders instance resource’s properties and returns the updated resource representation if successful. The returned response is identical to that returned above when making a GET request.

      HostedNumberOrders Instance POST Optional Parameters

      CallDelay
      Optional
      post integer Not PII

      The number of seconds, between 0 and 60, to delay before initiating the verification call. Defaults to 0.

      CcEmails
      Optional
      post string[] Not PII

      Optional. A list of emails that LOA document for this HostedNumberOrder will be carbon copied to.

      Email
      Optional
      post string Not PII

      Email of the owner of this phone number that is being hosted.

      Extension
      Optional
      post string Not PII

      Digits to dial after connecting the verification call.

      FriendlyName
      Optional
      post string Not PII

      A 64 character string that is a human readable text that describes this resource.

      Status
      Optional
      post enum:status Not PII

      User can only post to pending-verification status to transition the HostedNumberOrder to initiate a verification call or verification of ownership with a copy of a phone bill.

      UniqueName
      Optional
      post string Not PII

      Provides a unique and addressable name to be assigned to this HostedNumberOrder, assigned by the developer, to be optionally used in addition to SID.

      VerificationCode
      Optional
      post string Not PII

      A verification code that is given to the user via a phone call to the phone number that is being hosted.

      VerificationDocumentSid
      Optional
      post sid<RI> Not PII

      Optional. The unique sid identifier of the Identity Document that represents the document for verifying ownership of the number to be hosted. Required when VerificationType is phone-bill.

      VerificationType
      Optional
      post enum:verification_type Not PII

      Optional. The method used for verifying ownership of the number to be hosted. One of phone-call (default) or phone-bill.

      Loading Code Sample...
          
          
          
          
          Response

          The returned response is identical to that returned when making a GET request.

          Loading Code Sample...
              
              
              
              
              Loading Code Sample...
                  
                  
                  
                  
                  Ownership Verification

                  Ownership Verification is a security measure to host the number with Twilio for SMS to ensure the authenticity of the request.

                  HTTP DELETE

                  Cancels the HostedNumberOrder, and consequently, deletes the corresponding IncomingPhoneNumber. Note that you can only issue the DELETE request when the HostedNumberOrder status is in received, pending-verification, verified or pending-loa. Beyond that, you can off-board the Twilio platform by issuing a DELETE request to the corresponding IncomingPhoneNumbers.

                  Loading Code Sample...
                      
                      
                      
                      
                      Response

                      A successful request will result in an HTTP 204 with no response body.

                      HostedNumberOrders List Resource

                      The HostedNumberOrders list resource represents the list of active and completed or failed Hosted Number Orders for the account.

                      Resource URI

                      preview.twilio.com/HostedNumbers/HostedNumberOrders/
                      

                      List Filters

                      FriendlyName
                      Optional
                      get string Not PII

                      A human readable description of this resource, up to 64 characters.

                      IncomingPhoneNumberSid
                      Optional
                      get sid<PN> Not PII

                      A 34 character string that uniquely identifies the IncomingPhoneNumber resource created by this HostedNumberOrder.

                      PhoneNumber
                      Optional
                      get phone_number<e164> Not PII

                      An E164 formatted phone number hosted by this HostedNumberOrder.

                      Status
                      Optional
                      get enum:status Not PII

                      The Status of this HostedNumberOrder. One of received, pending-verification, verified, pending-loa, carrier-processing, testing, completed, failed, or action-required.

                      UniqueName
                      Optional
                      get string Not PII

                      Provides a unique and addressable name to be assigned to this HostedNumberOrder, assigned by the developer, to be optionally used in addition to SID.

                      HTTP GET

                      Retrieves a list of all Hosted Number Orders for an account.

                      Loading Code Sample...
                          
                          
                          
                          
                          Response

                          List of the instance responses above.

                          HTTP POST

                          Creates a new Hosted Number Order for the specified capability. Currently, only SMS is a supported capability.

                          Parameters

                          PhoneNumber
                          Required
                          post phone_number<e164> Not PII

                          The number to host in +E.164 format

                          SmsCapability
                          Required
                          post boolean Not PII

                          Used to specify that the SMS capability will be hosted on Twilio's platform.

                          AccountSid
                          Optional
                          post sid<AC> Not PII

                          This defaults to the AccountSid of the authorization the user is using. This can be provided to specify a subaccount to add the HostedNumberOrder to.

                          AddressSid
                          Optional
                          post sid<AD> Not PII

                          Optional. A 34 character string that uniquely identifies the Address resource that represents the address of the owner of this phone number.

                          CcEmails
                          Optional
                          post string[] Not PII

                          Optional. A list of emails that the LOA document for this HostedNumberOrder will be carbon copied to.

                          Email
                          Optional
                          post string Not PII

                          Optional. Email of the owner of this phone number that is being hosted.

                          FriendlyName
                          Optional
                          post string Not PII

                          A 64 character string that is a human readable text that describes this resource.

                          SmsApplicationSid
                          Optional
                          post sid<AP> Not PII

                          Optional. The 34 character sid of the application Twilio should use to handle SMS messages sent to this number. If a SmsApplicationSid is present, Twilio will ignore all of the SMS urls above and use those set on the application.

                          SmsFallbackMethod
                          Optional
                          post http_method Not PII

                          The HTTP method that should be used to request the SmsFallbackUrl. Must be either GET or POST. This will be copied onto the IncomingPhoneNumber resource.

                          SmsFallbackUrl
                          Optional
                          post url Not PII

                          A URL that Twilio will request if an error occurs requesting or executing the TwiML defined by SmsUrl. This will be copied onto the IncomingPhoneNumber resource.

                          SmsMethod
                          Optional
                          post http_method Not PII

                          The HTTP method that should be used to request the SmsUrl. Must be either GET or POST. This will be copied onto the IncomingPhoneNumber resource.

                          SmsUrl
                          Optional
                          post url Not PII

                          The URL that Twilio should request when somebody sends an SMS to the phone number. This will be copied onto the IncomingPhoneNumber resource.

                          StatusCallbackMethod
                          Optional
                          post http_method Not PII

                          Optional. The Status Callback Method attached to the IncomingPhoneNumber resource.

                          StatusCallbackUrl
                          Optional
                          post url Not PII

                          Optional. The Status Callback URL attached to the IncomingPhoneNumber resource.

                          UniqueName
                          Optional
                          post string Not PII

                          Optional. Provides a unique and addressable name to be assigned to this HostedNumberOrder, assigned by the developer, to be optionally used in addition to SID.

                          VerificationDocumentSid
                          Optional
                          post sid<RI> Not PII

                          Optional. The unique sid identifier of the Identity Document that represents the document for verifying ownership of the number to be hosted. Required when VerificationType is phone-bill.

                          VerificationType
                          Optional
                          post enum:verification_type Not PII

                          Optional. The method used for verifying ownership of the number to be hosted. One of phone-call (default) or phone-bill.

                          Loading Code Sample...
                              
                              
                              
                              
                              Response

                              The returned response is identical to that returned when making a GET to a HostedNumberOrders instance response.

                              Need some help?

                              We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.

                              Loading Code Sample...