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 Type	Required Parameters	Combinational Parameters	Optional Parameters
Area Code	areaCode	rateCenter (state required), city (state required), state, lata, zip	quantity, enableTNDetail, protected

Request URL

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

Examples:

cURL

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

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

Search telephone numbers for a specific NPA-NXX

Search Type	Required Parameters	Combinational Parameters	Optional Parameters
NPA-NXX	npaNxx	rateCenter (state required), city (state required), state, lata, zip, orderBy	quantity, enableTNDetail, protected
NPA-NXX with Local Calling Area	npaNxx		quantity, LCA, enableTNDetail, protected
NPA-NXX-X	npaNxxx	rateCenter (state required), city (state required), state, lata, zip, orderBy	quantity, enableTNDetail, protected
NPA-NXX-X with Local Calling Area	npaNxxx	rateCenter (state required), city (state required), state, lata, zip	quantity, LCA, enableTNDetail, protected

Request URL

GEThttps://dashboard.bandwidth.com/api/accounts/{accountId}/availableNumbers?npanxx=919228&quantity=2

Examples:

cURL

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

<SearchResult>
    <ResultCount>2</ResultCount>
    <TelephoneNumberList>
        <TelephoneNumber>9192286710</TelephoneNumber>
        <TelephoneNumber>9192286700</TelephoneNumber>
    </TelephoneNumberList>
</SearchResult>

Search telephone numbers for a specific Rate Center

Search Type	Required Parameters	Combinational Parameters	Optional Parameters
RateCenter	rateCenter, state	city, areaCode/npaNxx/npaNxxx, lata, zip, orderBy	quantity, enableTNDetail, protected
RateCenter with Local Calling Area	rateCenter, state		quantity, LCA, enableTNDetail, protected

Request URL

GEThttps://dashboard.bandwidth.com/api/accounts/{accountId}/availableNumbers?rateCenter=CARY&state=NC&quantity=2

Examples:

cURL

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

<SearchResult>
    <ResultCount>2</ResultCount>
    <TelephoneNumberList>
        <TelephoneNumber>9192286710</TelephoneNumber>
        <TelephoneNumber>9192286700</TelephoneNumber>
    </TelephoneNumberList>
</SearchResult>

Search telephone numbers for a specific State

Search Type	Required Parameters	Combinational Parameters	Optional Parameters
State	state	rateCenter, city, areaCode/npaNxx/npaNxxx, lata, zip	quantity, enableTNDetail, protected

Request URL

GEThttps://dashboard.bandwidth.com/api/accounts/{accountId}/availableNumbers?state=NC&quantity=2

Examples:

cURL

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

<SearchResult>
    <ResultCount>2</ResultCount>
    <TelephoneNumberList>
        <TelephoneNumber>9192286710</TelephoneNumber>
        <TelephoneNumber>9192286700</TelephoneNumber>
    </TelephoneNumberList>
</SearchResult>

Search telephone numbers for a specific City

Search Type	Required Parameters	Combinational Parameters	Optional Parameters
City	state, city	rateCenter, state, areaCode/npaNxx/npaNxxx, lata, zip, orderBy	quantity, enableTNDetail, protected

Request URL

GEThttps://dashboard.bandwidth.com/api/accounts/{accountId}/availableNumbers?city=CARY&state=NC&quantity=2

Examples:

cURL

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

<SearchResult>
    <ResultCount>2</ResultCount>
    <TelephoneNumberList>
        <TelephoneNumber>9192286710</TelephoneNumber>
        <TelephoneNumber>9192286700</TelephoneNumber>
    </TelephoneNumberList>
</SearchResult>

Search telephone numbers for a specific Zip Code

Search Type	Required Parameters	Combinational Parameters	Optional Parameters
Zip Code	zip	rateCenter (state required), city (state required), state, areaCode/npaNxx/npaNxxx, lata, orderBy	quantity, enableTNDetail, protected

Request URL

GEThttps://dashboard.bandwidth.com/api/accounts/{accountId}/availableNumbers?zip=27511&quantity=2

Examples:

cURL

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

<SearchResult>
    <ResultCount>2</ResultCount>
    <TelephoneNumberList>
        <TelephoneNumber>9192286710</TelephoneNumber>
        <TelephoneNumber>9192286700</TelephoneNumber>
    </TelephoneNumberList>
</SearchResult>

Search telephone numbers for a specific LATA

Search Type	Required Parameters	Combinational Parameters	Optional Parameters
LATA	lata	rateCenter (state required), city (state required), state, areaCode/npaNxx/npaNxxx, zip	quantity, enableTNDetail, protected

Request URL

GEThttps://dashboard.bandwidth.com/api/accounts/{accountId}/availableNumbers?lata=426&quantity=2

Examples:

cURL

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

<SearchResult>
    <ResultCount>2</ResultCount>
    <TelephoneNumberList>
        <TelephoneNumber>9192286710</TelephoneNumber>
        <TelephoneNumber>9192286700</TelephoneNumber>
    </TelephoneNumberList>
</SearchResult>

Search telephone numbers for a specific Local Vanity

Search Type	Required Parameters	Combinational Parameters	Optional Parameters
Local Vanity	localVanity	state, areaCode	endsIn, quantity, protected, enableTNdetails

Request URL

GEThttps://dashboard.bandwidth.com/api/accounts/{accountId}/availableNumbers?localVanity=NEWCARS&quantity=2

Examples:

cURL

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

<SearchResult>
    <ResultCount>2</ResultCount>
    <TelephoneNumberList>
        <TelephoneNumber>9192286710</TelephoneNumber>
        <TelephoneNumber>9192286700</TelephoneNumber>
    </TelephoneNumberList>
</SearchResult>

Search telephone numbers for a specific TollFree Vanity

Search Type	Required Parameters	Combinational Parameters	Optional Parameters
TollFree Vanity	tollFreeVanity	orderBy	quantity

Request URL

GEThttps://dashboard.bandwidth.com/api/accounts/{accountId}/availableNumbers?tollFreeVanity=NEWCARS&quantity=2

Examples:

cURL

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

<SearchResult>
    <ResultCount>2</ResultCount>
    <TelephoneNumberList>
        <TelephoneNumber>8012286710</TelephoneNumber>
        <TelephoneNumber>8012286700</TelephoneNumber>
    </TelephoneNumberList>
</SearchResult>

The tollFreeWildCardPattern allows you to search toll free area codes, but forces the 3rd digit to be a *. The third digit of Toll Free area codes will always be a repeat of the second. To search for 833 numbers, set the parameter value as 83* to return 833 numbers. For 800 numbers, search for 80* and so on.

Search Type	Required Parameters	Combinational Parameters	Optional Parameters
TollFree WildCard	tollFreeWildCardPattern	orderBy	quantity

Request URL

GEThttps://dashboard.bandwidth.com/api/accounts/{accountId}/availableNumbers?tollFreeWildCardPattern=80*&quantity=2

Examples:

cURL

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

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SearchResult>
    <ResultCount>2</ResultCount>
    <TelephoneNumberList>
        <TelephoneNumber>8002286710</TelephoneNumber>
        <TelephoneNumber>8006186700</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

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

Examples

Payload
cURL

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

curl -X POST 'https://dashboard.bandwidth.com/api/accounts/{accountId}/orders'
-u '{userName}:{password}'
-H 'Content-Type: application/xml'
-d '<Order>
        <SiteId>461</SiteId>
        <PartialAllowed>true</PartialAllowed>
        <ExistingTelephoneNumberOrderType>
            <TelephoneNumberList>
                <TelephoneNumber>6672286710</TelephoneNumber>
                <TelephoneNumber>5756186700</TelephoneNumber>
            </TelephoneNumberList>
        </ExistingTelephoneNumberOrderType>
    </Order>'

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

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

Examples

Payload
cURL

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

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

How to port numbers

Search Numbers​

Search Parameters​

Request URL​

Examples:​

Request URL​

Examples:​

Request URL​

Examples:​

Request URL​

Examples:​

Request URL​

Examples:​

Request URL​

Examples:​

Request URL​

Examples:​

Request URL​

Examples:​

Request URL​

Examples:​

Request URL​

Examples:​

Order Phone Numbers​

Request URL​

Examples​

Fetch Order Information​

Order Status Webhook​

Request URL​

Examples​

Where to next?​

Search Numbers

Search Parameters

Request URL

Examples:

Request URL

Examples:

Request URL

Examples:

Request URL

Examples:

Request URL

Examples:

Request URL

Examples:

Request URL

Examples:

Request URL

Examples:

Request URL

Examples:

Request URL

Examples:

Order Phone Numbers

Request URL

Examples

Fetch Order Information

Order Status Webhook

Request URL

Examples

Where to next?