Skip to main content

Ordering Numbers

This guide will take you through the basics of ordering phone numbers with the Bandwidth Dashboard API.

Polling vs. Webhooks#

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.

Order Phone Numbers#

Ordering Phone Numbers for use with the network allows you to provosion specific phone numbers from available inventory that have been discovered in a search.

Possible Order Types#

The Dashboard API allows you to submit different order types in your API request body to order numbers based on different requirements.

Order TypeDescription
ExistingTelephoneNumberOrderTypeOrder a known, available number or set of numbers
AreaCodeSearchAndOrderTypeOrder an unknown number or group of numbers from the same Area Code
RateCenterSearchAndOrderTypeOrder an unknown number or group of numbers from the same Rate Center
NPANXXSearchAndOrderTypeOrder an unknown number or group of numbers from the same NPANxx
TollFreeVanitySearchAndOrderTypeOrder an unknown toll-free number or group of toll-free numbers from that follow a specified vanity pattern
TollFreeWildCharSearchAndOrderTypeOrder an unknown toll-free number or group of toll-free numbers from any toll-free area code (ex. 8* or 83)
StateSearchAndOrderTypeOrder an unknown number or group of numbers from the same state
CitySearchAndOrderTypeOrder an unknown number or group of numbers from the same city
ZIPSearchAndOrderTypeOrder an unknown number or group of numbers from the same zip code
LATASearchAndOrderTypeOrder an unknown number or group of numbers from the same LATA
CombinedSearchAndOrderTypeOrder an unknown number or group of numbers from a combination of search parameters

To see specific examples of each order type, please visit the Dashboard API Reference.

Request URL#

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

Common Request Parameters#

EVERY type of order can/must include the parameters below

ParameterRequiredDescription
QuantityNoThe desired quantity of requested numbers. values range from 1-5000. Default: 5000
CustomerOrderIdNoOptional value for Id set by customer
SiteIdYesThe ID of the Site (Sub-Account) that the SIP Peer is to be associated with.
PeerIdNoThe ID of the SIP Peer (Location) that the telephone numbers are to be assigned to.
PartialAllowedNoBy 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
BackOrderRequestedNoBackOrderRequested 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

ParameterDescription
TelephoneNumberListA list of telephone numbers to order
AreaCodeAllowed ranged: [2-9] for the first digit and [0, 9] for both the second and third digits.
RateCenterA text Rate Center name. Must be combined with State information
StateThe two-letter abbreviation of the state
CityThe name of the city that the Ordered telephone numbers should apply to
ZipA five-digit (XXXXX) or nine-digit (XXXXX-XXXX) format value.
LataA maximum five-digit (XXXXX) numeric format.
EnableLCAIf 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 : trueNpaNxx 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.
LocalVanityA text string used to request a regular vanity number. Valid range is between 4 and 7 alphanumeric characters.
EndsInIntended 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
TollFreeVanityA text string used to request a toll free vanity number. Valid range is between 4 and 7 alphanumeric characters.
TollFreeWildCardPatternA 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
ReservationIdListIf 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.
TnAttributesAttributes to be assigned to the telephone number. Optional parameter. Possible values: Protected

Examples#

Search and Order 1 Number in a specific Area Code

Request

POST https://dashboard.bandwidth.com/api/accounts/{accountId}/orders HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
<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>

Fetching Order Information#

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

Request URL#

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

Examples#

Order Status Webhook

info

This is a webhook that bandwidth sends to your server upon order completion/failure - there is no need to poll the resource if using this recommended method.

POST your_url.com/webhookService HTTP/1.1
Content-Type: application/xml; charset=utf-8
<?xml version="1.0"?>
<Notification>
<SubscriptionId>...</SubscriptionId>
<OrderType>OrderId</OrderType>
<CustomerOrderId>...</CustomerOrderId>
<Status>COMPLETE</Status>
<CompletedTelephoneNumbers>
<TelephoneNumber> ... </TelephoneNumber>
</CompletedTelephoneNumbers>
</Notification>