Hosting Numbers

This walks through how to programmatically import Phone Numbers to your account for use with Bandwidth's Messaging Products.

Line Options feature management is NOT available for Phone numbers that have been imported for use with Hosted Messaging.

Polling vs. Webhooks

Hosted Messaging Orders in the Bandwidth Dashboard are asynchronous when creating an "order". The orders are then processed and the order status is updated asynchronously. Bandwidth recommends configuring your account with a subscription instead of polling the order resource for <OrderStatus>.

Order processing times can vary and are not guaranteed, so bandwidth does not recommend setting a timeout on waiting for an order to show either COMPLETE or FAILED status, but instead relying on a webhook from an orders subscription.

Check for Importability

The importTnChecker endpoint validates whether or not Bandwidth can host the number for messaging. Please note that a valid response from this endpoint does not ensure that the messaging traffic will be routed to Bandwidth—there are many factors with the other carriers that could cause them to withhold messaging ownership rights on a number.

Request URL

POST https://dashboard.bandwidth.com/api/accounts/{accountId}/importTnChecker

Examples

Request

POST https://dashboard.bandwidth.com/api/accounts/{accountId}/importTnChecker HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

<ImportTnCheckerPayload>
    <TelephoneNumbers>
        <TelephoneNumber>3032281000</TelephoneNumber>
        <TelephoneNumber>4109235436</TelephoneNumber>
        <TelephoneNumber>4104685864</TelephoneNumber>
    </TelephoneNumbers>
    <SiteId>486</SiteId>
    <SipPeerId>500025</SipPeerId>
</ImportTnCheckerPayload>

Response

HTTP 200 OK
Content-Type: application/xml; charset=utf-8

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ImportTnCheckerResponse>
    <ImportTnCheckerPayload>
        <TelephoneNumbers><!--These can be hosted for messaging-->
            <TelephoneNumber>3032281000</TelephoneNumber>
        </TelephoneNumbers>
        <ImportTnErrors>
            <ImportTnError>
                <Code>19006</Code>
                <Description>Bandwidth numbers cannot be imported by this account at this time.</Description>
                <TelephoneNumbers><!--These can NOT be hosted for messaging-->
                    <TelephoneNumber>4109235436</TelephoneNumber>
                    <TelephoneNumber>4104685864</TelephoneNumber>
                </TelephoneNumbers>
            </ImportTnError>
        </ImportTnErrors>
    </ImportTnCheckerPayload>
</ImportTnCheckerResponse>

Create importTnOrder

After validating the numbers are able to be imported, create a POST request to create the order to import the phone numbers in to your Bandwidth account.

Request URL

POST https://dashboard.bandwidth.com/api/accounts/{accountId}/importTnOrders

Request Parameters

Parameter	Required	Description
<CustomerOrderId>	No	Internal customer order id for tracking the order. Only alphanumeric values, dashes and spaces are allowed. Max length is 40 characters.
<Name>	Yes	Subscriber business / customer name.
<HouseNumber>	Yes	Street address number.
<StreetName>	Yes	Street name.
<City>	Yes	City.
<StateCode>	Yes	Two letter state code.
<Zip>	Yes	Zip code.
<LoaAuthorizingPerson>	Yes	First and last name of person who authorized LOA.
<TelephoneNumber>	Yes	Ten digit phone number with no dots or dashes. One or more is required. Use a PhoneNumber tag for each phone number in the list.
<SiteId>	Yes	See section on Sites
<SipPeerId>	No	See section on SIP Peers

Examples

Request

POST https://dashboard.bandwidth.com/api/accounts/{accountId}/importTnOrders HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

<ImportTnOrder>
  <CustomerOrderId>marktestorders</CustomerOrderId>
  <SiteId>14413</SiteId>
  <SipPeerId>521952</SipPeerId>
  <Subscriber>
      <Name>ABC Inc.</Name>
    <ServiceAddress>
      <HouseNumber>11235</HouseNumber>
      <StreetName>Back</StreetName>
      <City>Denver</City>
      <StateCode>CO</StateCode>
      <Zip>27541</Zip>
      <County>Canyon</County>
    </ServiceAddress>
  </Subscriber>
  <LoaAuthorizingPerson>markmacc</LoaAuthorizingPerson>
  <TelephoneNumbers>
    <TelephoneNumber>3032281000</TelephoneNumber>
    <TelephoneNumber>3032280004</TelephoneNumber>
  </TelephoneNumbers>
</ImportTnOrder>

Response

HTTP/1.1 201 Created
Content-Type: application/xml; charset=utf-8
Location: https://dashboard.bandwidth.com/api/accounts/{accountId}/importTnOrders/{orderId}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ImportTnOrderResponse>
  <ImportTnOrder>
    <CustomerOrderId>marktestorders</CustomerOrderId>
    <OrderCreateDate>2018-01-20T02:59:54.000Z</OrderCreateDate>
    <AccountId>9900012</AccountId>
    <CreatedByUser>{username}</CreatedByUser>
    <OrderId>b05de7e6-0cab-4c83-81bb-9379cba8efd0</OrderId>
    <LastModifiedDate>2018-01-20T02:59:54.000Z</LastModifiedDate>
    <SiteId>202</SiteId>
    <SipPeerId>520565</SipPeerId>
    <Subscriber>
      <Name>ABC Inc.</Name>
      <ServiceAddress>
        <HouseNumber>11235</HouseNumber>
        <StreetName>Back</StreetName>
        <City>Denver</City>
        <StateCode>CO</StateCode>
        <Zip>27541</Zip>
        <County>Canyon</County>
      </ServiceAddress>
    </Subscriber>
    <LoaAuthorizingPerson>markmacc</LoaAuthorizingPerson>
    <TelephoneNumbers>
      <TelephoneNumber>3032281000</TelephoneNumber>
      <TelephoneNumber>3032280004</TelephoneNumber>
    </TelephoneNumbers>
    <ProcessingStatus>PROCESSING</ProcessingStatus>
    <Errors/>
  </ImportTnOrder>
</ImportTnOrderResponse>

Fetching importTnOrders Information

A GET request to an existing importTnOrder will return it's status as well as any information originally used to create the order.

Request URL

GET https://dashboard.bandwidth.com/api/accounts/{accountId}/importTnOrders/{orderId}

Examples

ImportTnOrder Status Webhook

ImportTnOrder Status Webhook

info

This is a webhook that bandwidth sends to your server upon order completion/failure - there is no need to poll the resource if using this recommended method.

POST your_url.com/webhookService HTTP/1.1
Content-Type: application/xml; charset=utf-8

<?xml version="1.0"?>
<Notification>
    <SubscriptionId>...</SubscriptionId>
    <OrderType>importtnorders</OrderType>
    <OrderId>b05de7e6-0cab-4c83-81bb-9379cba8efd0</OrderId>
    <CustomerOrderId>...</CustomerOrderId>
    <Status>COMPLETE</Status>
    <Message>Import TN order processing has started.</Message>
    <Note>...</Note>
</Notification>

Poll for ImportTnOrder Status

Poll Order Information

Request

GET https://dashboard.bandwidth.com/api/accounts/{accountId}/importTnOrders/b05de7e6-0cab-4c83-81bb-9379cba8efd0 HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Response

HTTP 200 OK
Content-Type: application/xml; charset=utf-8

<?xml version="1.0"?>
<ImportTnOrder>
   <OrderCreateDate>2019-08-28T13:09:11.192Z</OrderCreateDate>
   <AccountId>9900674</AccountId>
   <CreatedByUser>mmacchioni</CreatedByUser>
   <OrderId>b05de7e6-0cab-4c83-81bb-9379cba8efd0</OrderId>
   <LastModifiedDate>2019-08-28T13:09:26.295Z</LastModifiedDate>
   <SiteId>14419</SiteId>
   <Subscriber>
      <Name>BANDWDITH</Name>
      <ServiceAddress>
         <HouseNumber>900</HouseNumber>
         <StreetName>Main Campus Dr.</StreetName>
         <City>Raleigh</City>
         <StateCode>NC</StateCode>
         <Zip>27606</Zip>
         <County>Wake</County>
         <Country>United States</Country>
         <AddressType>Service</AddressType>
      </ServiceAddress>
   </Subscriber>
   <LoaAuthorizingPerson>Mark Macchioni</LoaAuthorizingPerson>
   <TelephoneNumbers>
      <TelephoneNumber>9195041533</TelephoneNumber>
   </TelephoneNumbers>
   <ProcessingStatus>COMPLETE</ProcessingStatus>
   <Errors />
   <SipPeerId>521967</SipPeerId>
</ImportTnOrder>

Upload Letter of Authorization (LOA)

For completed orders, Bandwidth requires a completed Subscriber "Letter of Authorization" (LOA) from the phone number user. The LOA file is used in the case there is a dispute to ensure the phone number had permission to be enabled for hosted messaging for Bandwidth.

You are able to keep the LOA file within your own system, or upload the file to Bandwidth as part of the importTnOrder path.

Request URL

POST https://dashboard.bandwidth.com/api/accounts/{accountId}/importTnOrders/{orderId}/loas

Request Parameters

A POST request to the /loas resource will upload the file. The key attribute to a successful upload is to ensure that the headers are set correctly to support the type of the file upload.

Examples

Request

POST https://dashboard.../{accountId}/importTnOrders/{orderId}/loas HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Accept: /
Accept-Encoding: gzip, deflate
Content-Type: application/pdf

[file-content-as-body]

Response

HTTP/1.1 201 Created
Content-Type: application/xml; charset=utf-8

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<fileUploadResponse>
    <filename>63097af1-37ae-432f-8a0d-9b0e6517a35b-1429550165581.pdf</filename>
    <resultCode>0</resultCode>
    <resultMessage>LOA file uploaded successfully for order 63097af1-37ae-432f-8a0d-9b0e6517a35b</resultMessage>
</fileUploadResponse>