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:

GEThttps://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

POSThttps://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

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:

GEThttps://dashboard.bandwidth.com/api/accounts/{accountId}/billingreports/{reportId}

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:

GEThttps://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:

• How to port numbers