How to host phone numbers for messaging

In this guide, we will show you how to programmatically import phone numbers to your account for use with Bandwidth's Messaging Products.

info

Line options feature management is NOT available for phone numbers that have been imported for use with hosted messaging.

Check for Importability

In order to determine whether or not Bandwidth can host a number for messaging, you must first check if they can be imported.

info

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.

To check if your numbers can be imported for hosted messaging, make a POST request to our Import TN Checker API endpoint. This can be done through tools like Postman or cURL.

Examples:

Payload

Request URL:

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

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

cURL

curl -X POST 'https://dashboard.bandwidth.com/api/accounts/{accountId}/importTnChecker'
-u '{userName}:{password}'
-H 'Content-Type: application/xml'
-d '<ImportTnCheckerPayload>
        <TelephoneNumbers>
            <TelephoneNumber>3032281000</TelephoneNumber>
            <TelephoneNumber>4109235436</TelephoneNumber>
            <TelephoneNumber>4104685864</TelephoneNumber>
        </TelephoneNumbers>
        <SiteId>486</SiteId>
        <SipPeerId>500025</SipPeerId>
    </ImportTnCheckerPayload>'

Response

<ImportTnCheckerResponse>
    <ImportTnCheckerPayload>
        <TelephoneNumbers>
            <TelephoneNumber>3032281000</TelephoneNumber>
        </TelephoneNumbers>
        <ImportTnErrors>
            <ImportTnError>
                <Code>19006</Code>
                <Description>Bandwidth numbers cannot be imported by this account at this time.</Description>
                <TelephoneNumbers>
                    <TelephoneNumber>4109235436</TelephoneNumber>
                    <TelephoneNumber>4104685864</TelephoneNumber>
                </TelephoneNumbers>
            </ImportTnError>
        </ImportTnErrors>
    </ImportTnCheckerPayload>
</ImportTnCheckerResponse>

Create Import TN Order

After validating that your numbers are able to be imported, you can create the order to import the phone numbers into your Bandwidth account. To do that, you must make a POST request to our Create Import TN Order API endpoint. This can be done through tools like Postman or cURL.

Examples:

Payload

Request URL:

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

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

cURL

curl -X POST 'https://dashboard.bandwidth.com/api/accounts/{accountId}/importTnOrders'
-u '{userName}:{password}'
-H 'Content-Type: application/xml'
-d '<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

<ImportTnOrdersResponse>
   <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>
</ImportTnOrdersResponse>

Fetch Order Status

Since the Import TN order is asynchronous, 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 a subscription. Please follow the How to setup Notification Webhook guide for more information.

Otherwise, you can make a GET request to Fetch Import TN Order status API endpoint to poll the order status.

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. To upload a LOA file, make a POST request to Import TN Order LOAs API endpoint. This can be done through tools like Postman or cURL.

info

The key attribute to a successful upload is to ensure that the headers, Content-Type, Accept-Encoding and Accept, are set correctly to support the type of the file upload.

Examples:

Request URL

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

cURL

curl -X POST 'https://dashboard.bandwidth.com/api/accounts/{accountId}/importTnOrders/{orderId}/loas'
-u '{userName}:{password}'
-H 'Content-Type: application/pdf'
-H 'Accept-Encoding: gzip, deflate'
-H 'Accept: /'
-d [file-content-as-body]

Response

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

Where to next?

Now that you have learned how to host phone numbers for messaging, check out some of the other available actions in our guides:

• How to search your numbers