Upgrading to E.164

A Universal Platform account is not required to take advantage of E.164 Phone Numbers in the v2 API.

What is E.164?

E.164 is an international standard that defines the format of phone numbers. It establishes a country code, area code, and subscriber number. E.164 phone numbers are formatted as +[country code][area code and subscriber number] and can have a maximum of 15 digits.

How to Utilize E.164 Phone Numbers in the v2 API

The v2 API requires all phone numbers to be in E.164 format. This means that all phone numbers must be prefixed with a + and the country code.

This change also affects CSV reports generated by the /reports and /billingReports APIs. Reports generated using the v2 API will display telephone numbers in E.164 format.

To take advantage of this format in v2 - simply follow these steps to migrate your existing integration to utilize E.164 format:

Ensure your requests are being sent to the v2 API at api.bandwidth.com/api/v2
Recreate your subscriptions using the v2 API
- Subscriptions created using the v1 API will send and receive phone numbers in 10-digit format
- Subscriptions created using the v2 API will send and receive phone numbers in E.164 format
Update your codebase to send E.164 telephone numbers in requests and expect E.164 telephone numbers in responses

note

With the v2 API, any usage of the areaCode query parameter now requires that countryCodeA3 is also included in the request.

Examples

Requests

POST https://dashboard.bandwidth.com/api/v1/accounts/{accountId}/orders HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

<?xml version="1.0" encoding="UTF-8"?>
<Order>
    <CustomerOrderId>MyTestOrderId</CustomerOrderId>
    <ExistingTelephoneNumberOrderType>
        <TelephoneNumberList>
            <TelephoneNumber>2125551234</TelephoneNumber>
            <TelephoneNumber>9195555710</TelephoneNumber>
        </TelephoneNumberList>
    </ExistingTelephoneNumberOrderType>
    <SiteId>{siteId}</SiteId>
    <PeerId>{sippeerId}</PeerId>
    <PartialAllowed>false</PartialAllowed>
</Order>

POST https://api.bandwidth.com/api/v2/accounts/{accountId}/orders HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

<?xml version="1.0" encoding="UTF-8"?>
<Order>
    <CustomerOrderId>MyTestOrderId</CustomerOrderId>
    <ExistingTelephoneNumberOrderType>
        <TelephoneNumberList>
            <TelephoneNumber>+12125551234</TelephoneNumber>
            <TelephoneNumber>+19195005710</TelephoneNumber>
        </TelephoneNumberList>
    </ExistingTelephoneNumberOrderType>
    <SiteId>{siteId}</SiteId>
    <PeerId>{sippeerId}</PeerId>
    <PartialAllowed>false</PartialAllowed>
</Order>

Responses

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OrderResponse>
    <Order>
        <CustomerOrderId>MyTestOrderId</CustomerOrderId>
        <OrderCreateDate>2018-01-23T19:56:29.678Z</OrderCreateDate>
        <BackOrderRequested>false</BackOrderRequested>
        <id>47955555-67aa-4adb-8c0f-b6894e60c0dc</id>
        <ExistingTelephoneNumberOrderType>
            <TelephoneNumberList>
                <TelephoneNumber>2125551234</TelephoneNumber>
                <TelephoneNumber>9195555710</TelephoneNumber>
            </TelephoneNumberList>
        </ExistingTelephoneNumberOrderType>
        <PartialAllowed>true</PartialAllowed>
        <SiteId>{siteId}</SiteId>
        <SippeerId>{sippeerId}</SippeerId>
    </Order>
    <OrderStatus>RECEIVED</OrderStatus>
</OrderResponse>

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OrderResponse>
    <Order>
        <CustomerOrderId>MyTestOrderId</CustomerOrderId>
        <OrderCreateDate>2018-01-23T19:56:29.678Z</OrderCreateDate>
        <BackOrderRequested>false</BackOrderRequested>
        <id>47955555-67aa-4adb-8c0f-b6894e60c0dc</id>
        <ExistingTelephoneNumberOrderType>
            <TelephoneNumberList>
                <TelephoneNumber>+12125551234</TelephoneNumber>
                <TelephoneNumber>+19195005710</TelephoneNumber>
            </TelephoneNumberList>
        </ExistingTelephoneNumberOrderType>
        <PartialAllowed>true</PartialAllowed>
        <SiteId>{siteId}</SiteId>
        <SippeerId>{sippeerId}</SippeerId>
    </Order>
    <OrderStatus>RECEIVED</OrderStatus>
</OrderResponse>

Webhooks

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

<?xml version="1.0"?>
<Notification>
    <SubscriptionId>...</SubscriptionId>
    <OrderType>47955555-67aa-4adb-8c0f-b6894e60c0dc</OrderType>
    <CustomerOrderId>MyTestOrderId</CustomerOrderId>
    <Status>COMPLETE</Status>
    <CompletedTelephoneNumbers>
        <TelephoneNumber>2125551234</TelephoneNumber>
        <TelephoneNumber>9195005710</TelephoneNumber>
    </CompletedTelephoneNumbers>
    <LastModifiedDate>2023-09-12T15:11:31.705Z</LastModifiedDate>
</Notification>

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

<?xml version="1.0"?>
<Notification>
    <SubscriptionId>...</SubscriptionId>
    <OrderType>47955555-67aa-4adb-8c0f-b6894e60c0dc</OrderType>
    <CustomerOrderId>MyTestOrderId</CustomerOrderId>
    <Status>COMPLETE</Status>
    <CompletedTelephoneNumbers>
        <TelephoneNumber>+12125551234</TelephoneNumber>
        <TelephoneNumber>+19195005710</TelephoneNumber>
    </CompletedTelephoneNumbers>
    <LastModifiedDate>2023-09-12T15:11:31.705Z</LastModifiedDate>
</Notification>

What is E.164?​

How to Utilize E.164 Phone Numbers in the v2 API​

Examples​

Requests​

Responses​

Webhooks​