Skip to main content

Breaking Changes

This guide provides an overview of the changes and breaking changes that have been made to the Bandwidth Number Management APIs as part of the upgrade to the Universal Platform. This includes all APIs at https://dashboard.bandwidth.com/api

Whats New​

  • New Base URL (https://api.bandwidth.com/api/v2)
  • 60+ country support on a single API
  • countryCodeA3 and phoneNumberType are first-class parameters
  • New resource groups for country-specific compliance
    • Voice Configuration Packages
    • Requirements Packages
    • Service Activation
    • All net-new resource groups support JSON

Overview of Changes​

  • All phone numbers are in E.164 format
    • This is true for requests, responses, callbacks, and reports
  • GET /api/v1/addresses is now GET /api/v2/e911Addresses
  • /api/v1/accounts/{accountId}/importTnOrders is moving to /api/v2/accounts/{accountId}/importTnOrders/messaging
    • /api/v1/accounts/{accountId}/externalTns is deprecated
  • Usage of the ?areaCode= query parameter now requires countryCodeA3= to be included
  • All previously deprecated v1 endpoints are no longer supported

Migrating​

Authorization​

The Bandwidth APIs support Bearer Authentication. It is reccommended to use Bearer tokens for authentication.

See the Credentials Guide for more information.

Base Path​

Update your base path to https://api.bandwidth.com/api/v2.

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

Requests​

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

curl -X POST 'https://api.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 phone numbers in E.164 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 by including <NumberFormat>LEGACY</NumberFormat> in the request.

curl -X POST 'https://api.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 phone numbers in E.164 format. This is the preferred option.

Iris Phone 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://api.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://api.bandwidth.com/api/v2/accounts/{accountId}/e911Addresses'
-u '{userName}:{password}'

Hosted Messaging​

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

curl 'https://api.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://api.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://api.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://api.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://api.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​

note

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.

  • 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.
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