Skip to main content

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 typeNotified states
portinsPENDING_DOCUMENTS, SUBMITTED, FOC, REQUESTED_SUPP, COMPLETE, CANCELLED, EXCEPTION, REQUESTED_CANCEL
ordersCOMPLETE, PARTIAL, BACKORDERED, FAILED
portoutsCOMPLETE
disconnectsCOMPLETE, PARTIAL, FAILED
dldasRECEIVED, PROCESSING, COMPLETE, PARTIAL, FAILED
lsrordersPENDING, FOC, EXCEPTION, COMPLETE, CANCELLED, PARTIAL, FAILED
e911sRECEIVED, PROCESSING, COMPLETE, ADJUSTED_COMPLETE, PARTIAL, ADJUSTED_PARTIAL, FAILED
tnoptionsRECEIVED, PROCESSING, COMPLETE, PARTIAL, FAILED
externalTnsCOMPLETE, PARTIAL, FAILED
lidbPROCESSING, COMPLETE, PARTIAL, FAILED
bulkPortinsDRAFT, IN_PROGRESS, NEEDS_ATTENTION, PARTIAL, COMPLETED, CANCELLED
importtnordersCOMPLETE, PARTIAL, FAILED, EXCEPTION
removeImportedTnOrdersPROCESSING, COMPLETE, PARTIAL, FAILED
csrsCOMPLETE, FAILED, ACTION_REQUIRED
emergencyNotificationGroupCOMPLETE, FAILED
emergencyEndpointGroupCOMPLETE, FAILED

Event Types#

Event typeDescription
MESSAGING_LOSTSent 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#

ParametersRequiredDescription
OrderTypeNo*
(one of OrderType or EventType must be set)
The type of Order (see table above) of the subscription. Will send Order Based Callbacks.
EventTypeNo*
(one of OrderType or EventType must be set)
The type of Event (see table above) of the subscription Will send Event Based Callbacks.
OrderIdNoA unique OrderId of the same OrderType.
Use the OrderId if you want to get callbacks for a specific order. Typically used for porting numbers.
CallbackSubscriptionYesContainer for the callback details
ExpiryYesThe 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
URLYesUrl to receive callbacks for the specified orderId or orderType
CallbackCredentialsNo, but highly recommendedContainer for the Auth
BasicAuthentication-Basic auth credentials to apply to your message & voice events
BasicAuthentication.UsernameNo, but highly recommendedBasic auth Username
BasicAuthentication.PasswordNo, but highly recommendedBasic auth Password
PublicKeyNoBASE64 encoded public key matching the notification receiving server

Examples#

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