Search and order Phone Numbers with Callbacks
About
This guide will walk through the recommended approach to searching and ordering phone numbers using the Bandwidth Phone Number API. This will cover how to setup a subscription to manage phone number order alerts, how to search for available phone numbers, and finally how to order phone numbers.
Differences between Polling & Callbacks
Phone number ordering in the Bandwidth Dashboard is asyncronous through creating an "order". The orders are then processed and the order status is updated asyncronously. Bandwidth recommends configuring your account with a subscription and following this guide for the most performant integration.
Use-cases
This guide is best suited for use-cases where an end-user is assigned a new specific phone number and may want to customize their phone number.
In the case where a user would like to keep their existing phone number, follow the porting guide.
Steps
- Create Subscription
- Search for Phone Numbers
- Create order for Phone Numbers
- Receive HTTP Callback with order status
- Fetch information about order (optional)
Create Subscription for Orders
The Bandwidth Phone Number API allows users to manage notifications on their account through the /subscriptions
resource. Subscriptions can be configured to send a HTTP Callback to a valid publicly addressable URL or send an email to a valid email address.
This guide only covers creating a <CallbackSubscription>
. For more information see the full guide on managing subscriptions.
Base URL
POST
https://dashboard.bandwidth.com/api/accounts/{{accountId}}/subscriptions
Basic Authentication
Bandwidth's Account API leverages Basic Authentication with your Dashboard API Credentials. Read more about how Bandwidth secures endpoints in the Security & Credentials document.
Basic Parameters
Parameter | Required | Description |
---|---|---|
<OrderType> |
Yes | The Specific type of order in which to configure the subscription. For this guide, the value is: orders |
<CallbackSubscription> |
Yes | Contains the information about the callback url |
<URL> |
Yes | The URL to send the POST request when order status changes. Part of the <CallbackSubscription> element. |
<Expiry> |
Yes | How long to keep the subscription active. Can be very large (100 years in seconds 3153600000 ) Part of the <CallbackSubscription> element. |
<CallbackCredentials> |
No | Container for the authentication credentials for the specified URL Part of the <CallbackSubscription> element. |
<BasicAuthentication> |
No | Container for Basic Authentication credentials. |
<UserName> |
No | Username for Basic Authentication scheme. Max 100 characters Part of the <BasicAuthentication> element. |
<Password> |
No | Password for Basic Authentication scheme. Encrypted at rest and never returned by the API Part of the <BasicAuthentication> element. |
<PublicKey> |
No | A BASE64 encoded public key that matches the server specified in the URL Part of the <BasicAuthentication> element. |
Example XML to Create Subscription
POST https://dashboard.../{{accountId}}/subscriptions HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
<Subscription>
<OrderType>orders</OrderType>
<CallbackSubscription>
<URL>https://your-secure-url.com</URL>
<Expiry>3153600000</Expiry>
<CallbackCredentials>
<BasicAuthentication>
<Username>User15</Username>
<Password>Hunter15</Password>
</BasicAuthentication>
<PublicKey>LS0[...]LS0tLQ0K</PublicKey>
</CallbackCredentials>
</CallbackSubscription>
</Subscription>
Searching 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. Searching only provides a list of available numbers that match the search criteria.
There are a number of search approaches that can be used; the NPA NXX search is used for this example. Please see the [guide on searching phone numbers for the other applicable search types.
Base URL
GET
https://dashboard.bandwidth.com/api/accounts/{{accountId}}/availableNumbers
Basic Authentication
Bandwidth's Phone Number API leverages Basic Authentication with your Dashboard API Credentials. Read more about how Bandwidth secures endpoints in the Security & Credentials document.
Query Parameters
Parameters | Description |
---|---|
npaNxx |
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]. |
This example only demonstrates searching by NPA NXX
to learn about the different search types and filtering see the guide on searching phone numbers.
Example: Search by NPA NXX
GET https://dashboard.bandwidth.com/api/accounts/{{accountId}}/availableNumbers?npaNxx=540551&quantity=7 HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
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>
Order Phone Numbers
- To successfully order a Phone Number that was previously returned in a search on the
/availableNumbers
you will create a<ExistingTelephoneNumberOrderType>
with a<TelephoneNumberList>
containing at least 1 phone number. - There is no guarantee that the a telephone number appearing in search results will still be available by the time an order request is processed.
- In this example, the
<TelephoneNumber>
s are known by the previous search. - It is worth noting that most orders complete very quickly (less than 1 second).
Base URL
POST
https://dashboard.bandwidth.com/api/accounts/{{accountId}}/orders
Basic Authentication
Bandwidth's Phone Number API leverages Basic Authentication with your Dashboard API Credentials. Read more about how Bandwidth secures endpoints in the Security & Credentials document.
Common Request Parameters
Parameter | Required | Description |
---|---|---|
<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 not 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 |
<TelephoneNumberList> |
Yes | A list of telephone numbers to order. |
<TelephoneNumber> |
Yes | TelephoneNumberList must have at least one TelephoneNumber to order Part of the <TelephoneNumberList> element. |
Example: Order 1 Number Returned in the Search above
POST https://dashboard.bandwidth.com/api/accounts/{{accountId}}/orders HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
<Order>
<CustomerOrderId>123456789</CustomerOrderId>
<Name>My Custom Name or UUID of a customer session</Name>
<ExistingTelephoneNumberOrderType>
<TelephoneNumberList>
<TelephoneNumber>5402278098</TelephoneNumber>
</TelephoneNumberList>
</ExistingTelephoneNumberOrderType>
<SiteId>743</SiteId>
</Order>
Response
HTTP/1.1 201 Created
Content-Type: application/xml; charset=utf-8
Location: https://dashboard.bandwidth.com/api/accounts/{{accountId}}/orders/c9dg306c-gdh7-77j7-812c-0520c8f49123
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OrderResponse>
<Order>
<CustomerOrderId>1234567896</CustomerOrderId>
<Name>Existing Number Order 3</Name>
<OrderCreateDate>2018-03-20T19:51:20.886Z</OrderCreateDate>
<BackOrderRequested>false</BackOrderRequested>
<id>c9dg306c-gdh7-77j7-812c-0520c8f49123</id>
<ExistingTelephoneNumberOrderType>
<TelephoneNumberList>
<TelephoneNumber>5402278098</TelephoneNumber>
</TelephoneNumberList>
</ExistingTelephoneNumberOrderType>
<PartialAllowed>true</PartialAllowed>
<SiteId>13606</SiteId>
</Order>
<OrderStatus>RECEIVED</OrderStatus>
</OrderResponse>
Receive HTTP Callback with Order Status
The Bandwidth Phone Number API will send a HTTP Callback (webhook) to the URL specified in the <URL>...</URL>
when creating the subscription.
The HTTP Callback will contain information if the order was successful or failed. For our example here, if status is anything other than COMPLETE
the order has failed. The most likely scenario is that another customer ordered the desired phone number between the time 'searched' and 'ordered'. If the order is not COMPLETE
, either try ordering a different phone number, or search for more numbers.
Callback Request Parameters
Parameter | Description |
---|---|
<Status> |
Following this tutorial should only yield two possible Status values: - COMPLETE : The order succeeded and all phone numbers requested were ordered and will be sent in the <CompletedTelephoneNumbers> list. - FAILED : The order did not succeed (at least 1 phone number sent in the order was unable to be ordered). To learn more about the order states, see the Advanced Ordering Overview |
<SubscriptionId> |
The unique Id associated with the subscription that was configured for orders . This is the same value that is returned in Location Header when creating the subscription. |
<Message> |
A specific message related to the order. |
<OrderId> |
The unique Id associated with the order. This is the same value that is returned in the Location Header when creating the order |
<OrderType> |
The specific type of order that was created. For this example, the value will be orders . For more information see managing subscriptions |
<CompletedTelephoneNumbers> |
Contains the list of Phone Numbers that were attempted to be ordered. |
<TelephoneNumber> |
The actual Phone Number that was attempted to be ordered. Part of the <CompletedTelephoneNumbers> element. |
Example: Successful Phone Number Order
POST https://your-server.com HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Notification>
<Status>COMPLETE</Status>
<SubscriptionId>d8274fa6-e49b-469a-93bf-c7dd17615950</SubscriptionId>
<Message>Created a new number order for 1 number from WASHINGTON, VA</Message>
<OrderId>a8ef295b-fcf4-44a7-945c-0520c8f49123</OrderId>
<OrderType>orders</OrderType>
<CompletedTelephoneNumbers>
<TelephoneNumber>5402278098</TelephoneNumber>
</CompletedTelephoneNumbers>
</Notification>
Example: Failed Phone Number Order
POST https://your-server.com HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Notification>
<Status>FAILED</Status>
<SubscriptionId>333643f0-3eac-4c8f-8b15-c712f49e09fe</SubscriptionId>
<Message>5005: The telephone number is unavailable for ordering</Message>
<OrderId>4a58b348-892c-4426-8900-97fc4555c42c</OrderId>
<OrderType>orders</OrderType>
<CompletedTelephoneNumbers>
<TelephoneNumber>5402278098</TelephoneNumber>
</CompletedTelephoneNumbers>
</Notification>
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.
In the example below the orderId
is the orderId
returned in the 'location' header of the order phone numbers response.
Base URL
GET
https://dashboard.bandwidth.com/api/accounts/{{accountId}}/orders/{{orderId}}
Basic Authentication
Bandwidth's Phone Number API leverages Basic Authentication with your Dashboard API Credentials. Read more about how Bandwidth secures endpoints in the Security & Credentials document.
Query Parameters
There are no query parameters for fetching information about an existing order.
Example: Fetch Order Information
GET https://dashboard.bandwidth.com/api/accounts/{{accountId}}/orders/4a58b348-892c-4426-8900-97fc4555c42c HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Example: Successful Order Response
For this example, look for OrderStatus == COMPLETED and the CompletedNumbers list, and CompletedQuantity == 1 to verify the order was successful.
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OrderResponse>
<CompletedQuantity>1</CompletedQuantity>
<CreatedByUser>jbm</CreatedByUser>
<ErrorList/>
<FailedNumbers/>
<LastModifiedDate>2018-03-21T15:28:06.438Z</LastModifiedDate>
<OrderCompleteDate>2018-03-21T15:28:06.438Z</OrderCompleteDate>
<Order>
<CustomerOrderId>123456789</CustomerOrderId>
<Name>Existing Number Order</Name>
<OrderCreateDate>2018-03-21T15:28:06.359Z</OrderCreateDate>
<PeerId>546348</PeerId>
<BackOrderRequested>false</BackOrderRequested>
<ExistingTelephoneNumberOrderType>
<TelephoneNumberList>
<TelephoneNumber>5405511247</TelephoneNumber>
</TelephoneNumberList>
</ExistingTelephoneNumberOrderType>
<PartialAllowed>true</PartialAllowed>
<SiteId>13606</SiteId>
</Order>
<OrderStatus>COMPLETE</OrderStatus>
<CompletedNumbers>
<TelephoneNumber>
<FullNumber>5405511247</FullNumber>
</TelephoneNumber>
</CompletedNumbers>
<Summary>1 number ordered in (540)</Summary>
<FailedQuantity>0</FailedQuantity>
</OrderResponse>
Example: Unsuccessful Order Response
Otherwise, note that OrderStatus == FAILED, the Error Description text, and the FailedNumbers list.
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OrderResponse>
<CompletedQuantity>0</CompletedQuantity>
<CreatedByUser>jbm</CreatedByUser>
<ErrorList>
<Error>
<Code>5005</Code>
<Description>The telephone number is unavailable for ordering</Description>
<TelephoneNumber>5402278098</TelephoneNumber>
</Error>
</ErrorList>
<FailedNumbers>
<FullNumber>5402278098</FullNumber>
</FailedNumbers>
<LastModifiedDate>2018-03-21T15:20:36.212Z</LastModifiedDate>
<OrderCompleteDate>2018-03-21T15:20:36.212Z</OrderCompleteDate>
<Order>
<CustomerOrderId>1234567896</CustomerOrderId>
<Name>Existing Number Order 234</Name>
<OrderCreateDate>2018-03-21T15:20:36.153Z</OrderCreateDate>
<PeerId>546348</PeerId>
<BackOrderRequested>false</BackOrderRequested>
<ExistingTelephoneNumberOrderType>
<TelephoneNumberList>
<TelephoneNumber>5402278098</TelephoneNumber>
</TelephoneNumberList>
</ExistingTelephoneNumberOrderType>
<PartialAllowed>true</PartialAllowed>
<SiteId>13606</SiteId>
</Order>
<OrderStatus>FAILED</OrderStatus>
<CompletedNumbers/>
<Summary>1 number requested</Summary>
<FailedQuantity>1</FailedQuantity>
</OrderResponse>