How to request billing reports
The Bandwidth numbers API allows you to automate the creation and download of certain billing reports related to account usage. These reports contain information about billable events that occured on your Bandwidth account and associated telephone numbers.
Retrieve Billing Reports
To retrieve all account billing reports and view possible billing report types, make a GET request to our List Billing Reports API endpoint. This can be done through tools like Postman or cURL.
Request URL:
GET https://dashboard.bandwidth.com/api/accounts/{accountId}/billingreports
- cURL
curl 'https://dashboard.bandwidth.com/api/accounts/{accountId}/billingreports'
-u '{userName}:{password}'
Response
<BillingReportsRetrievalResponse>
<BillingReportList>
<BillingReport>
<BillingReportId>5f8734f0-d7c3-445c-b1e2-cdbb620e4ff7</BillingReportId>
<BillingReportKind>BDR</BillingReportKind>
<UserId>some_user</UserId>
<ReportStatus>PROCESSING</ReportStatus>
<Description>The requested report archive is still being constructed, please check back later.</Description>
<CreatedDate>2021-09-16 14:12:16</CreatedDate>
<DateRange>
<StartDate>2021-07-16</StartDate>
<EndDate>2021-09-16</EndDate>
</DateRange>
</BillingReport>
</BillingReportList>
</BillingReportsRetrievalResponse>
Request a Report
To generate a billing report with specific date range and type, you must make a POST request to our Create Billing Report in Range API endpoint. A successful response will include a body and location header, which contains a URI with the report ID to be used in later requests. This can be done through tools like Postman or cURL.
- Payload
- cURL
POST https://dashboard.bandwidth.com/api/accounts/{accountId}/billingreports
<BillingReport>
<Type>BDR</Type>
<DateRange>
<StartDate>2021-07-16</StartDate>
<EndDate>2021-09-16</EndDate>
</DateRange>
</BillingReport>
curl -X POST 'https://dashboard.bandwidth.com/api/accounts/{accountId}/billingreports'
-u '{userName}:{password}'
-H 'Content-Type: application/xml'
-d '<BillingReport>
<Type>BDR</Type>
<DateRange>
<StartDate>2021-07-16</StartDate>
<EndDate>2021-09-16</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
<BillingReportCreationResponse>
<ReportStatus>RECEIVED</ReportStatus>
<Description>The report archive is currently being constructed.</Description>
</BillingReportCreationResponse>
Fetch Report Status
Since the Billing Report request generation is asynchronous, make a GET request to our Retrieve Report Instance API endpoint to determine the status. This can be done through tools like Postman or cURL.
Request URL:
GET https://dashboard.bandwidth.com/api/accounts/{accountId}/billingreports/
- cURL
curl 'https://dashboard.bandwidth.com/api/accounts/{accountId}/billingreports/{reportId}'
-u '{userName}:{password}'
Response
<BillingReportRetrievalResponse>
<ReportStatus>COMPLETED</ReportStatus>
<Description>The report archive is constructed.</Description>
</BillingReportRetrievalResponse>
Download the Report
If the report status is COMPLETED, then you are ready to download the requested report.
This can be done by making a GET request to our Download Billing Report File API endpoint.
The 200 response will include a Content-Disposition header indicating the filename, and a download of the .zip file will begin.
Request URL:
GET https://dashboard.bandwidth.com/api/accounts/{accountId}/billingreports/
{reportId}/file
- cURL
curl 'https://dashboard.bandwidth.com/api/accounts/{accountId}/billingreports/{reportId}/file'
-u '{userName}:{password}'
Response
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
Content-Disposition: attachment; filename=bdrs_2021-07-16_2021-09-16.zip
Where to next?
Now that you have learned how to request account billing reports, check out some of the other available actions in our guides: