{% multimethod %} {% endmultimethod %}

Number Ordering Summary {#top}

This guide will take you through the basics of searching and ordering phone numbers with the Bandwidth Phone Number API.

Assumptions

You have a Phone Number Dashboard account

Overview

Searching for new Phone Numbers
Reserving Phone Numbers
Ordering Phone Numbers
Fetching Order Info
Deactivating a Phone Number
Fetching Deactivation Info

Searching For Phone Numbers {#search-for-phone-numbers}

Finding numbers can be achieved by searching the Bandwidth inventory.

This step is optional – the telephone numbers can be ordered directly using search criteria, but if there is need to examine the numbers before activating them on the account, the search can be used to return a list of available numbers.

There are a number of search approaches that can be used; the NPA NXX search is used for this example. Please see the API documentation for the other applicable search types.

Base URL

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

{% extendmethod %}

Query Parameters

Parameters	Description
`areaCode`	The allowed number ranges are [2-9] for the first digit and [0-9] for both the second and third digits.
`npaNxx` -or- `npaNxxx`	NPA NXX combination to be searched. - Valid npa values:[2-9] for the first digit, and [0-9] for both the second and third digits. - Valid Nxx values:[2-9] for the first digit, and [0-9] for both the second and third digits. - Valid x values [0-9].
`rateCenter`	The abbreviation for the Rate Center
`state`	The two-letter abbreviation of the state the RateCenter is in.
`city`	The name of the city.
`zip`	A five-digit (XXXXX) or nine-digit (XXXXX-XXXX) zip-code value.
`lata`	A maximum five digit (XXXXX) numeric format.
`localVanity`	Requested vanity number. Valid range is from 4 to 7 alphanumeric characters
`tollFreeVanity`	The Toll Free requested vanity number. Valid range is from 4 to 7 alphanumeric characters
`tollFreeWildCardPattern`	The requested Toll Free 3 digit wild card pattern. Examples: `8*`, `80`, `87*`, etc.
`quantity`	The desired quantity of requested numbers. Values range from 1-5000. If no quantity is specified, the default of 5000 is returned.
`enableTNDetail`	If set to true, a list of details associated with the telephone number (rate center abbreviation, rate center host city, state, and LATA) will be displayed along with the telephone number. This value is set to false by default.
`LCA`	Local Calling Area. If this parameter is specified then Telephone Numbers that are likely in the Local Calling Area of the stated Rate Center, NPANXX or NPANNXX will be returned, in addition to those that exactly match the query will be returned. Since LCA logic is not always symmetric and not always inclusive of RC and NPANXX search criteria, this result reflects somewhat of an approximation. The parameter value is true or false. The default is true
`endsIn`	Intended to use with localVanity only. The parameter value is true or false. If set to true, the search will look for only numbers which end in specified localVanity, otherwise localVanity sequence can be met anywhere in last 7 number digits. The default is false.
`orderBy`	The field by which the returned numbers will be sorted. Only supported if at least one of the following search criteria is specified: npaNxx or npaNxxx, rateCenter, city, zip, tollFreeVanity, tollFreeWildCardPattern. Allowed values are fullNumber, npaNxxx, npaNxx, and areaCode>
`protected`	A query parameter, that governs, how the Protected status of numbers impacts the search results: - `None` : The numbers returned in the payload will not contain any numbers that are tagged as Protected - `ONLY` :The numbers returned in the payload will all be tagged as Protected. No "unProtected" numbers will be returned - `MIXED` : The protected status of the numbers will be ignored in the search - all types of numbers will be returned

{% common %}

Example: Search by NPA NXX

GET https://dashboard.bandwidth.com/api/accounts/{{accountId}}/availableNumbers?npaNxx=540551&quantity=10 HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: {user:password}

Response

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SearchResult>
    <ResultCount>7</ResultCount>
    <TelephoneNumberList>
        <TelephoneNumber>5405514342</TelephoneNumber>
        <TelephoneNumber>5405515330</TelephoneNumber>
        <TelephoneNumber>5405515329</TelephoneNumber>
        <TelephoneNumber>5402278098</TelephoneNumber>
        <TelephoneNumber>5402270905</TelephoneNumber>
        <TelephoneNumber>5402278089</TelephoneNumber>
        <TelephoneNumber>5402278090</TelephoneNumber>
    </TelephoneNumberList>
</SearchResult>

ℹ️ Notice that only 7 of 10 were returned = that is all that were currently available in that npanxx combination. Any of these numbers can be reserved or immediately ordered

{% endextendmethod %}

Reserve Phone Numbers {#reserving-phone-numbers}

In the example below, we reserve a number returned by the search, preventing other accounts from ordering that available number before the number is activated on the account. This is intended to manage the delays that occur in the customer “buy-flow”, permitting the number to be discarded unless a purchase confirmation is returned by the end user.

A reserved telephone number or a set of reserved telephone numbers are reserved for a default time of 4 hours. A successful reservation returns a location header that can be used to retrieve the reservation at a later time.

Base URL

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

{% extendmethod %}

Body Parameters

Parameter	Description
`ReservedTn`	The Desired Phone Number to reserve You can only reserve a single phone number at a time! If multiple `<ReservedTn>` are sent, only the last `<ReservedTn>` will be reserved

{% common %}

Example: Reserve a Phone Number

POST https://dashboard.bandwidth.com/api/accounts/{{accountId}}/tnreservation HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: {user:password}

<Reservation>
    <ReservedTn>5405514342</ReservedTn>
</Reservation>

Response

HTTP/1.1 201 Created
Content-Type: application/xml; charset=utf-8
Location: https://dashboard.bandwidth.com/api/accounts/{{accountId}}/tnreservation/8dddbd6f-77ca-4a17-97ca-83d334fc404e

{% endextendmethod %}

Check existing Phone Numbers Reservation {#get-reserved-phone-numbers}

Retrieves a TN reservation's information.

Base URL

GEThttps://dashboard.bandwidth.com/api/accounts/{{accountId}}/tnreservation/{{reservationId}}

Query Parameters

There are no query parameters for fetching information about an existing reservation

{% extendmethod %}

{% common %}

Example: Fetch an existing Reservation

GET https://dashboard.bandwidth.com/api/accounts/{{accountId}}/tnreservation/8dddbd6f-77ca-4a17-97ca-83d334fc404e HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: {user:password}

Response

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ReservationResponse>
  <Reservation>
    <ReservationId>8dddbd6f-77ca-4a17-97ca-83d334fc404e</ReservationId>
    <AccountId>9500012</AccountId>
    <ReservationExpires>14293</ReservationExpires>
    <ReservedTn>5405514342</ReservedTn>
  </Reservation>
</ReservationResponse>

{% endextendmethod %}

Order Phone Numbers {#order-phone-numbers}

Ordering Phone Numbers for use with the network uses requires you to order specific phone numbers that have been discovered in a search. This is only one of a number of ways to acquire and activate phone numbers.

Base URL

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

{% extendmethod %}

Common Request Parameters

EVERY type of order can/must include the parameters below

Parameter	Required	Description
`Quantity`	No	The desired quantity of requested numbers. values range from 1-5000. Default: `5000`
`Name`	Yes	The name of the order. Max length restricted to 50 characters.
`CustomerOrderId`	No	Optional value for Id set by customer
`SiteId`	Yes	The ID of the Site (or sub-account) that the SIP Peer is to be associated with.
`PeerId`	No	The ID of the SIP Peer (or location) that the telephone numbers are to be assigned to. ⚠️ The `PeerId` MUST already exist under the `Site` (or sub-account) EX: `/accounts/{accountId}/sites/{siteId}/sippeers/{PeerId}`
`PartialAllowed`	No	By default all order submissions are fulfilled partially. Setting the `PartialAllowed` to false would trigger the entire order to be fulfilled (any error encountered such as 1 TN not being available would fail all TNs in the order) Default: `false`
`BackOrderRequested`	No	`BackOrderRequested` will indicate to the system that if the entire quantity of numbers is not available on the first attempt to fill the new number order, the request will be repeated periodically until the request is successful or canceled. `true` - Backorder numbers if the entire quantity is not available Default: `false`

Order Type Specific Request Parameters

These parameters may or may not be required based on the type of order. Check out the reference documentation for more information on the different types of orders

Parameter	Description
`TelephoneNumberList`	A list of telephone numbers to order
`AreaCode`	Allowed ranged: [2-9] for the first digit and [0, 9] for both the second and third digits.
`RateCenter`	A text Rate Center name. Must be combined with State information
`State`	The two-letter abbreviation of the state
`City`	The name of the city that the Ordered telephone numbers should apply to
`Zip`	A five-digit (XXXXX) or nine-digit (XXXXX-XXXX) format value.
`Lata`	A maximum five-digit (XXXXX) numeric format.
`EnableLCA`	If set to `true`, local calling access numbers will be returned for Rate Center, NPA-NXX and NPANXXX orders if numbers are not available for the given criteria. Default: `true`.
`Npa-Nxx` -or- `Npa-Nxxxx` ⚠️ with `EnableLCA` : `true`	NpaNxx combination to be searched. Valid Npa values: [2-9] for the first digit, and [0-9] for both the second and third digits. Valid Nxx values: [2-9] for the first digit, and [0-9] for both the second and third digits. Valid Xxvalues [0-9]. ℹ️ If set to true, enables the ability to get local calling access numbers if numbers are not available for the given criteria.
`LocalVanity`	A text string used to request a regular vanity number. Valid range is between 4 and 7 alphanumeric characters.
`EndsIn`	Intended to use with `LocalVanity` only. -`true` : the search will look for only numbers which end in specified `LocalVanity` -`false`: `LocalVanity` sequence can be met anywhere in last 7 number digits. Default: `false`
`TollFreeVanity`	A text string used to request a toll free vanity number. Valid range is between 4 and 7 alphanumeric characters.
`TollFreeWildCardPattern`	A 3-digit wild card pattern for specifying toll free prefixes, comprised of 8 followed by two stars, a digit and a star or two digits
`ReservationIdList`	If a telephone number or numbers have been previously reserved, the ReservationIdList provides the IDs necessary to release the numbers. This only applies to reserved numbers - if no reservation has been placed on the numbers this list is not required.
`TnAttributes`	Attributes to be assigned to the telephone number. Optional parameter. Possible values: `Protected`

{% common %}

Example 1 of 2: Order Previously Reserved Phone Numbers from a Reservation

POST https://dashboard.bandwidth.com/api/accounts/{{accountId}}/orders HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: {user:password}

<Order>
    <Name>Available Telephone Number order</Name>
    <SiteId>461</SiteId>
    <CustomerOrderId>SJMres001</CustomerOrderId>
    <ExistingTelephoneNumberOrderType>
       <TelephoneNumberList>
           <TelephoneNumber>7034343704</TelephoneNumber>
           <TelephoneNumber>5405514342</TelephoneNumber>
       </TelephoneNumberList>
       <ReservationIdList>
           <ReservationId>3150268b-b7e8-421f-8cc8-9ad9f2e8fd24</ReservationId>
           <ReservationId>8dddbd6f-77ca-4a17-97ca-83d334fc404e</ReservationId>
       </ReservationIdList>
    </ExistingTelephoneNumberOrderType>
</Order>

Response

HTTP/1.1 201 Created
Content-Type: application/xml; charset=utf-8
Location: https://dashboard.bandwidth.com/api/accounts/{{accountId}}/orders/d30eda5a-ce10-456e-8cb9-eb13b9f14cfd

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OrderResponse>
    <Order>
        <CustomerOrderId>SJMres001</CustomerOrderId>
        <Name>Available Telephone Number order</Name>
        <OrderCreateDate>2015-01-20T20:58:39.365Z</OrderCreateDate>
        <BackOrderRequested>false</BackOrderRequested>
        <id>d30eda5a-ce10-456e-8cb9-eb13b9f14cfd</id>
        <ExistingTelephoneNumberOrderType>
            <ReservationIdList>
                <ReservationId>3150268b-b7e8-421f-8cc8-9ad9f2e8fd24</ReservationId>
                <ReservationId>8dddbd6f-77ca-4a17-97ca-83d334fc404e</ReservationId>
            </ReservationIdList>
            <TelephoneNumberList>
                <TelephoneNumber>7034343704</TelephoneNumber>
                <TelephoneNumber>5405514342</TelephoneNumber>
            </TelephoneNumberList>
        </ExistingTelephoneNumberOrderType>
        <PartialAllowed>true</PartialAllowed>
        <SiteId>461</SiteId>
    </Order>
    <OrderStatus>RECEIVED</OrderStatus>
</OrderResponse>

Example 2 of 2: Search AND Order 1 Number in Area Code

POST https://dashboard.bandwidth.com/api/accounts/{{accountId}}/orders HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: {user:password}

<Order>
    <AreaCodeSearchAndOrderType>
        <AreaCode>910</AreaCode>
        <Quantity>1</Quantity>
    </AreaCodeSearchAndOrderType>
    <SiteId>461</SiteId>
</Order>

Response

HTTP/1.1 201 Created
Content-Type: application/xml; charset=utf-8
Location: https://dashboard.bandwidth.com/api/accounts/{{accountId}}/orders/47955555-ce10-456e-8cb9-eb13b9f14cfd

<?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>
        <AreaCodeSearchAndOrderType>
            <AreaCode>910</AreaCode>
            <Quantity>1</Quantity>
        </AreaCodeSearchAndOrderType>
        <PartialAllowed>true</PartialAllowed>
        <SiteId>461</SiteId>
    </Order>
    <OrderStatus>RECEIVED</OrderStatus>
</OrderResponse>

{% endextendmethod %}

Fetching Order Information {#get-order-info}

A GET Request to an existing order will return it's status as well as any information originally used to create the order.

Base URL

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

{% extendmethod %}

Query Parameters

There are no query parameters for fetching information about an existing order.

{% common %}

Example: Fetch Order Information

GET https://dashboard.bandwidth.com/api/accounts/{{accountId}}/orders/d30eda5a-ce10-456e-8cb9-eb13b9f14cfd HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: {user:password}

Response

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OrderResponse>
    <CompletedQuantity>2</CompletedQuantity>
    <CreatedByUser>jbm</CreatedByUser>
    <LastModifiedDate>2015-01-20T20:58:39.549Z</LastModifiedDate>
    <OrderCompleteDate>2015-01-20T20:58:39.549Z</OrderCompleteDate>
    <Order>
        <CustomerOrderId>SJMres001</CustomerOrderId>
        <Name>Available Telephone Number order</Name>
        <OrderCreateDate>2015-01-20T20:58:39.365Z</OrderCreateDate>
        <PeerId>1927</PeerId>
        <BackOrderRequested>false</BackOrderRequested>
        <ExistingTelephoneNumberOrderType/>
        <PartialAllowed>true</PartialAllowed>
        <SiteId>461</SiteId>
    </Order>
    <OrderStatus>COMPLETE</OrderStatus>
    <CompletedNumbers>
        <TelephoneNumber>
            <FullNumber>5405514342</FullNumber>
        </TelephoneNumber>
        <TelephoneNumber>
            <FullNumber>7034343704</FullNumber>
        </TelephoneNumber>
    </CompletedNumbers>
    <FailedQuantity>0</FailedQuantity>
</OrderResponse>

{% endextendmethod %}

Disconnecting a Phone Number {#disconnect-phone-number}

Disconnecting a phone number leaves it in all applicable inventories, but makes it available for activation with a new subscriber.

Base URL

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

{% extendmethod %}

Request Parameters

Parameter	Required	Description
`Name`	Yes	The name of the order. Max length restricted to 50 characters
`TelephoneNumberList`	Yes	A list of telephone numbers to disconnect.
`DisconnectMode`	No	The severity of disconnect order. Typically `Normal`.
`Protected`	No	Change protected status of telephones during disconnection. Possible values: `TRUE`, `FALSE`, `UNCHANGED`. Typically `UNCHANGED`.

{% common %}

Example: Create a disconnect request for 2 Phone Numbers

POST https://dashboard.bandwidth.com/api/accounts/{{accountId}}/disconnects HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: {user:password}

<?xml version="1.0"?>
<DisconnectTelephoneNumberOrder>
    <name>training run</name>
    <DisconnectTelephoneNumberOrderType>
        <TelephoneNumberList>
            <TelephoneNumber>5405514342</TelephoneNumber>
            <TelephoneNumber>7034343704</TelephoneNumber>
        </TelephoneNumberList>
    </DisconnectTelephoneNumberOrderType>
</DisconnectTelephoneNumberOrder>

Response

HTTP/1.1 201 Created
Content-Type: application/xml; charset=utf-8
Location: https://dashboard.bandwidth.com/api/accounts/{{accountId}}/disconnects/df2gc2e2-653d-466c-945d-8f292f09ce55

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<DisconnectTelephoneNumberOrderResponse>
    <orderRequest>
        <OrderCreateDate>2018-01-23T21:00:23.802Z</OrderCreateDate>
        <id>df2gc2e2-653d-466c-945d-8f292f09ce55</id>
        <DisconnectTelephoneNumberOrderType>
            <TelephoneNumberList>
                <TelephoneNumber>5405514342</TelephoneNumber>
                <TelephoneNumber>7034343704</TelephoneNumber>
            </TelephoneNumberList>
            <DisconnectMode>normal</DisconnectMode>
        </DisconnectTelephoneNumberOrderType>
    </orderRequest>
    <OrderStatus>RECEIVED</OrderStatus>
</DisconnectTelephoneNumberOrderResponse>

{% endextendmethod %}

Fetching Disconnect Information {#get-disconnect-info}

A GET Request to an existing disconnect will return it's status as well as any information originally used to create the disconnect.

Base URL

GEThttps://dashboard.bandwidth.com/api/accounts/{{accountId}}/disconnects/{{disconnectId}}

{% extendmethod %}

Query Parameters

There are no query parameters for fetching information about an existing disconnect.

{% common %}

Example: Fetch Disconnect Information

GET https://dashboard.bandwidth.com/api/accounts/{{accountId}}/disconnects/df2gc2e2-653d-466c-945d-8f292f09ce55 HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: {user:password}

Response

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<DisconnectTelephoneNumberOrderResponse>
    <DisconnectedTelephoneNumberList>
        <TelephoneNumber>5405514342</TelephoneNumber>
        <TelephoneNumber>7034343704</TelephoneNumber>
    </DisconnectedTelephoneNumberList>
    <ErrorList/>
    <orderRequest>
        <OrderCreateDate>2015-01-20T21:05:58.026Z</OrderCreateDate>
        <id>df2gc2e2-653d-466c-945d-8f292f09ce55</id>
        <DisconnectTelephoneNumberOrderType>
            <TelephoneNumberList>
                <TelephoneNumber>7034343704</TelephoneNumber>
                <TelephoneNumber>5405514342</TelephoneNumber>
            </TelephoneNumberList>
            <DisconnectMode>normal</DisconnectMode>
        </DisconnectTelephoneNumberOrderType>
    </orderRequest>
    <OrderStatus>COMPLETE</OrderStatus>
</DisconnectTelephoneNumberOrderResponse>

{% endextendmethod %}

Files

numberOrderingSummary-OLD.md

Latest commit

History

numberOrderingSummary-OLD.md

File metadata and controls

Number Ordering Summary {#top}

Assumptions

Overview

Searching For Phone Numbers {#search-for-phone-numbers}

Base URL

Query Parameters

Example: Search by NPA NXX

Response

Reserve Phone Numbers {#reserving-phone-numbers}

Base URL

Body Parameters

Example: Reserve a Phone Number

Response

Check existing Phone Numbers Reservation {#get-reserved-phone-numbers}

Base URL

Query Parameters

Example: Fetch an existing Reservation

Response

Order Phone Numbers {#order-phone-numbers}

Base URL

Common Request Parameters

Order Type Specific Request Parameters

Example 1 of 2: Order Previously Reserved Phone Numbers from a Reservation

Response

Example 2 of 2: Search AND Order 1 Number in Area Code

Response

Fetching Order Information {#get-order-info}

Base URL

Query Parameters

Example: Fetch Order Information

Response

Disconnecting a Phone Number {#disconnect-phone-number}

Base URL

Request Parameters

Example: Create a disconnect request for 2 Phone Numbers

Response

Fetching Disconnect Information {#get-disconnect-info}

Base URL

Query Parameters

Example: Fetch Disconnect Information

Response