Downloading Reports
Overview
About
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 (/reports
)
Report Name | ID | Description |
---|---|---|
Full Phone Number Details | 2 | Complete information about all phone numbers within the report’s scope |
Phone Number Inventory | 4 | A list of all phone numbers associated with an account |
E911 Phone Number Details | 6 | E911 information associated with phone numbers within the report’s scope |
Port-out Orders | 8 | Phone number details for historic or current port-out orders |
Port-in Orders | 14 | Phone number details for historic or current port-in orders |
UC Account Summary | 16 | Detailed account information for a given UC account |
User Information | 24 | Information about all active and inactive users for a given account |
Disconnected Phone Numbers | 30 | Information about all phone numbers that have been disconnected from the account |
External Phone Number Details | 31 | Complete information about customer provided phone numbers within the report’s scope |
End-User Phone Number Assignment | 34 | A list of phone numbers and their end-user assignment statuses |
Alternate Caller ID E911 Report | 36 | E911 detail information for accounts that use an alternative identifier for the end user |
E911 Addresses | 42 | A 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 Report | 47 | This report will list all of the Telephone Numbers that appear to be under-utilized and unassigned |
Iris Account Number Utilization Report | 48 | This account report will provide insight into the current utilization and assignment data associated with the Bandwidth Dashboard TN inventory |
Protected Phone Numbers Report | 50 | This report will provide a simple report that lists all of the protected TNs on an account, as well as their status |
New Numbers | 59 | Phone number details for historic or current new number orders |
International TN Inventory Summary | 64 | Summary of international telephone numbers |
Telephone Number Route Plan Report | 65 | This report lists all of the route plans that are active for the indicated account |
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.
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 (/billingReports
)
Report Type | Description |
---|---|
BDR | Billing Detail Records for Voice Services - per call information, available on day to day basis - may not reflect final invoice |
MDR | Message Detail Records - per message information - may not reflect final invoice |
INVOICE | A copy of the invoice file or files for the specified date range |
STMTBDR | BDR records that are aligned with the invoice for Voice Services |
DIDSNAP | A list of telephone numbers, aligned with invoice |
DIDSNAP_MSG | A list of telephone numbers that are enabled for messaging, aligned with invoice |
RECORDINGBDR | Billing Detail Records for Recording Services - per recording information, available on day to day basis |
RECORDINGSTMTBDR | BDR records that are aligned with the invoice for Recording Services |
TRANSCRIPTIONBDR | Billing Detail Records for Transcription Services - per call transcription information, available on day to day basis |
TRANSCRIPTIONSTMTBDR | BDR records that are aligned with the invoice for Recording Services |
CNAMBDR | Record of CNAM Subscribe and Notify queries/dips, available on day to day basis |
CNAMSTMTBDR | Record of CNAM Subscribe and Notify queries/dips, aligns with invoices |
CONFBDR | Billing Detail Records for Transcription Services - per conference information, available on day to day basis |
CONFSTMTBDR | BDR records that are aligned with the invoice for Conferencing Services |
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