Search your Numbers

In this guide, we will show you how to search telephone numbers across your Bandwidth account.

Search All Numbers

To search telephone numbers and view possible search parameters, make a GET request to our List Numbers API endpoint. This can be done through tools like Postman or cURL.

Search Types

You can use a combination of these parameters for a more specific search.

All

Search all telephone numbers across your accounts

Request URL:

GEThttps://api.bandwidth.com/api/tns

Examples:

cURL

curl 'https://api.bandwidth.com/api/tns'
-u '{userName}:{password}'

Response

<TelephoneNumbersResponse>
    <TelephoneNumberCount>2</TelephoneNumberCount>
    <Links>
        <first><!-- Snip --></first>
        <next><!-- Snip --></next>
    </Links>
    <TelephoneNumbers>
        <TelephoneNumber>
            <City>CARY</City>
            <Lata>426</Lata>
            <State>NC</State>
            <FullNumber>2012381139</FullNumber>
            <Tier>1</Tier>
            <VendorId>49</VendorId>
            <VendorName>Bandwidth CLEC</VendorName>
            <RateCenter>CARY</RateCenter>
            <Status>Inservice</Status>
            <AccountId>9900008</AccountId>
            <LastModified>2013-12-05T05:58:27.000Z</LastModified>
            <InServiceDate>2013-12-05T05:58:27.000Z</InServiceDate>
        </TelephoneNumber>
        <TelephoneNumber>
            <City>CARY</City>
            <Lata>426</Lata>
            <State>NC</State>
            <FullNumber>9192381138</FullNumber>
            <Tier>0</Tier>
            <VendorId>49</VendorId>
            <VendorName>Bandwidth CLEC</VendorName>
            <RateCenter>CARY</RateCenter>
            <Status>Inservice</Status>
            <AccountId>9900000</AccountId>
            <LastModified>2013-12-05T05:58:27.000Z</LastModified>
            <InServiceDate>2013-12-05T05:58:27.000Z</InServiceDate>
        </TelephoneNumber>
    </TelephoneNumbers>
</TelephoneNumbersResponse>

Account

Search telephone numbers for a specific account

Request URL:

GEThttps://api.bandwidth.com/api/tns?accountId=9900008

Examples:

cURL

curl 'https://api.bandwidth.com/api/tns?accountId=9900008'
-u '{userName}:{password}'

Response

<TelephoneNumbersResponse>
    <TelephoneNumberCount>1</TelephoneNumberCount>
    <Links>
        <first><!-- Snip --></first>
        <next><!-- Snip --></next>
    </Links>
    <TelephoneNumbers>
        <TelephoneNumber>
            <City>CARY</City>
            <Lata>426</Lata>
            <State>NC</State>
            <FullNumber>9192381138</FullNumber>
            <Tier>0</Tier>
            <VendorId>49</VendorId>
            <VendorName>Bandwidth CLEC</VendorName>
            <RateCenter>CARY</RateCenter>
            <Status>Inservice</Status>
            <AccountId>9900008</AccountId>
            <LastModified>2013-12-05T05:58:27.000Z</LastModified>
            <InServiceDate>2013-12-05T05:58:27.000Z</InServiceDate>
        </TelephoneNumber>
    </TelephoneNumbers>
</TelephoneNumbersResponse>

City

Search all telephone numbers for a specific city

Request URL:

GEThttps://api.bandwidth.com/api/tns?city=CARY

Examples:

cURL

curl 'https://api.bandwidth.com/api/tns?city=CARY'
-u '{userName}:{password}'

Response

<TelephoneNumbersResponse>
    <TelephoneNumberCount>2</TelephoneNumberCount>
    <Links>
        <first><!-- Snip --></first>
        <next><!-- Snip --></next>
    </Links>
    <TelephoneNumbers>
        <TelephoneNumber>
            <City>CARY</City>
            <Lata>426</Lata>
            <State>NC</State>
            <FullNumber>2012381139</FullNumber>
            <Tier>1</Tier>
            <VendorId>49</VendorId>
            <VendorName>Bandwidth CLEC</VendorName>
            <RateCenter>CARY</RateCenter>
            <Status>Inservice</Status>
            <AccountId>9900008</AccountId>
            <LastModified>2013-12-05T05:58:27.000Z</LastModified>
            <InServiceDate>2013-12-05T05:58:27.000Z</InServiceDate>
        </TelephoneNumber>
        <TelephoneNumber>
            <City>CARY</City>
            <Lata>426</Lata>
            <State>NC</State>
            <FullNumber>9192381138</FullNumber>
            <Tier>0</Tier>
            <VendorId>49</VendorId>
            <VendorName>Bandwidth CLEC</VendorName>
            <RateCenter>CARY</RateCenter>
            <Status>Inservice</Status>
            <AccountId>9900000</AccountId>
            <LastModified>2013-12-05T05:58:27.000Z</LastModified>
            <InServiceDate>2013-12-05T05:58:27.000Z</InServiceDate>
        </TelephoneNumber>
    </TelephoneNumbers>
</TelephoneNumbersResponse>

Full Number

Search specific telephone number

Request URL:

GEThttps://api.bandwidth.com/api/tns?fullnumber=2012381139

Examples:

cURL

curl 'https://api.bandwidth.com/api/tns?fullnumber=2012381139'
-u '{userName}:{password}'

Response

<TelephoneNumbersResponse>
    <TelephoneNumberCount>1</TelephoneNumberCount>
    <Links>
        <first><!-- Snip --></first>
        <next><!-- Snip --></next>
    </Links>
    <TelephoneNumbers>
        <TelephoneNumber>
            <City>CARY</City>
            <Lata>426</Lata>
            <State>NC</State>
            <FullNumber>2012381139</FullNumber>
            <Tier>1</Tier>
            <VendorId>49</VendorId>
            <VendorName>Bandwidth CLEC</VendorName>
            <RateCenter>CARY</RateCenter>
            <Status>Inservice</Status>
            <AccountId>9900000</AccountId>
            <LastModified>2013-12-05T05:58:27.000Z</LastModified>
            <InServiceDate>2013-12-05T05:58:27.000Z</InServiceDate>
        </TelephoneNumber>
    </TelephoneNumbers>
</TelephoneNumbersResponse>

NPA

Search telephone numbers for a specific NPA

Request URL:

GEThttps://api.bandwidth.com/api/tns?npa=201

Examples:

cURL

curl 'https://api.bandwidth.com/api/tns?npa=201'
-u '{userName}:{password}'

Response

<TelephoneNumbersResponse>
    <TelephoneNumberCount>1</TelephoneNumberCount>
    <Links>
        <first><!-- Snip --></first>
        <next><!-- Snip --></next>
    </Links>
    <TelephoneNumbers>
        <TelephoneNumber>
            <City>CARY</City>
            <Lata>426</Lata>
            <State>NC</State>
            <FullNumber>2012381139</FullNumber>
            <Tier>1</Tier>
            <VendorId>49</VendorId>
            <VendorName>Bandwidth CLEC</VendorName>
            <RateCenter>CARY</RateCenter>
            <Status>Inservice</Status>
            <AccountId>9900000</AccountId>
            <LastModified>2013-12-05T05:58:27.000Z</LastModified>
            <InServiceDate>2013-12-05T05:58:27.000Z</InServiceDate>
        </TelephoneNumber>
    </TelephoneNumbers>
</TelephoneNumbersResponse>

NPANxx

Search telephone numbers for a specific NPANxx

Request URL:

GEThttps://api.bandwidth.com/api/tns?npaNxx=201238

Examples:

cURL

curl 'https://api.bandwidth.com/api/tns?npaNxx=201238'
-u '{userName}:{password}'

Response

<TelephoneNumbersResponse>
    <TelephoneNumberCount>1</TelephoneNumberCount>
    <Links>
        <first><!-- Snip --></first>
        <next><!-- Snip --></next>
    </Links>
    <TelephoneNumbers>
        <TelephoneNumber>
            <City>CARY</City>
            <Lata>426</Lata>
            <State>NC</State>
            <FullNumber>2012381139</FullNumber>
            <Tier>1</Tier>
            <VendorId>49</VendorId>
            <VendorName>Bandwidth CLEC</VendorName>
            <RateCenter>CARY</RateCenter>
            <Status>Inservice</Status>
            <AccountId>9900000</AccountId>
            <LastModified>2013-12-05T05:58:27.000Z</LastModified>
            <InServiceDate>2013-12-05T05:58:27.000Z</InServiceDate>
        </TelephoneNumber>
    </TelephoneNumbers>
</TelephoneNumbersResponse>

NPANxxX

Search telephone numbers for a specific NPANxxX

Request URL:

GEThttps://api.bandwidth.com/api/tns?npaNxxX=2012381

Examples:

cURL

curl 'https://api.bandwidth.com/api/tns?npaNxxX=2012381'
-u '{userName}:{password}'

Response

<TelephoneNumbersResponse>
    <TelephoneNumberCount>1</TelephoneNumberCount>
    <Links>
        <first><!-- Snip --></first>
        <next><!-- Snip --></next>
    </Links>
    <TelephoneNumbers>
        <TelephoneNumber>
            <City>CARY</City>
            <Lata>426</Lata>
            <State>NC</State>
            <FullNumber>2012381139</FullNumber>
            <Tier>1</Tier>
            <VendorId>49</VendorId>
            <VendorName>Bandwidth CLEC</VendorName>
            <RateCenter>CARY</RateCenter>
            <Status>Inservice</Status>
            <AccountId>9900000</AccountId>
            <LastModified>2013-12-05T05:58:27.000Z</LastModified>
            <InServiceDate>2013-12-05T05:58:27.000Z</InServiceDate>
        </TelephoneNumber>
    </TelephoneNumbers>
</TelephoneNumbersResponse>

Rate Center

Search telephone numbers for a specific Rate Center

Request URL:

GEThttps://api.bandwidth.com/api/tns?rateCenter=2012381

Examples:

cURL

curl 'https://api.bandwidth.com/api/tns?rateCenter=CARY'
-u '{userName}:{password}'

Response

<TelephoneNumbersResponse>
    <TelephoneNumberCount>2</TelephoneNumberCount>
    <Links>
        <first><!-- Snip --></first>
        <next><!-- Snip --></next>
    </Links>
    <TelephoneNumbers>
        <TelephoneNumber>
            <City>CARY</City>
            <Lata>426</Lata>
            <State>NC</State>
            <FullNumber>2012381139</FullNumber>
            <Tier>1</Tier>
            <VendorId>49</VendorId>
            <VendorName>Bandwidth CLEC</VendorName>
            <RateCenter>CARY</RateCenter>
            <Status>Inservice</Status>
            <AccountId>9900008</AccountId>
            <LastModified>2013-12-05T05:58:27.000Z</LastModified>
            <InServiceDate>2013-12-05T05:58:27.000Z</InServiceDate>
        </TelephoneNumber>
        <TelephoneNumber>
            <City>CARY</City>
            <Lata>426</Lata>
            <State>NC</State>
            <FullNumber>9192381138</FullNumber>
            <Tier>0</Tier>
            <VendorId>49</VendorId>
            <VendorName>Bandwidth CLEC</VendorName>
            <RateCenter>CARY</RateCenter>
            <Status>Inservice</Status>
            <AccountId>9900000</AccountId>
            <LastModified>2013-12-05T05:58:27.000Z</LastModified>
            <InServiceDate>2013-12-05T05:58:27.000Z</InServiceDate>
        </TelephoneNumber>
    </TelephoneNumbers>
</TelephoneNumbersResponse>

State

Search telephone numbers for a specific State

Request URL:

GEThttps://api.bandwidth.com/api/tns?state=NC

Examples:

cURL

curl 'https://api.bandwidth.com/api/tns?state=NC'
-u '{userName}:{password}'

Response

<TelephoneNumbersResponse>
    <TelephoneNumberCount>2</TelephoneNumberCount>
    <Links>
        <first><!-- Snip --></first>
        <next><!-- Snip --></next>
    </Links>
    <TelephoneNumbers>
        <TelephoneNumber>
            <City>CARY</City>
            <Lata>426</Lata>
            <State>NC</State>
            <FullNumber>2012381139</FullNumber>
            <Tier>1</Tier>
            <VendorId>49</VendorId>
            <VendorName>Bandwidth CLEC</VendorName>
            <RateCenter>CARY</RateCenter>
            <Status>Inservice</Status>
            <AccountId>9900008</AccountId>
            <LastModified>2013-12-05T05:58:27.000Z</LastModified>
            <InServiceDate>2013-12-05T05:58:27.000Z</InServiceDate>
        </TelephoneNumber>
        <TelephoneNumber>
            <City>CARY</City>
            <Lata>426</Lata>
            <State>NC</State>
            <FullNumber>9192381138</FullNumber>
            <Tier>0</Tier>
            <VendorId>49</VendorId>
            <VendorName>Bandwidth CLEC</VendorName>
            <RateCenter>CARY</RateCenter>
            <Status>Inservice</Status>
            <AccountId>9900000</AccountId>
            <LastModified>2013-12-05T05:58:27.000Z</LastModified>
            <InServiceDate>2013-12-05T05:58:27.000Z</InServiceDate>
        </TelephoneNumber>
    </TelephoneNumbers>
</TelephoneNumbersResponse>

Tier

Search telephone numbers for a specific Tier (0-5)

Request URL:

GEThttps://api.bandwidth.com/api/tns?tier=1

Examples:

cURL

curl 'https://api.bandwidth.com/api/tns?tier=1'
-u '{userName}:{password}'

Response

<TelephoneNumbersResponse>
    <TelephoneNumberCount>2</TelephoneNumberCount>
    <Links>
        <first><!-- Snip --></first>
        <next><!-- Snip --></next>
    </Links>
    <TelephoneNumbers>
        <TelephoneNumber>
            <City>CARY</City>
            <Lata>426</Lata>
            <State>NC</State>
            <FullNumber>2012381139</FullNumber>
            <Tier>1</Tier>
            <VendorId>49</VendorId>
            <VendorName>Bandwidth CLEC</VendorName>
            <RateCenter>CARY</RateCenter>
            <Status>Inservice</Status>
            <AccountId>9900008</AccountId>
            <LastModified>2013-12-05T05:58:27.000Z</LastModified>
            <InServiceDate>2013-12-05T05:58:27.000Z</InServiceDate>
        </TelephoneNumber>
    </TelephoneNumbers>
</TelephoneNumbersResponse>

Search for Specific Numbers

To search for specific telephone numbers, make a POST request to our List Numbers API endpoint. This can be done through tools like Postman or cURL.

Request URL:

POSThttps://api.bandwidth.com/api/tns

Examples:

Payload

<TnList>
    <Tn>3172000285</Tn>
    <Tn>3172000207</Tn>
</TnList>

cURL

curl -X POST 'https://api.bandwidth.com/api/tns'
-u '{userName}:{password}'
-H 'Content-Type: application/xml'
-d '<TnList>
        <Tn>3172000285</Tn>
        <Tn>3172000207</Tn>
    </TnList>'

Response

<TelephoneNumbersResponse>
    <TelephoneNumberCount>4</TelephoneNumberCount>
    <Links>
        <first><!-- Snip --></first>
    </Links>
    <TelephoneNumbers>
        <TelephoneNumber>
            <City>INDIANAPOLIS</City>
            <Lata>336</Lata>
            <State>IN</State>
            <FullNumber>3172000285</FullNumber>
            <Tier>0</Tier>
            <VendorId>49</VendorId>
            <VendorName>Bandwidth CLEC</VendorName>
            <RateCenter>INDIANAPLS</RateCenter>
            <Status>Available</Status>
            <AccountId>753</AccountId>
            <LastModified>2016-11-16T19:34:22.000Z</LastModified>
        </TelephoneNumber>
        <TelephoneNumber>
            <City>INDIANAPOLIS</City>
            <Lata>336</Lata>
            <State>IN</State>
            <FullNumber>3172000207</FullNumber>
            <Tier>0</Tier>
            <VendorId>49</VendorId>
            <VendorName>Bandwidth CLEC</VendorName>
            <RateCenter>INDIANAPLS</RateCenter>
            <Status>Aging</Status>
            <AccountId>14</AccountId>
            <LastModified>2016-11-21T19:34:22.000Z</LastModified>
        </TelephoneNumber>
    </TelephoneNumbers>
</TelephoneNumbersResponse>

Retrieve Specific Number Details

To show specific number details, use one of our endpoints described in the list below.

This can be done through tools like Postman or cURL.

TN Details Requests

Information

To show general number information, make a GET request to our Retrieve TN Information API endpoint.

Request URL:

GEThttps://api.bandwidth.com/api/tns/{tn}

Examples:

cURL

curl 'https://api.bandwidth.com/api/tns/{tn}'
-u '{userName}:{password}'

Response

<TelephoneNumberResponse>
    <TelephoneNumber>2012035013</TelephoneNumber>
    <Status>Inservice</Status>
    <LastModifiedDate>2014-03-25 12:55:11.0</LastModifiedDate>
    <OrderCreateDate>2014-03-25T12:55:11.810Z</OrderCreateDate>
    <OrderId>cf79d3c3-21b7-4db7-9867-273a1867f934</OrderId>
    <OrderType>NEW_NUMBER_ORDER</OrderType>
    <InServiceDate>2014-03-25T12:55:11.810Z</InServiceDate>
    <SiteId>2409</SiteId>
    <AccountId>8000273</AccountId>
</TelephoneNumberResponse>

Details

To show number details, make a GET request to our Retrieve TN Details API endpoint.

Request URL:

GEThttps://api.bandwidth.com/api/tns/{tn}/tnDetails

Examples:

cURL

curl 'https://api.bandwidth.com/api/tns/{tn}/tnDetails'
-u '{userName}:{password}'

Response

<TelephoneNumberResponse>
    <TelephoneNumberDetails>
        <City>CARY</City>
        <Lata>426</Lata>
        <State>AL</State>
        <FullNumber>9996667777</FullNumber>
        <Tier>0</Tier>
        <VendorId>49</VendorId>
        <VendorName>Bandwidth CLEC</VendorName>
        <OnNetVendor>true</OnNetVendor>
        <RateCenter>CARY</RateCenter>
        <Status>Inservice</Status>
        <AccountId>9488776</AccountId>
        <Site>
            <Id>30611</Id>
            <Name>Account-Name</Name>
        </Site>
        <SipPeer>
            <PeerId>617819</PeerId>
            <PeerName>peer-name</PeerName>
            <IsDefaultPeer>true</IsDefaultPeer>
        </SipPeer>
        <ServiceTypes>
            <ServiceType>Messaging</ServiceType>
            <ServiceType>Voice</ServiceType>
        </ServiceTypes>
        <LastModified>2020-09-04T20:14:57.000Z</LastModified>
        <MessagingSettings>
            <SmsEnabled>true</SmsEnabled>
            <A2pState>system_default</A2pState>
            <AssignedNnRoute>
                <Nnid>103885</Nnid>
                <Name>unofficial - Bandwidth E830 equivalent - Verizon A2P tag(103885)</Name>
            </AssignedNnRoute>
        </MessagingSettings>
    </TelephoneNumberDetails>
</TelephoneNumberResponse>

Sites

To show sites that are associated with your numbers, make a GET request to our Retrieve TN Sites API endpoint.

Request URL:

GEThttps://api.bandwidth.com/api/tns/{tn}/sites

Examples:

cURL

curl 'https://api.bandwidth.com/api/tns/{tn}/sites'
-u '{userName}:{password}'

Response

<Site>
    <Id>2409</Id>
    <Name>siteName</Name>
</Site>

Sip-Peers

To show SIP Peers associated with your numbers, make a GET request to our Retrieve TN Sip-Peers API endpoint.

Request URL:

GEThttps://api.bandwidth.com/api/tns/{tn}/sippeers

Examples:

cURL

curl 'https://api.bandwidth.com/api/tns/{tn}/sippeers'
-u '{userName}:{password}'

Response

<SipPeer>
    <Id>305643</Id>
    <Name>PeerOneSiteThree</Name>
</SipPeer>

Rate Centers

To show number rate center, make a GET request to our Retrieve TN Rate Center API endpoint.

Request URL:

GEThttps://api.bandwidth.com/api/tns/{tn}/ratecenter

Examples:

cURL

curl 'https://api.bandwidth.com/api/tns/{tn}/ratecenter'
-u '{userName}:{password}'

Response

<TelephoneNumberResponse>
    <TelephoneNumberDetails>
        <State>NJ</State>
        <RateCenter>HACKENSACK</RateCenter>
    </TelephoneNumberDetails>
</TelephoneNumberResponse>

LCA

To show number LCA, make a GET request to our Retrieve TN LCA API endpoint.

Request URL:

GEThttps://api.bandwidth.com/api/tns/{tn}/lca

Examples:

cURL

curl 'https://api.bandwidth.com/api/tns/{tn}/lca'
-u '{userName}:{password}'

Response

<SearchResult>
    <ListofNPANXX>
        <NPANXX>201202</NPANXX>
        <NPANXX>201203</NPANXX>
        <NPANXX>201206</NPANXX>
        <!-- SNIP -->
        <NPANXX>973930</NPANXX>
        <NPANXX>973931</NPANXX>
        <NPANXX>973955</NPANXX>
    </ListofNPANXX>
    <Location>
        <RateCenters>
            <State>NJ</State>
            <RCs>
                <RC>CLIFFSIDE</RC>
                <RC>DUMONT</RC>
                <!-- SNIP -->
                <RC>UNION CITY</RC>
                <RC>WESTWOOD</RC>
            </RCs>
        </RateCenters>
    </Location>
</SearchResult>

LATA

To show number LATA, make a GET request to our Retrieve TN LATA API endpoint.

Request URL:

GEThttps://api.bandwidth.com/api/tns/{tn}/lata

Examples:

cURL

curl 'https://api.bandwidth.com/api/tns/{tn}/lata'
-u '{userName}:{password}'

Response

<TelephoneNumberResponse>
    <TelephoneNumberDetails>
        <Lata>224</Lata>
    </TelephoneNumberDetails>
</TelephoneNumberResponse>

Reservation

To show number reservation, make a GET request to our Retrieve TN Reservation API endpoint.

Request URL:

GEThttps://api.bandwidth.com/api/tns/{tn}/tnreservation

Examples:

cURL

curl 'https://api.bandwidth.com/api/tns/{tn}/tnreservation'
-u '{userName}:{password}'

Response

<TNReservation>
    <ReservationID>d28529e6-23dc-408e-b7ad-f2015a6975d5</ReservationID>
    <Account>12346099</Account>
    <ReservationExpires>14346</ReservationExpires>
    <ReservedTN>6136211234</ReservedTN>
</TNReservation>

NN Routes

To show number available NNRoutes, make a GET request to our Retrieve TN NNRoutes API endpoint.

Request URL:

GEThttps://api.bandwidth.com/api/tns/{tn}/availableNnRoutes

Examples:

cURL

curl 'https://api.bandwidth.com/api/tns/{tn}/availableNnRoutes'
-u '{userName}:{password}'

Response

<AvailableNNRoutes>
    <NNRoute>
        <Nnid>101601</Nnid>>
        <Name>USA Mobility</Name>
    </NNRoute>
    <NNRoute>
        <Nnid>102787</Nnid>
        <Name>Globe Wireless - Bandwidth.com - SVR</Name>
    </NNRoute>
</AvailableNNRoutes>

Where to next?

Now that you have learned how to search numbers in your Bandwidth accounts, check out some of the other available actions in the following guides:

• How to apply options and features to numbers