Level up your Twilio API skills in TwilioQuest, an educational game for Mac, Windows, and Linux. Download Now

Menu

Expand
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?

Hosted Number Order Resource

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.

HostedNumberOrder properties

Names in PHP format
sid
sid<HR> Not PII

A 34 character string that uniquely identifies this HostedNumberOrder.

accountSid
sid<AC> Not PII

A 34 character string that uniquely identifies the account.

incomingPhoneNumberSid
sid<PN> Not PII

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

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

signingDocumentSid
sid<PX> Not PII

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

phoneNumber
phone_number<e164> Not PII

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

capabilities
phone_number_capabilities Not PII

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

friendlyName

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

uniqueName

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

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.

failureReason
string Not PII

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

dateCreated
date_time<iso8601> Not PII

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

dateUpdated
date_time<iso8601> Not PII

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

verificationAttempts
integer Not PII

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

email

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

ccEmails
string[] PII MTL: 30 DAYS

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

url
url Not PII

The URL of this HostedNumberOrder.

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

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

extension
string Not PII

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

callDelay
integer Not PII

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

verificationCode
string Not PII

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

verificationCallSids
string[] Not PII

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

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 The Hosted Number Order failed because the number is currently SMS enabled or has been idle for more than 30 days. At this point, it is no longer possible to re-submit the request for the failed Hosted Number Order. However, a new Hosted Number Order can be created for the same phone number once SMS registration has been deactivated on the phone number or the previous Hosted Number Order has failed due to being idle.

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

Create a HostedNumberOrder resource

post
https://preview.twilio.com/HostedNumbers/HostedNumberOrders

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

Parameters
Names in None format
account_sid
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.

friendly_name
Optional
post string PII MTL: 30 DAYS

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

unique_name
Optional
post string PII MTL: 30 DAYS

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.

cc_emails
Optional
post string[] PII MTL: 30 DAYS

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

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

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

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

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

status_callback_url
Optional
post url Not PII

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

status_callback_method
Optional
post http_method Not PII

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

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

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

email
Optional
post string PII MTL: 30 DAYS

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

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

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

phone_number
Required
post phone_number<e164> Not PII

The number to host in +E.164 format

sms_capability
Required
post boolean Not PII

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

Example 1
        
        
        
        

        Fetch a HostedNumberOrder resource

        get
        https://preview.twilio.com/HostedNumbers/HostedNumberOrders/{Sid}

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

        Parameters
        Names in None format
        sid
        Required
        get sid<HR> Not PII

        A 34 character string that uniquely identifies this HostedNumberOrder.

        Example
              
              
              
              

              Read multiple HostedNumberOrder resources

              get
              https://preview.twilio.com/HostedNumbers/HostedNumberOrders
              Parameters
              Names in None format
              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.

              phone_number
              Optional
              get phone_number<e164> Not PII

              An E164 formatted phone number hosted by this HostedNumberOrder.

              incoming_phone_number_sid
              Optional
              get sid<PN> Not PII

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

              friendly_name
              Optional
              get string PII MTL: 30 DAYS

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

              unique_name
              Optional
              get string PII MTL: 30 DAYS

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

              Example
                    
                    
                    
                    

                    Update a HostedNumberOrder resource

                    post
                    https://preview.twilio.com/HostedNumbers/HostedNumberOrders/{Sid}

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

                    Parameters
                    Names in None format
                    friendly_name
                    Optional
                    post string PII MTL: 30 DAYS

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

                    unique_name
                    Optional
                    post string PII MTL: 30 DAYS

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

                    email
                    Optional
                    post string PII MTL: 30 DAYS

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

                    cc_emails
                    Optional
                    post string[] PII MTL: 30 DAYS

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

                    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.

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

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

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

                    extension
                    Optional
                    post string Not PII

                    Digits to dial after connecting the verification call.

                    call_delay
                    Optional
                    post integer Not PII

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

                    Example 1
                          
                          
                          
                          
                          Example 2
                                
                                
                                
                                
                                Example 3
                                      
                                      
                                      
                                      

                                      Ownership Verification

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

                                      Delete a HostedNumberOrder resource

                                      delete
                                      https://preview.twilio.com/HostedNumbers/HostedNumberOrders/{Sid}

                                      Cancels the Hosted Number Order, and consequently, deletes the corresponding Incoming Phone Number.

                                      You can only issue the 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. 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
                                      Names in None format
                                      sid
                                      Required
                                      delete sid<HR> Not PII

                                      A 34 character string that uniquely identifies this HostedNumberOrder.

                                      Example
                                            
                                            
                                            
                                            
                                            Rate this page:

                                            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.