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

POST /HostedNumbers/HostedNumberOrders

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

  • SmsCapability boolean Required

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

  • 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 64 character string that is a human readable text that describes this resource.

  • UniqueName string

    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.

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

  • 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}$.

  • AddressSid string

    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

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

  • VerificationType string

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

    Values are phone-call or phone-bill.

  • VerificationDocumentSid string

    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.

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

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 64 character string that is a human-readable text that describes this resource.

    • unique_name string | null

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

    • verification_attempts integer

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

      Default value is 0.

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

    • verification_type string

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

      Values are phone-call or phone-bill.

    • verification_document_sid string | null

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

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

    • extension string | null

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

    • call_delay integer

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

      Default value is 0.

    • verification_code string | null

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

    • verification_call_sids array[string] | null

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

POST /HostedNumbers/HostedNumberOrders
curl \
 --request POST 'https://preview.twilio.com/HostedNumbers/HostedNumberOrders' \
 --user "username:password" \
 --header "Content-Type: application/x-www-form-urlencoded" \
 --data 'Email=test%40twilio.com&AddressSid=AD11111111111111111111111111111111&PhoneNumber=%2B14153608311&SmsCapability=true'
{"Email"=>"test@twilio.com", "AddressSid"=>"AD11111111111111111111111111111111", "PhoneNumber"=>"+14153608311", "SmsCapability"=>true}
{"PhoneNumber"=>"+14153608311", "SmsCapability"=>true}
{"PhoneNumber"=>"+14153608311", "SmsCapability"=>true, "VerificationType"=>"phone-bill", "VerificationDocumentSid"=>"RIaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}
{
  "sid": "HRaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "url": "https://preview.twilio.com/HostedNumbers/HostedNumberOrders/HRaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "email": "test@twilio.com",
  "status": "received",
  "cc_emails": [],
  "extension": null,
  "call_delay": 0,
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "address_sid": "AD11111111111111111111111111111111",
  "unique_name": null,
  "capabilities": {
    "sms": true,
    "voice": false
  },
  "date_created": "2017-03-28T20:06:39Z",
  "date_updated": "2017-03-28T20:06:39Z",
  "phone_number": "+14153608311",
  "friendly_name": null,
  "failure_reason": "",
  "verification_code": null,
  "verification_type": "phone-call",
  "signing_document_sid": null,
  "verification_attempts": 0,
  "verification_call_sids": null,
  "incoming_phone_number_sid": "PN11111111111111111111111111111111",
  "verification_document_sid": null
}
{
  "sid": "HRaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "url": "https://preview.twilio.com/HostedNumbers/HostedNumberOrders/HRaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "email": null,
  "status": "received",
  "cc_emails": [],
  "extension": null,
  "call_delay": 0,
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "address_sid": null,
  "unique_name": null,
  "capabilities": {
    "sms": true,
    "voice": false
  },
  "date_created": "2017-03-28T20:06:39Z",
  "date_updated": "2017-03-28T20:06:39Z",
  "phone_number": "+14153608311",
  "friendly_name": null,
  "failure_reason": "",
  "verification_code": null,
  "verification_type": "phone-call",
  "signing_document_sid": null,
  "verification_attempts": 0,
  "verification_call_sids": null,
  "incoming_phone_number_sid": "PN11111111111111111111111111111111",
  "verification_document_sid": null
}
{
  "sid": "HRaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "url": "https://preview.twilio.com/HostedNumbers/HostedNumberOrders/HRaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "email": null,
  "status": "received",
  "cc_emails": [],
  "extension": null,
  "call_delay": 0,
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "address_sid": null,
  "unique_name": null,
  "capabilities": {
    "sms": true,
    "voice": false
  },
  "date_created": "2017-03-28T20:06:39Z",
  "date_updated": "2017-03-28T20:06:39Z",
  "phone_number": "+14153608311",
  "friendly_name": null,
  "failure_reason": "",
  "verification_code": null,
  "verification_type": "phone-bill",
  "signing_document_sid": null,
  "verification_attempts": 0,
  "verification_call_sids": null,
  "incoming_phone_number_sid": "PN11111111111111111111111111111111",
  "verification_document_sid": "RIaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}