Host a phone number's capability on Twilio's platform.

POST /v2/HostedNumber/Orders
Account sid auth token

Host a phone number's capability on Twilio's platform.

application/x-www-form-urlencoded

Body

  • PhoneNumber string(phone-number) Required

    The number to host in +E.164 format

  • ContactPhoneNumber string(phone-number) Required

    The contact phone number of the person authorized to sign the Authorization Document.

  • AddressSid string Required

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

    Minimum length is 34, maximum length is 34. Format should match the following pattern: ^AD[0-9a-fA-F]{32}$.

  • Email string Required

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

  • AccountSid string

    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.

    Minimum length is 34, maximum length is 34. Format should match the following pattern: ^AC[0-9a-fA-F]{32}$.

  • FriendlyName string

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

  • CcEmails array[string]

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

  • SmsUrl string(uri)

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

  • SmsMethod string(http-method)

    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.

    Values are GET or POST.

  • SmsFallbackUrl string(uri)

    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.

  • SmsCapability boolean

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

  • SmsFallbackMethod string(http-method)

    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.

    Values are GET or POST.

  • StatusCallbackUrl string(uri)

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

  • StatusCallbackMethod string(http-method)

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

    Values are GET or POST.

  • SmsApplicationSid string

    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.

    Minimum length is 34, maximum length is 34. Format should match the following pattern: ^AP[0-9a-fA-F]{32}$.

  • ContactTitle string

    The title of the person authorized to sign the Authorization Document for this phone number.

Responses

  • 201 application/json

    Created

    Hide headers attributes Show headers attributes
    • Access-Control-Allow-Origin string

      Specify the origin(s) allowed to access the resource

    • Access-Control-Allow-Methods string

      Specify the HTTP methods allowed when accessing the resource

    • Access-Control-Allow-Headers string

      Specify the headers allowed when accessing the resource

    • Access-Control-Allow-Credentials boolean

      Indicates whether the browser should include credentials

    • Access-Control-Expose-Headers string

      Headers exposed to the client

    Hide response attributes Show response attributes object
    • sid string | null

      A 34 character string that uniquely identifies this HostedNumberOrder.

      Minimum length is 34, maximum length is 34. Format should match the following pattern: ^HR[0-9a-fA-F]{32}$.

    • account_sid string | null

      A 34 character string that uniquely identifies the account.

      Minimum length is 34, maximum length is 34. Format should match the following pattern: ^AC[0-9a-fA-F]{32}$.

    • incoming_phone_number_sid string | null

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

      Minimum length is 34, maximum length is 34. Format should match the following pattern: ^PN[0-9a-fA-F]{32}$.

    • address_sid string | null

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

      Minimum length is 34, maximum length is 34. Format should match the following pattern: ^AD[0-9a-fA-F]{32}$.

    • signing_document_sid string | null

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

      Minimum length is 34, maximum length is 34. Format should match the following pattern: ^PX[0-9a-fA-F]{32}$.

    • phone_number string(phone-number) | null

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

    • capabilities object(phone-number-capabilities) | null

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

      Hide capabilities attributes Show capabilities attributes object(phone-number-capabilities) | null
      • mms boolean
      • sms boolean
      • voice boolean
      • fax boolean
    • friendly_name string | null

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

    • status string

      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.

      Values are twilio-processing, received, pending-verification, verified, pending-loa, carrier-processing, testing, completed, failed, or action-required.

    • failure_reason string | null

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

    • date_created string(date-time) | null

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

    • date_updated string(date-time) | null

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

    • email string | null

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

    • cc_emails array[string] | null

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

    • url string(uri) | null

      The URL of this HostedNumberOrder.

    • contact_title string | null

      The title of the person authorized to sign the Authorization Document for this phone number.

    • contact_phone_number string(phone-number) | null

      The contact phone number of the person authorized to sign the Authorization Document.

    • bulk_hosting_request_sid string | null

      A 34 character string that uniquely identifies the bulk hosting request associated with this HostedNumberOrder.

      Minimum length is 34, maximum length is 34. Format should match the following pattern: ^BH[0-9a-fA-F]{32}$.

    • next_step string | null

      The next step you need to take to complete the hosted number order and request it successfully.

    • verification_attempts integer

      The number of attempts made to verify ownership via a call for the hosted phone number.

      Default value is 0.

    • verification_call_sids array[string] | null

      The Call SIDs that identify the calls placed to verify ownership.

    • verification_call_delay integer

      The number of seconds to wait before initiating the ownership verification call. Can be a value between 0 and 60, inclusive.

      Default value is 0.

    • verification_call_extension string | null

      The numerical extension to dial when making the ownership verification call.

    • verification_code string | null

      The digits the user must pass in the ownership verification call.

    • verification_type string

      The method used to verify ownership of the number to be hosted. Can be: phone-call or phone-bill and the default is phone-call.

      Value is phone-call.
POST /v2/HostedNumber/Orders 
curl \
 --request POST 'https://numbers.twilio.com/v2/HostedNumber/Orders' \
 --user "username:password" \
 --header "Content-Type: application/x-www-form-urlencoded" \
 --data 'Email=test%40twilio.com&AddressSid=AD11111111111111111111111111111111&PhoneNumber=%2B14153608311&ContactTitle=contact_title_test&ContactPhoneNumber=%2B12344444444'
Request examples 
{"Email"=>"test@twilio.com", "AddressSid"=>"AD11111111111111111111111111111111", "PhoneNumber"=>"+14153608311", "ContactTitle"=>"contact_title_test", "ContactPhoneNumber"=>"+12344444444"}
{"Email"=>"test@twilio.com", "AddressSid"=>"AD11111111111111111111111111111111", "PhoneNumber"=>"+14153608311", "ContactPhoneNumber"=>"+12344444444"}
Response examples (201) 
{
  "sid": "HRaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "url": "https://numbers.twilio.com/v2/HostedNumber/Orders/HRaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "email": "test@twilio.com",
  "status": "received",
  "cc_emails": [],
  "next_step": "next_step",
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "address_sid": "AD11111111111111111111111111111111",
  "capabilities": {
    "sms": true,
    "voice": false
  },
  "date_created": "2017-03-28T20:06:39Z",
  "date_updated": "2017-03-28T20:06:39Z",
  "phone_number": "+14153608311",
  "contact_title": "contact_title_test",
  "friendly_name": null,
  "failure_reason": "",
  "verification_code": null,
  "verification_type": "phone-call",
  "contact_phone_number": "+12344444444",
  "signing_document_sid": null,
  "verification_attempts": 0,
  "verification_call_sids": [],
  "verification_call_delay": 0,
  "bulk_hosting_request_sid": "BH11111111111111111111111111111111",
  "incoming_phone_number_sid": "PN11111111111111111111111111111111",
  "verification_call_extension": null
}
{
  "sid": "HRaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "url": "https://numbers.twilio.com/v2/HostedNumber/Orders/HRaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "email": "test@twilio.com",
  "status": "received",
  "cc_emails": [],
  "next_step": "next_step",
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "address_sid": "AD11111111111111111111111111111111",
  "capabilities": {
    "sms": true,
    "voice": false
  },
  "date_created": "2017-03-28T20:06:39Z",
  "date_updated": "2017-03-28T20:06:39Z",
  "phone_number": "+14153608311",
  "contact_title": null,
  "friendly_name": null,
  "failure_reason": "",
  "verification_code": null,
  "verification_type": "phone-call",
  "contact_phone_number": "+12344444444",
  "signing_document_sid": null,
  "verification_attempts": 0,
  "verification_call_sids": [],
  "verification_call_delay": 0,
  "bulk_hosting_request_sid": "BH11111111111111111111111111111111",
  "incoming_phone_number_sid": "PN11111111111111111111111111111111",
  "verification_call_extension": null
}