How to setup Subscriptions

Bandwidth uses webhooks to send number management & porting events to any publicly addressable url.

In order to successfully use the Number Management & Porting APIs you need to configure a subscription for each orderType. Each subscription is account-global and each account can have multiple subscriptions per orderType.

Subscriptions contain the URL & CallbackCreds to authenticate and send events for each state change.

Because processing times may vary across all order types, Bandwidth recommends the use of subscriptions to receive webhook notifications upon order completion, as opposed to polling the resource ID with GET requests until the desired state is returned.

Subscriptions

Order Types

Order type	Notified states
`portins`	`PENDING_DOCUMENTS`, `SUBMITTED`, `FOC`, `REQUESTED_SUPP`, `COMPLETE`, `CANCELLED`, `EXCEPTION`, `REQUESTED_CANCEL`
`orders`	`COMPLETE`, `PARTIAL`, `BACKORDERED`, `FAILED`
`portouts`	`COMPLETE`
`disconnects`	`COMPLETE`, `PARTIAL`, `FAILED`
`dldas`	`RECEIVED`, `PROCESSING`, `COMPLETE`, `PARTIAL`, `FAILED`
`lsrorders`	`PENDING`, `FOC`, `EXCEPTION`, `COMPLETE`, `CANCELLED`, `PARTIAL`, `FAILED`
`e911s`	`RECEIVED`, `PROCESSING`, `COMPLETE`, `ADJUSTED_COMPLETE`, `PARTIAL`, `ADJUSTED_PARTIAL`, `FAILED`
`tnoptions`	`RECEIVED`, `PROCESSING`, `COMPLETE`, `PARTIAL`, `FAILED`
`externalTns`	`COMPLETE`, `PARTIAL`, `FAILED`
`lidb`	`PROCESSING`, `COMPLETE`, `PARTIAL`, `FAILED`
`bulkPortins`	`DRAFT`, `IN_PROGRESS`, `NEEDS_ATTENTION`, `PARTIAL`, `COMPLETED`, `CANCELLED`
`importtnorders`	`COMPLETE`, `PARTIAL`, `FAILED`, `EXCEPTION`
`removeImportedTnOrders`	`PROCESSING`, `COMPLETE`, `PARTIAL`, `FAILED`
`importVoiceTnOrders`	`COMPLETE`, `PARTIAL`, `FAILED`, `EXCEPTION`
`removeImportedVoiceTnOrders`	`PROCESSING`, `COMPLETE`, `PARTIAL`, `FAILED`
`csrs`	`COMPLETE`, `FAILED`, `ACTION_REQUIRED`
`emergencyNotificationGroup`	`COMPLETE`, `FAILED`
`emergencyEndpointGroup`	`COMPLETE`, `FAILED`

Event Types

Event type	Description
`MESSAGING_LOST`	Sent when TNs in your account are impacted due to orders outside of your account. For example, a `MESSAGING_LOST` event is reported on a TN with hosted messaging service in your account when a port in order placed by another account on the same TN is executed. An order placed in your account to remove the TN will NOT report a `MESSAGING_LOST` event.

Create Subscription

This operation will create an active subscription on your account.

Request URL

POST https://dashboard.bandwidth.com/api/accounts/{accountId}/subscriptions

Request Parameters

Parameters	Required	Description
`OrderType`	No* (one of `OrderType` or `EventType` must be set)	The type of Order (see table above) of the subscription. Will send Order Based Callbacks.
`EventType`	No* (one of `OrderType` or `EventType` must be set)	The type of Event (see table above) of the subscription Will send Event Based Callbacks.
`OrderId`	No	A unique `OrderId` of the same `OrderType`. Use the `OrderId` if you want to get callbacks for a specific order. Typically used for porting numbers.
`CallbackSubscription`	Yes	Container for the callback details
`Expiry`	Yes	The time in seconds to persist the subscription. Example Times 99 years = `3122064000` seconds 2 weeks = `1209600` seconds 1 week = `604800` seconds 1 day = `86400` seconds 1 hour = `3600` seconds
`URL`	Yes	Url to receive callbacks for the specified `orderId` or `orderType`
`CallbackCredentials`	No, but highly recommended	Container for the Auth
`BasicAuthentication`	-	Basic auth credentials to apply to your message & voice events
`BasicAuthentication.Username`	No, but highly recommended	Basic auth `Username`
`BasicAuthentication.Password`	No, but highly recommended	Basic auth `Password`
`PublicKey`	No	BASE64 encoded public key matching the notification receiving server

Examples

General Order Subscription
Single Portin Order Subscription
Event Subscription

Request

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

<Subscription>
    <OrderType>orders</OrderType>
    <CallbackSubscription>
        <URL>[valid publically addressable URL]</URL>
        <Expiry>3122064000</Expiry>
        <CallbackCredentials>
            <BasicAuthentication>
                <Username>[username]</Username>
                <Password>[password]</Password>
            </BasicAuthentication>
            <PublicKey>kQgQ0VSVElGSUNBVEUtLS0tLQ0K</PublicKey>
        </CallbackCredentials>
    </CallbackSubscription>
</Subscription>

Response

HTTP/1.1 201 Created
Content-Type: application/xml
Location: https://dashboard.bandwidth.com/api/accounts/{accountId}/subscriptions/{subscriptionId}

Request

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

<Subscription>
    <OrderType>portins</OrderType>
    <OrderId>ee456cfb-d237-4adc-b3f8-9db03d2e62a2<OrderId>
    <CallbackSubscription>
        <URL>[valid publically addressable URL]</URL>
        <Expiry>3122064000</Expiry>
        <CallbackCredentials>
            <BasicAuthentication>
                <Username>[username]</Username>
                <Password>[password]</Password>
            </BasicAuthentication>
        </CallbackCredentials>
    </CallbackSubscription>
</Subscription>

Response

HTTP/1.1 201 Created
Content-Type: application/xml
Location: https://dashboard.bandwidth.com/api/accounts/{accountId}/subscriptions/{subscriptionId}

Request

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

<Subscription>
    <EventType>MESSAGING_LOST</EventType>
    <CallbackSubscription>
        <URL>[valid publically addressable URL]</URL>
        <Expiry>3122064000</Expiry>
        <CallbackCredentials>
            <BasicAuthentication>
                <Username>[username]</Username>
                <Password>[password]</Password>
            </BasicAuthentication>
        </CallbackCredentials>
    </CallbackSubscription>
</Subscription>

Response

HTTP/1.1 201 Created
Content-Type: application/xml
Location: https://dashboard.bandwidth.com/api/accounts/{accountId}/subscriptions/{subscriptionId}

List Subscriptions

This operation will list all active applications on your account.

Request URL

GET https://dashboard.bandwidth.com/api/accounts/{accountId}/subscriptions

Examples

Request

GET https://dashboard.bandwidth.com/api/accounts/{accountId}/subscriptions HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Response

HTTP/1.1 200 OK
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SubscriptionsResponse>
    <Subscriptions>
        <Subscription>
            <SubscriptionId>4025131f-a05f-4269-8ad6-f38efbf23cea</SubscriptionId>
            <EventType>MESSAGING_LOST</EventType>
            <CallbackSubscription>
                <URL>https://myUrl.com/messagingLost</URL>
                <Expiry>3586</Expiry>
                <Status>READY</Status>
            </CallbackSubscription>
        </Subscription>
        <Subscription>
            <SubscriptionId>23bba4e1-50f1-4461-94b1-33d223e886dc</SubscriptionId>
            <OrderType>portins</OrderType>
            <CallbackSubscription>
                <URL>https://myUrl.com/portins</URL>
                <Expiry>3596</Expiry>
                <Status>READY</Status>
            </CallbackSubscription>
        </Subscription>
        <Subscription>
            <SubscriptionId>c01a23e3-eb99-4174-9598-77d5beadebcf</SubscriptionId>
            <OrderType>orders</OrderType>
            <CallbackSubscription>
              <URL>https://myUrl.com/ordersWithAuth</URL>
              <Expiry>3593</Expiry>
              <Status>READY</Status>
              <CallbackCredentials>
                  <BasicAuthentication>
                      <Username>username</Username>
                  </BasicAuthentication>
              </CallbackCredentials>
          </CallbackSubscription>
        </Subscription>
    </Subscriptions>
</SubscriptionsResponse>

Fetch Specific Subscription Information

This operation will list information for a single active subscription on your account.

Request URL

GET https://dashboard.bandwidth.com/api/accounts/{accountId}/subscriptions/{ subscriptionId }

Examples

Request

GET https://dashboard.bandwidth.com/api/accounts/{accountId}/subscriptions/{subscriptionId} HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Response

HTTP/1.1 200 OK
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SubscriptionsResponse>
    <Subscriptions>
        <Subscription>
            <SubscriptionId>c01a23e3-eb99-4174-9598-77d5beadebcf</SubscriptionId>
            <OrderType>orders</OrderType>
            <CallbackSubscription>
                <URL>https://myUrl.com/ordersWithAuth</URL>
                <Expiry>3319</Expiry>
                <Status>READY</Status>
                <CallbackCredentials>
                    <BasicAuthentication>
                        <Username>username</Username>
                    </BasicAuthentication>
                </CallbackCredentials>
            </CallbackSubscription>
        </Subscription>
    </Subscriptions>
</SubscriptionsResponse>

Completely Update a Subscription

This operation allows you to completely overwrite the subscription resource with an idempotent PUT request. Note that any field not supplied in the request body will return to system default after the request is completed.

Request URL

PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/subscriptions/{ subscriptionId }

Examples

Request

PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/subscriptions/{subscriptionId} HTTP/1.1
Content-Type: application/xml
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

<Subscription>
    <OrderType>orders</OrderType>
    <CallbackSubscription>
        <URL>[Same URL as before]</URL>
        <Expiry>3122064000</Expiry>
    </CallbackSubscription>
</Subscription>

Response

HTTP/1.1 200 OK

Delete a Subscription

This operation will delete an active subscription.

Request URL

DELETE https://dashboard.bandwidth.com/api/accounts/{accountId}/subscriptions/{ subscriptionId }

Examples

Request

DELETE https://dashboard.bandwidth.com/api/accounts/{accountId}/subscriptions/{subscriptionId} HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Response

HTTP/1.1 200 OK

Order Types​

Event Types​

Create Subscription​

Request URL​

Request Parameters​

Examples​

List Subscriptions​

Request URL​

Examples​

Fetch Specific Subscription Information​

Request URL​

Examples​

Completely Update a Subscription​

Request URL​

Examples​

Delete a Subscription​

Request URL​

Examples​

Order Types

Event Types

Create Subscription

Request URL

Request Parameters

Examples

List Subscriptions

Request URL

Examples

Fetch Specific Subscription Information

Request URL

Examples

Completely Update a Subscription

Request URL

Examples

Delete a Subscription

Request URL

Examples