Skip to main content

Migrating to API V2

Base Path​

Update your base path to /api/v2.

https://dashboard.bandwidth.com/api/v2/

Requests​

Add +1 to all phone numbers passed to our APIs.

curl -X POST 'https://dashboard.bandwidth.com/api/v2/accounts/{accountId}/orders'
-u '{userName}:{password}'
-H 'Content-Type: application/xml'
-d '<Order>
        <SiteId>461</SiteId>
        <PartialAllowed>true</PartialAllowed>
        <ExistingTelephoneNumberOrderType>
            <TelephoneNumberList>
                <TelephoneNumber>+16672286710</TelephoneNumber>
                <TelephoneNumber>+15756186700</TelephoneNumber>
            </TelephoneNumberList>
        </ExistingTelephoneNumberOrderType>
    </Order>'

Responses​

Expect a +1 prefix on all phone numbers returned by our API responses.

<?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>
        <ExistingTelephoneNumberOrderType>
            <TelephoneNumberList>
                <TelephoneNumber>+16672286710</TelephoneNumber>
                <TelephoneNumber>+15756186700</TelephoneNumber>
            </TelephoneNumberList>
        </ExistingTelephoneNumberOrderType>
        <PartialAllowed>true</PartialAllowed>
        <SiteId>461</SiteId>
    </Order>
    <OrderStatus>RECEIVED</OrderStatus>
</OrderResponse>

Callbacks​

You can chose one of 2 options.

Update callback handler​

Update your callback handlers to expect telephone numbers in E164 format. This is the preferred option.

POST your_url.com/webhookService HTTP/1.1
Content-Type: application/xml; charset=utf-8

<?xml version="1.0"?>
<Notification>
    <SubscriptionId>...</SubscriptionId>
    <OrderType>OrderId</OrderType>
    <CustomerOrderId>...</CustomerOrderId>
    <Status>COMPLETE</Status>
    <CompletedTelephoneNumbers>
        <TelephoneNumber>+16672286710</TelephoneNumber>
    </CompletedTelephoneNumbers>
    <LastModifiedDate>2023-09-12T15:11:31.705Z</LastModifiedDate>
    <ActualFocDate>2023-09-12T00:00:00Z</ActualFocDate>
</Notification>

Update subscriptions request​

Alternatively, configure /api/v2/subscriptions to receive callback and email notifications with numbers in a 10-digit format.

curl -X POST 'https://dashboard.bandwidth.com/api/v2/accounts/{accountId}/subscriptions'
-u '{userName}:{password}'
-H 'Content-Type: application/xml'
-d '<Subscription>
        <OrderType>orders</OrderType>
        <CallbackSubscription>
            <URL>[valid publically addressable URL]</URL>
            <Expiry>3122064000</Expiry>
            <NumberFormat>LEGACY</NumberFormat>
            <CallbackCredentials>
                <BasicAuthentication>
                    <Username>[username]</Username>
                    <Password>[password]</Password>
                </BasicAuthentication>
                <PublicKey>kQgQ0VSVElGSUNBVEUtLS0tLQ0K</PublicKey>
            </CallbackCredentials>
        </CallbackSubscription>
    </Subscription>'

Reports​

You can chose one of 2 options.

Update report handler​

Update your CSV report processing to expect telephone numbers in E164 format. This is the preferred option.

Iris Telephone Number Inventory Report
+441224003018
+441224003020
+441962418907
+61870933122
+12565806460
+13048255495

Update report request​

Alternatively, configure /api/v2/reports to download reports with numbers in a 10-digit format.

curl -X POST 'https://dashboard.bandwidth.com/api/v2/accounts/{accountId}/reports/{reportId}/instances'
-u '{userName}:{password}'
-H 'Content-Type: application/xml'
-d '<Instance>
        <OutputFormat>pdf</OutputFormat>
        <NumberFormat>LEGACY</NumberFormat>
        <Parameters>
            <Parameter>
                <Name>Account</Name>
                <Value>1</Value>
            </Parameter>
            <Parameter>
                <Name>Sub-account</Name>
                <Value>1</Value>
            </Parameter>
            <Parameter>
                <Name>MultiValueEnum</Name>
                <Value>value1</Value>
                <Value>value2</Value>
            </Parameter>
        </Parameters>
        <ExpiresAt>2020-11-25</ExpiresAt>
    </Instance>'

E911 Addresses​

Replace GET /accounts/{accountId}/addresses with GET /accounts/{accountId}/e911Addresses. This change allows us to use the original endpoint for reusable addresses.

curl 'https://dashboard.bandwidth.com/api/v2/accounts/{accountId}/e911Addresses'
-u '{userName}:{password}'

Hosted Messaging​

Replace /accounts/{accountId}/importTnOrders with /accounts/{accountId}/importTnOrders/messaging.

curl 'https://dashboard.bandwidth.com/api/v2/accounts/{accountId}/importTnOrders/messaging'
-u '{userName}:{password}'

ExternalTNs​

Replace use of /externalTns with /importTnOrders/messaging for new inventory.

Add hosted messaging on external phone numbers

curl -X POST 'https://dashboard.bandwidth.com/api/v2/accounts/{accountId}/importTnOrders/messaging'
-u '{userName}:{password}'
-H 'Content-Type: application/xml'
-d '<ExternalTnsOrder>
        <CustomerOrderId>ICPA123ABC</CustomerOrderId>
        <SiteId>743</SiteId>
        <SipPeerId>303716</SipPeerId>
        <LoaType>[ CARRIER | SUBSCRIBER ]</LoaType>
        <TelephoneNumbers>
            <TelephoneNumber>+19199918388</TelephoneNumber>
            <TelephoneNumber>+14158714245</TelephoneNumber>
            <TelephoneNumber>+14352154439</TelephoneNumber>
            <TelephoneNumber>+14352154466</TelephoneNumber>
        </TelephoneNumbers
    </ExternalTnsOrder>'

Removed hosted messaging phone numbers

curl -X POST 'https://dashboard.bandwidth.com/api/v2/accounts/{accountId}/removeImportedTnOrders/messaging'
-u '{userName}:{password}'
-H 'Content-Type: application/xml'
-d '<RemoveImportedTnOrder>
        <CustomerOrderId>ICPA123ABC</CustomerOrderId>
        <TelephoneNumbers>
            <TelephoneNumber>+19199918388</TelephoneNumber>
            <TelephoneNumber>+14158714245</TelephoneNumber>
            <TelephoneNumber>+14352154439</TelephoneNumber>
            <TelephoneNumber>+14352154466</TelephoneNumber>
        </TelephoneNumbers
    </RemoveImportedTnOrder>'

AreaCode Queries​

For all API requests that pass an areaCode query filter, add a countryCodeA3={countryCodeA3} filter. An area code without a country code is not globally unique when the system supports multiple countries.

curl 'https://dashboard.bandwidth.com/api/v2/accounts/{accountId}/inserviceNumbers?countryCodeA3=USA&areaCode=919'
-u '{userName}:{password}'

Messaging service updates in location settings​

Replace messaging status updates in CREATE and UPDATE /sippeers/{sippeerId}/tns with a /tnoptions call.

Request when API version is v2

curl 'https://dashboard.bandwidth.com/api/v2/accounts/{{accountId}}/sites/{{siteId}}/sippeers/{{sippeerId}}/tns/{{tn}}'
-u '{userName}:{password}'

Response 400 BAD Request

    <SipPeerTelephoneNumberResponse>
      <ResponseStatus>
        <ErrorCode>400</ErrorCode>
        <Description>Messaging service needs to be enabled/disabled via a TN Option order</Description>
      </ResponseStatus>
    </SipPeerTelephoneNumberResponse>

Breaking Changes​

  • The filter on area codes now enforces a country code filter as a part of its checks. This is to ensure adherence to the new e164 format.
  • The e911 address is moving from /addresses to /e911addresses to make room for new additions at that route
  • V2 now handles area codes as strings to accommodate international area codes that include a leading zero. The string will encompass both the country and area code. i.e. +270985556666 would have a string portion containing “+27098” and an integer with the value 5556666.

Turning on and off Messaging service must now be done through Service Activation orders​

  • Messaging service can no longer be turned on and off via the /sippeers/tns endpoint, use TN Option orders instead.
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