JSON Support in the Bandwidth App

Bandwidth is updating more endpoints to support JSON responses/requests in its Numbers APIs. Prior to 2025, only a few endpoints supported JSON, but continuous updates are now being implemented to standardize and enhance the API suite.

Importance of the Accept Header

When implementing Bandwidth endpoints, it is necessary to explicitly define the Accept header to specify the preferred type of responses, such as application/xml or application/json. If no Accept header is provided, or if it is supplied as */*, and the endpoint supports XML, Bandwidth will return XML by default. Many new v2 endpoints (Requirements Packages and Service Activation for example) will only support JSON.

Possible Breaking-Change

If you include application/json, */* or application/json, application/xml in your Accept header, but the endpoint has only supported XML in the past, your implementation might have been set up to handle XML specifically. However, once JSON becomes available, the endpoint will return JSON based on the order specified in the Accept header, which could potentially break your implementation. To prevent this issue, it is strongly recommended to specify only one value in the Accept header—namely, the content type that your implementation is prepared to handle.

Grace Period until May 1, 2025

During the initial JSON rollout period, unless only JSON is specified, XML will be sent regardless of the Accept header to allow time for customers to update their headers. During the grace period, if the Accept header includes application/xml or */*, XML will be provided, even if JSON was specified earlier.

info

To receive JSON, it is necessary to explicitly request solely application/json.

This XML override will be removed on May 1, 2025. After that date, JSON-enabled endpoints will respond according to the Accept header.

How to Determine if an Endpoint Supports JSON

The best place to determine if an endpoint officially supports JSON is by reviewing its documentation in the API Specification and checking the Content-Type for the endpoint.

Example

The /availableNumbers endpoint supports both JSON and XML. This can be seen in the right panel of the API Specification under the Content-Type dropdown as seen below.

Specific JSON Endpoint Release Dates

For more transparency, below are the scheduled releases by date and endpoint. Our aim is to deliver updated API documentation that clearly reflects the new JSON content type. When JSON is specified in the API request, the endpoint will respond with JSON.

Mar 5, 2025

• GET /tns
• GET /tns/{tn}/tndetails
• POST /accounts/{accountId}/disconnects
• GET /accounts/{accountId}/disconnects/{disconnectId}
• DELETE /accounts/{accountId}/portins/{orderid}

Mar 12, 2025

• POST /accounts/{accountId}/tnreservation
• GET /accounts/{accountId}/tnreservation/{reservationid}
• DELETE /accounts/{accountId}/tnreservation/{reservationid}

Mar 19, 2025

• POST /accounts/{accountId}/orders
• GET /accounts/{accountId}/orders/{orderId}
• GET /accounts/{accountId}/orders
• PUT /accounts/{accountId}/orders/{orderId}
• POST /accounts/{accountId}/portins
• PUT /accounts/{accountId}/portins/{orderId}
• GET /accounts/{accountId}/portins/{orderId}
• DELETE /accounts/{accountId}/portins/{orderId}