Skip to main content

Order Numbers

Ordering phone numbers is a simple process with Bandwidth's Universal Platform (UP). You can search for numbers by country, area code, and more, and purchase them directly through our API. This guide will help you understand the steps and options for ordering numbers using your Bandwidth account.

Prerequisites​

Before ordering there are a couple of things to consider and verify:

  • The user account placing the order must be active and have the Ordering user role assigned.
  • You have created a Sub-account (Site) and Location (Sip-Peer) where your numbers will reside. Learn more about our Account Structure.
  • Your account may have restrictions on which Countries and Number Types you may order.
  • Some Countries and Number Types may have strict Restrictions and Requirements.

Country Restrictions API​

The Country Restrictions API allows you to query for restrictions for a specific country.

Request​

GET https://api.bandwidth.com/api/v2/restrictions?countryCodeA3=ITA
Authorization: Bearer mySecretToken

Response​

<?xml version='1.0' encoding='UTF-8' standalone='yes'?>
<RestrictionResponse>
    <Restrictions>
        <Restriction>
            <CountryCodeA3>ITA</CountryCodeA3>
            <RestrictionCategory>Sub allocation</RestrictionCategory>
            <RestrictionDescription>Customers providing Electronic Communication Services must be registered operators with the local regulator and must provide these services to end users.</RestrictionDescription>
            <RestrictionType>LEGAL</RestrictionType>
        </Restriction>
        <Restriction>
            <CountryCodeA3>ITA</CountryCodeA3>
            <RestrictionCategory>Others</RestrictionCategory>
            <RestrictionDescription>Customers or end users conducting call center activities must be notified/registered operators with the local regulator.</RestrictionDescription>
            <RestrictionType>LEGAL</RestrictionType>
        </Restriction>
        <!-- Additional restrictions -->
        <Restriction>
            <CountryCodeA3>ITA</CountryCodeA3>
            <RestrictionCategory>Outbound call</RestrictionCategory>
            <RestrictionDescription>Enhanced Voice Transit does not support access to Emergency Services.</RestrictionDescription>
            <RestrictionType>SERVICE</RestrictionType>
        </Restriction>
        <Restriction>
            <CountryCodeA3>ITA</CountryCodeA3>
            <RestrictionCategory>Outbound call</RestrictionCategory>
            <RestrictionDescription>Customer shall not send traffic through the Enhanced Voice Transit feature to Bandwidth's network from numbers not permitted to originate calls, short codes, specialized service numbers, Emergency Service numbers and Premium Rate numbers as designated as such by the National numbering plan.</RestrictionDescription>
            <RestrictionType>SERVICE</RestrictionType>
        </Restriction>
    </Restrictions>
</RestrictionResponse>
tip

Country requirements are also visible in the Dashboard under the Service Management > Restrictions and Requirements area.

Searching for Numbers​

The API provides filters to identify a set of available numbers to order. Based on the prerequisite step of identifying the Country and Number Type you can retrieve a set of available numbers.

The /availableNumbers endpoint is used, along with query parameters, to find numbers available to purchase.

Searching for International Numbers​

Query Parameters​

note

countryCodeA3 is required parameter for all Non-NANP searches

Search telephone numbers for a specific country

Search TypeRequired ParametersCombination ParametersOptional Parameters
CountrycountryCodeA3numberType, areaCode, cityquantity, enableTNDetail, protected

Example​

https://api.bandwidth.com/api/v2/accounts/{accountId}/availableNumbers?countryCodeA3=DEU&quantity=5

Request​

With this request we can find 5 United Kingdom, Geographic available numbers to purchase.

GET https://api.bandwidth.com/api/v2/accounts/{accountId}/availableNumbers?countryCodeA3=GBR&phoneNumberType=GEOGRAPHIC&quantity=5
Authorization: Bearer mySecretToken

Response​

<?xml version='1.0' encoding='UTF-8' standalone='yes'?>
<SearchResult>
    <ResultCount>5</ResultCount>
    <TelephoneNumberList>
        <TelephoneNumber>+441224003908</TelephoneNumber>
        <TelephoneNumber>+441224003995</TelephoneNumber>
        <TelephoneNumber>+441224003996</TelephoneNumber>
        <TelephoneNumber>+441224003997</TelephoneNumber>
        <TelephoneNumber>+441224003998</TelephoneNumber>
    </TelephoneNumberList>
</SearchResult>

Searching for North America Numbering Plan (NANP) Numbers​

The availableNumbers endpoint provides a variety of filters specific to NANP numbers. These can be combined to provide very narrow search results for available numbers.

Query Parameters​

Search telephone numbers for a specific Area Code

Search TypeRequired ParametersCombinational ParametersOptional Parameters
Area CodeareaCode

rateCenter (state required), city (state required), state, lata, zip

quantity, enableTNDetail, protected
Request​
GET https://api.bandwidth.com/api/v2/accounts/{accountId}/availableNumbers?countryCodeA3=USA&quantity=5&city=Raleigh&state=NC
Authorization: Bearer mySecretToken
Response​
<?xml version='1.0' encoding='UTF-8' standalone='yes'?>
<SearchResult>
    <ResultCount>5</ResultCount>
    <TelephoneNumberList>
        <TelephoneNumber>+19842471432</TelephoneNumber>
        <TelephoneNumber>+19842471793</TelephoneNumber>
        <TelephoneNumber>+19842471794</TelephoneNumber>
        <TelephoneNumber>+19842471827</TelephoneNumber>
        <TelephoneNumber>+19842471828</TelephoneNumber>
    </TelephoneNumberList>
</SearchResult>

Ordering Numbers​

warning

Inventory is first-come first-serve. At any point in your search and order flow, it is possible that another customer may order the number you are looking for. If this happens, the order will enter a FAILED or PARTIAL state with an error indicating that the number is no longer available.

Additionally - order processing time is not guaranteed. It is possible that order processing times may vary. Your integration should be able to handle these scenarios by ensuring orders are in a COMPLETED state before attempting modify configurations or call/send messages to/from these numbers.

After identifying available numbers now it is time to purchase them via the /orders endpoint. This endpoint creates an asynchronous order on your account.

Example​

Request​
POST https://api.bandwidth.com/api/v2/accounts/{accountId}/orders
Authorization: Bearer mySecretToken
Content-Type: application/xml

<Order>
    <CustomerOrderId>123456789</CustomerOrderId>
    <Name>UK Number Order</Name>
    <ExistingTelephoneNumberOrderType>
        <TelephoneNumberList>
            <TelephoneNumber>+441224003845</TelephoneNumber>
        </TelephoneNumberList>
    </ExistingTelephoneNumberOrderType>
    <SiteId>{siteId}</SiteId>
    <VoiceConfigurationPackageId>d21315af-9b5b-4b45-a6f4-9106cbfe87d1</VoiceConfigurationPackageId>
    <RequirementsPackageId>3fa85f64-5717-4562-b3fc-2c963f66afa6</RequirementsPackageId>
    <AutoActivate>true</AutoActivate>
</Order>

Important Elements in the Request​

  • SiteId - this is the Site (Sub-Account) the number will be put into - using the default Location (Sip-Peer). These are used for grouping and managing your number number inventory. Learn more about Account Structure
  • VoiceConfigurationPackageId - if you would like to associate a Voice Configuration with the number during the ordering process you can use this optional parameter. Learn more about Voice Configuration Packages
  • RequirementsPackageId - if you would like to associate a Requirements Package with the number during the ordering process you can use this optional parameter. Learn more about Requirements Packages
  • AutoActivate - an optional parameter that, if all required information is provided and validated, will activate services on the ordered number(s). Learn more about Service Activation

For non-NANP numbers, you can specify an existing Requirements Pacakge and Voice Configuration Package, so that services can be automatically activated on your numbers when the order completes.

note

Ordering telephone numbers is asynchronous. You will receive a response with an order ID, which you can use to check the status of your order.

Additionally - you can subscribe to webhooks to receive updates on the status of your order.

Response​
<?xml version='1.0' encoding='UTF-8' standalone='yes'?>
<OrderResponse>
    <Order>
        <CustomerOrderId>123456789</CustomerOrderId>
        <Name>UK Number Order</Name>
        <OrderCreateDate>2024-09-05T23:34:31.553Z</OrderCreateDate>
        <AutoActivate>true</AutoActivate>
        <BackOrderRequested>false</BackOrderRequested>
        <id>0aac5809-a57f-4cf8-a5ad-d0c458e6e317</id>
        <ExistingTelephoneNumberOrderType>
            <TelephoneNumberList>
                <TelephoneNumber>+448000488968</TelephoneNumber>
            </TelephoneNumberList>
        </ExistingTelephoneNumberOrderType>
        <PartialAllowed>true</PartialAllowed>
        <SiteId>{siteId}</SiteId>
    </Order>
    <OrderStatus>RECEIVED</OrderStatus>
</OrderResponse>

Additional Ordering Capabilities for NANP Numbers​

Bandwidth provides some additional capabilities when ordering North American Numbering Plan numbers. These include:

  • Reserving available numbers for up to 4 hours
  • Using backorder to order numbers when they become available

Checking the Status of your Order​

Once your order is placed you can check the status of the order using the orderId provided in the original order response.

Request​

GET https://api.bandwidth.com/api/v2/accounts/{accountId}/orders/{orderId}
Authorization: Bearer mySecretToken

Response​

<?xml version='1.0' encoding='UTF-8' standalone='yes'?>
<OrderResponse>
    <CompletedQuantity>0</CompletedQuantity>
    <CreatedByUser>universal-platform-user</CreatedByUser>
    <CompletedNumbers>
        <FullNumber>+448000488968</FullNumber>
    </CompletedNumbers>
    <LastModifiedDate>2024-09-05T23:34:33.306Z</LastModifiedDate>
    <OrderCompleteDate>2024-09-05T23:34:33.306Z</OrderCompleteDate>
    <Order>
        <CustomerOrderId>123456789</CustomerOrderId>
        <Name>Existing UK Number Order</Name>
        <OrderCreateDate>2024-09-05T23:34:31.553Z</OrderCreateDate>
        <PeerId>{sippeerId}</PeerId>
        <AutoActivate>true</AutoActivate>
        <BackOrderRequested>false</BackOrderRequested>
        <ExistingTelephoneNumberOrderType>
            <TelephoneNumberList>
                <TelephoneNumber>+448000488968</TelephoneNumber>
            </TelephoneNumberList>
        </ExistingTelephoneNumberOrderType>
        <PartialAllowed>true</PartialAllowed>
        <SiteId>{siteId}</SiteId>
    </Order>
    <OrderStatus>COMPLETED</OrderStatus>
    <Summary>1 number requested</Summary>
    <FailedQuantity>1</FailedQuantity>
</OrderResponse>

Whats Next?​

Need help? Reach out to our team for dev tips
Contact Us
Our Company
About UsBlogContactNewsroomCareersInvestor RelationsLeadership
Quicklinks
SupportService StatusDevelopersResourcesSecurityPartner ProgramCustomersRelease NotesGlossaryTwilio AlternativeRegulations
Legal
GeneralAccessibilityLaw Enforcement GuideBandwidth Privacy NoticeReport a Phone NumberCookie NoticeTerms of Use
Request trialTalk to an expert
Call Us
+1 800 808 5150
Bandwidth.com CLEC, LLC is a wholly owned subsidiary of Bandwidth Inc. ©2024