Skip to main content

Searching Number Inventory

Searching for available phone numbers can be performed through our Dashboard API. There are many ways to search for phone numbers and this guide covers the various methods and how you perform them.

Specific API information can be found on our Dashboard API reference

Searching Numbers#

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.

Request URL#

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

Query Parameters#

ParameterDescriptionExample
areaCodeThe 3 digit area code to search for919
npaNxxThe 6 digits following an area code123321
npaNxxxThe 7 digits following an area code1234321
rateCenterThe rate center to search forCary
stateThe 2 letter state code to search forNC
cityThe city to search forRaleigh
zipThe 5 or 9 digit zip code to search for27606, 27606-0007
lataLocal access and transport area. An up to 5 digit number that represents the geographic area in which numbers are routed244
localVanityA 3 to 7 alphanumeric character long string for pattern matching of phone numbers. May also include * (to match all) and _ (to match one)81_, 8*
tollFreeVanityA 4 to 7 alphanumeric character long string for pattern matching of toll free numbersNEWCARS
tollFreeWildCardPatternA 3 alphanumeric character long string representing a wild card pattern for toll free numbers8**
quantityNumber of phone numbers to return. Can be 1 to 5000. Defaults to 50005000
enableTNDetailBoolean value to include TN details. Defaults to falsetrue
LCABoolean value to include TNs in the local calling area.
⚠️Defaults to true
true
endsInBoolean value to include only numbers which end in the localVanity. Defaults to falsetrue
orderByThe field to order the results by. Can be one of fullNumber, npaNxx, npaNxxx, or areaCodeareaCode
protectedDetermines if the search should return only protected numbers (ONLY), only not protected numbers (NONE), or both protected and not protected numbers (MIXED). Can be one of NONE, ONLY, or MIXEDNONE

Local Calling Area (LCA)#

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

Search TypeRequired ParametersCombinational ParametersOptional Parameters
Area CodeareaCoderateCenter (state required), city (state required), state, lata, zipquantity, enableTNDetail, protected
NPA-NXXnpaNxxrateCenter (state required), city (state required), state, lata, zip, orderByquantity, enableTNDetail, protected
NPA-NXX with Local Calling AreanpaNxxquantity, LCA, enableTNDetail, protected
NPA-NXX-XnpaNxxxrateCenter (state required), city (state required), state, lata, zip, orderByquantity, enableTNDetail, protected
NPA-NXX-X with Local Calling AreanpaNxxxrateCenter (state required), city (state required), state, lata, zipquantity, LCA, enableTNDetail, protected
RateCenterrateCenter, statecity, areaCode/npaNxx/npaNxxx, lata, zip, orderByquantity, enableTNDetail, protected
RateCenter with Local Calling ArearateCenter, statequantity, LCA, enableTNDetail, protected
StatestaterateCenter, city, areaCode/npaNxx/npaNxxx, lata, zipquantity, enableTNDetail, protected
Citystate, cityrateCenter, state, areaCode/npaNxx/npaNxxx, lata, zip, orderByquantity, enableTNDetail, protected
Zip CodeziprateCenter (state required), city (state required), state, areaCode/npaNxx/npaNxxx, lata, orderByquantity, enableTNDetail, protected
LATAlatarateCenter (state required), city (state required), state, areaCode/npaNxx/npaNxxx, zipquantity, enableTNDetail, protected
Local VanitylocalVanitystate, areaCodeendsIn, quantity, protected, enableTNdetails
TollFree VanitytollFreeVanityorderByquantity
TollFree WildCardtollFreeWildCardPatternorderByquantity

Examples#

Search for 2 phone numbers by Area Code

Parameters:

  • areaCode : 919
  • quantity : 2

Request

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

Response

HTTP/1.1 200
Content-type: application/xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SearchResult>
<ResultCount>2</ResultCount>
<TelephoneNumberList>
<TelephoneNumber>9192760028</TelephoneNumber>
<TelephoneNumber>9194954957</TelephoneNumber>
</TelephoneNumberList>
</SearchResult>