Skip to main content

Downloading Reports

The Bandwidth numbers API allows you to automate the creation and download of certain reports related to account usage. This is handled through various requests to our /reports and /billingReports endpoints. The available reports for each endpoint are detailed in their respective sections.

Account Reports#

A GET request to https://dashboard.bandwidth.com/api/accounts/{accountId}/reports will return an XML list of the available report types, their ID number, and a description of each. The report ID needs to be passed in to the URL of the API request to indicate which type of report we want to create.

A GET request to https://dashboard.bandwidth.com/api/accounts/{accountId}/reports/{reportId} will return details for a specific report, like a description and the parameters needed to define boundaries for the report.

Report NameIDDescription
Full Phone Number Details2Complete information about all phone numbers within the report’s scope
Phone Number Inventory4A list of all phone numbers associated with an account
E911 Phone Number Details6E911 information associated with phone numbers within the report’s scope
Port-out Orders8Phone number details for historic or current port-out orders
Port-in Orders14Phone number details for historic or current port-in orders
UC Account Summary16Detailed account information for a given UC account
User Information24Information about all active and inactive users for a given account
Disconnected Phone Numbers30Information about all phone numbers that have been disconnected from the account
External Phone Number Details31Complete information about customer provided phone numbers within the report’s scope
End-User Phone Number Assignment34A list of phone numbers and their end-user assignment statuses
Alternate Caller ID E911 Report36E911 detail information for accounts that use an alternative identifier for the end user
E911 Addresses42A list of all E911 addresses provisioned to an account. The list of addresses shown are only for Dynamic Location Routing-enabled accounts.
Number Utilization Telephone Number List Report47This report will list all of the Telephone Numbers that appear to be under-utilized and unassigned
Iris Account Number Utilization Report48This account report will provide insight into the current utilization and assignment data associated with the Bandwidth Dashboard TN inventory
Protected Phone Numbers Report50This report will provide a simple report that lists all of the protected TNs on an account, as well as their status
New Numbers59Phone number details for historic or current new number orders
International TN Inventory Summary64Summary of international telephone numbers
Telephone Number Route Plan Report65This report lists all of the route plans that are active for the indicated account

Request a Report#

Once the ID of the report you are looking to generate is ascertained, A POST request to https://dashboard.bandwidth.com/api/accounts/{accountId}/reports/{reportId}/instances will trigger the generation of a new report and return a 201 response with a location header containing a URL used to query the status of the report.

Request

POST https://dashboard.bandwidth.com/api/accounts/{accountId}/reports/{reportId}/instancess HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
<Instance>
<OutputFormat>pdf</OutputFormat>
<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>
<!-- the date (not longer than 30 days in the future) at the end of which the instance will expire, should be specified in YYYY-MM-DD format-->
</Instance>

Response

HTTP/1.1 201 Created
Content-Type: application/xml; charset=utf-8
Location: https://dashboard.bandwidth.com/api/accounts/{accountId}/reports/{reportId}/instances/789

Query Report Status#

Using the URL received in the HTTP response from our first POST request, we can make a request to query the API for the status of our report's generation.

Request

GET https://dashboard.bandwidth.com/api/accounts/{accountId}/reports/{reportId}/instances/789 HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Response

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ReportInstanceResponse>
<Instance>
<Id>100102</Id>
<ReportId>100020</ReportId>
<ReportName>Sample Report</ReportName>
<OutputFormat>pdf</OutputFormat>
<RequestedByUserName>user</RequestedByUserName>
<RequestedAt>2020-9-19 11:05:12</RequestedAt>
<Parameters>
<Parameter>
<Name>AccountId</Name>
<Value>1</Value>
</Parameter>
</Parameters>
<Status>Ready</Status>
<ExpiresAt>2020-11-25</ExpiresAt>
</Instance>
</ReportInstanceResponse>

Download the Report#

Once the report status query returns Ready, we are ready to download the requested report. This can be done by making a GET request to the URI received in the location header of the response to our original POST request, and appending it with /file . The 200 response will include a Content-Disposition header indicating the filename, and a download of the file will begin.

Request

GET https://dashboard.bandwidth.com/api/accounts/{accountId}/reports/{reportId}/instances/789/file HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Response

HTTP/1.1 200 OK
Content-Disposition: attachment; filename=output.pdf

Billing Reports#

These reports return information about billable events that occured on your Bandwidth account and associated telephone numbers.

Report TypeDescription
BDRBilling Detail Records for Voice Services - per call information, available on day to day basis - may not reflect final invoice
MDRMessage Detail Records - per message information - may not reflect final invoice
INVOICEA copy of the invoice file or files for the specified date range
STMTBDRBDR records that are aligned with the invoice for Voice Services
DIDSNAPA list of telephone numbers, aligned with invoice
DIDSNAP_MSGA list of telephone numbers that are enabled for messaging, aligned with invoice
RECORDINGBDRBilling Detail Records for Recording Services - per recording information, available on day to day basis
RECORDINGSTMTBDRBDR records that are aligned with the invoice for Recording Services
TRANSCRIPTIONBDRBilling Detail Records for Transcription Services - per call transcription information, available on day to day basis
TRANSCRIPTIONSTMTBDRBDR records that are aligned with the invoice for Recording Services
CNAMBDRRecord of CNAM Subscribe and Notify queries/dips, available on day to day basis
CNAMSTMTBDRRecord of CNAM Subscribe and Notify queries/dips, aligns with invoices
CONFBDRBilling Detail Records for Transcription Services - per conference information, available on day to day basis
CONFSTMTBDRBDR records that are aligned with the invoice for Conferencing Services
UNPROVISIONED_CALLS_BDRBDR for unprovisioned 911 calls that were routed to the ECC

Request a Report#

Creating a report starts with a POST request to https://dashboard.bandwidth.com/api/accounts/{accountId}/billingReports, detailing the date range for the report as well as type of report you wish to download. A successful response will include a body and location header, which contains a URI with the report ID to be used in later requests.

Request

POST https://dashboard.bandwidth.com/api/accounts/{accountId}/billingReports HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
<BillingReport>
<Type>BDR</Type>
<DateRange>
<StartDate>2020-05-21</StartDate>
<EndDate>2020-05-29</EndDate>
</DateRange>
</BillingReport>

Response

HTTP/1.1 201 Created
Content-Type: application/xml; charset=utf-8
Location: https://dashboard.bandwidth.com/api/accounts/{accountId}/billingreports/a12b456c8-abcd-1a3b-a1b2-0a2b4c6d8e0f2
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<BillingReportCreationResponse>
<ReportStatus>RECEIVED</ReportStatus>
<Description>The report archive is currently being constructed.</Description>
</BillingReportCreationResponse>

Query Report Status#

Because of the asynchronous nature of the /billingReports endpoint, a POST request does not necessarily mean the report is ready to be consumed. A GET request to the URI received in the location header will return the report status, letting us know if it is ready to be downloaded or not. Expected responses in the <ReportStatus> element are PROCESSING and COMPLETED.

Request

GET https://dashboard.bandwidth.com/api/accounts/{accountId}/billingreports/a12b456c8-abcd-1a3b-a1b2-0a2b4c6d8e0f2 HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Response

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<BillingReportRetrievalResponse>
<ReportStatus>COMPLETED</ReportStatus>
<Description>The report archive is constructed.</Description>
</BillingReportRetrievalResponse>

Download the Report#

Once the report status query returns COMPLETED, we are ready to download the requested report. This can be done by making a GET request to the URI received in the location header of the response to our original POST request, and appending it with /file . The 200 response will include a Content-Disposition header indicating the filename, and a download of the .zip file will begin.

Request

GET https://dashboard.bandwidth.com/api/accounts/{accountId}/billingreports/a12b456c8-abcd-1a3b-a1b2-0a2b4c6d8e0f2/file HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Response

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
Content-Disposition: attachment; filename=bdrs_2020-05-21_2020-05-29.zip