Skip to main content

How to search and order a phone number

Bandwidth offers an API that allows you to search our inventory and purchase numbers for use with our network.

In this guide we will show you how to search for available phone numbers and order them through the API.

Search Numbers

You can find Bandwidth's available numbers using different search criteria. In certain cases where the exact digits are important (such as localVantiy, endsIn, npaNxxx) LCA should be disabled to filter out non-pattern matched phone numbers. Bandwidth's available number searches with local calling enabled by default. (The LCA flag searches nearby Ratecenters for phone numbers that are considered "local" to the parameters passed).

Search Parameters

To search for an available number and view possible search parameters, make a GET request to our Available Numbers API endpoint. This can be done through tools like Postman or cURL.

You can use a combination of path parameters for different type of search.

Search telephone numbers for a specific Area Code

Search TypeRequired ParametersCombinational ParametersOptional Parameters
Area CodeareaCode

rateCenter (state required), city (state required), state, lata, zip

quantity, enableTNDetail, protected

Request URL

GET

https://dashboard.bandwidth.com/api/accounts/{accountId} /availableNumbers?areaCode=919&quantity=2

Examples:

curl 'https://dashboard.bandwidth.com/api/accounts/{accountId}/availableNumbers?areaCode=919&quantity=2'
-u '{userName}:{password}'

Response

<SearchResult>
<ResultCount>2</ResultCount>
<TelephoneNumberList>
<TelephoneNumber>6672286710</TelephoneNumber>
<TelephoneNumber>5756186700</TelephoneNumber>
</TelephoneNumberList>
</SearchResult>

Order Phone Numbers

The orderType parameter of the request schema in Order Numbers API determines how you order numbers. To create an order using the numbers found in your search, set the orderType to ExistingTelephoneNumberOrderType.

You can also search and order numbers simultaneously by setting the orderType parameter to one of the search and order types.

In this example, we will show how to create an order for numbers that were found using the search. To order numbers, you must make a POST request to our Order Numbers API endpoint. This can be done through tools like Postman or cURL.

Request URL

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

Examples

<Order>
<SiteId>461</SiteId>
<PartialAllowed>true</PartialAllowed>
<ExistingTelephoneNumberOrderType>
<TelephoneNumberList>
<TelephoneNumber>6672286710</TelephoneNumber>
<TelephoneNumber>5756186700</TelephoneNumber>
</TelephoneNumberList>
</ExistingTelephoneNumberOrderType>
</Order>

Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OrderResponse>
<Order>
<OrderCreateDate>2018-01-23T19:56:29.678Z</OrderCreateDate>
<BackOrderRequested>false</BackOrderRequested>
<id>47955555-67aa-4adb-8c0f-b6894e60c0dc</id>
<ExistingTelephoneNumberOrderType>
<TelephoneNumberList>
<TelephoneNumber>6672286710</TelephoneNumber>
<TelephoneNumber>5756186700</TelephoneNumber>
</TelephoneNumberList>
</ExistingTelephoneNumberOrderType>
<PartialAllowed>true</PartialAllowed>
<SiteId>461</SiteId>
</Order>
<OrderStatus>RECEIVED</OrderStatus>
</OrderResponse>

Fetch Order Information

Phone number ordering in the Bandwidth Dashboard is 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.

Poll for Order Status

To poll for Order status you have to send GET request with order ID to our Fetch Order Status API endpoint.

Order Status Webhook

This is a webhook that bandwidth sends to your server/email upon order completion/failure - there is no need to poll the resource if using this recommended method. Please follow the How to setup Notification Webhook guide for more information.

Request URL

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

Examples

<Subscription>
<OrderType>orders</OrderType>
<OrderId>ORDER_ID</OrderId>
<EmailSubscription>
<Email>your_email@gmail.com</Email>
<DigestRequested>DAILY</DigestRequested>
</EmailSubscription>
</Subscription>

Where to next?

Now that you have learned how to search and order numbers, check out some of the other available actions in our guides: