V1 → V2 Numbers API Migration Guide

Table of Contents

Credentials

Ordering Numbers

Disconnecting Numbers

Resources

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!