V1 → V2 Numbers API migration guide

Follow

Samantha Capps

Updated

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 your API username and password for a user on your 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. Questions? Please open a ticket with your Bandwidth Support Team or hit us up at (855) 864-7776!

Article is closed for comments.