V1 → V2 Numbers API Migration Guide
FollowTable of Contents
Credentials
V1 and V2 both use Basic Auth. In V1, the only credentials you need are token and a secret. In V2, you'll use a token and a secret to create and send messages. You can get these credentials from the Applications page in the Dashboard. In addition, for number management functions in V2, you'll use the username and password for a user on your V2 account as your credentials.
Ordering Numbers
Ordering numbers is very different in V2 compared to V1. In V1, searching for a number looks like:
GET
https://api.catapult.inetwork.com/v1/availableNumbers/local?areaCode={{area_code}}&quantity=1
Authorization: Basic {{token_secret_encoded}}
And the response to this search looks like:
[
{
"number": "{{number1}}",
"nationalNumber": "{{national_number1}}",
"city": "{{city}}",
"lata": "{{lata}}",
"rateCenter": "{{rate_center}}",
"state": "{{state}}",
"price": "{{price}}"
}
In V2, ordering numbers is an asynchronous process. First, searching for numbers looks like:
GET
https://dashboard.bandwidth.com/api/accounts/{{accountId}}/availableNumbers?npaNxx=540551&quantity=7
Authorization: Basic {{user_password_encoded}}
With a response that looks like:
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>
While ordering a number looks like:
POST
https://dashboard.bandwidth.com/api/accounts/{{accountId}}/orders
Content-Type: application/xml
Authorization: Basic {{user_password_encoded}}
<Order>
<AreaCodeSearchAndOrderType>
<AreaCode>910</AreaCode>
<Quantity>1</Quantity>
</AreaCodeSearchAndOrderType>
<SiteId>461</SiteId>
</Order>
With a response that looks like:
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>
Because this is an asynchronous process, the 201 Created response doesn't mean the number is fully purchased. Here's how you can check the status of the order:
GET
https://dashboard.bandwidth.com/api/accounts/{{accountId}}/orders/d30eda5a-ce10-456e-8cb9-eb13b9f14cfd
Authorization: Basic {{user_password_encoded}}
With a response that looks like:
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>
<LastModifiedDate>2018-01-23T19:56:29.782Z</LastModifiedDate>
<OrderCompleteDate>2018-01-23T19:56:29.782Z</OrderCompleteDate>
<Order>
<OrderCreateDate>2018-01-23T19:56:29.678Z</OrderCreateDate>
<PeerId>651681</PeerId>
<BackOrderRequested>false</BackOrderRequested>
<AreaCodeSearchAndOrderType>
<AreaCode>910</AreaCode>
<Quantity>1</Quantity>
</AreaCodeSearchAndOrderType>
<PartialAllowed>true</PartialAllowed>
<SiteId>24717</SiteId>
</Order>
<OrderStatus>COMPLETE</OrderStatus>
<CompletedNumbers>
<TelephoneNumber>
<FullNumber>9102414365</FullNumber>
</TelephoneNumber>
</CompletedNumbers>
<Summary>1 number ordered in (910)</Summary>
<FailedQuantity>0</FailedQuantity>
</OrderResponse>
There are many different ways to search for phone numbers. To learn more, go to API Methods, select 'Accounts' and scroll down to the endpoint “/accounts /{accountId} /orders." Click it to find information about all different phone number purchasing order types.
Disconnecting Numbers
Disconnecting a number in V1 looks like:
DELETE https://api.catapult.inetwork.com/v1/users/{{userId}}/phoneNumbers/{{numberId}}
Authorization: Basic {{token_secret_encoded}}
Disconnecting a number in V2 is an asynchronous process that looks like:
POST https://dashboard.bandwidth.com/api/accounts/{{accountId}}/disconnects
Content-Type: application/xml
Authorization: Basic {{user_password_encoded}}
<?xml version="1.0"?>
<DisconnectTelephoneNumberOrder>
<name>training run</name>
<DisconnectTelephoneNumberOrderType>
<TelephoneNumberList>
<TelephoneNumber>5405514342</TelephoneNumber>
<TelephoneNumber>7034343704</TelephoneNumber>
</TelephoneNumberList>
</DisconnectTelephoneNumberOrderType>
</DisconnectTelephoneNumberOrder>
The response to this request looks like:
201 Created
Content-Type: application/xml
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>
Resources
Check out our Developer Docs for additional documentation.
Still have questions? Open a ticket with our support team. We're here to help!
Was this article helpful?
1 out of 3 found this helpful
Article is closed for comments.