Export#
Use the Export resource to generate and download non-real-time reports of call and message records through the DIDWW API.
An Export is an asynchronous request for inbound or outbound call detail records (CDRs) or inbound or outbound SMS records. It records the export type, selected filters, processing status, creation time, callback settings, external reference ID, and the download URL that becomes available after processing is complete.
Four export types are supported:
Export type |
Use it to |
|---|---|
|
Export inbound CDRs for a required date and time range. The results can optionally be limited by DID number, caller number, or caller country. |
|
Export outbound CDRs for a required date and time range. The results can optionally be limited by Outbound Trunk, source number, CLI, or destination number. |
|
Export inbound SMS records for a required date and time range. The results can optionally be limited by address, status, SMS trunk, trunk type, or SMS ID. |
|
Export outbound SMS records for a required date and time range. The results can optionally be limited by address, status, SMS trunk, service type, sender ID verification, or SMS ID. |
Attention
Records of every export type can be exported only for the current month and the previous two months. DIDWW automatically deletes a completed Export one month after completion.
Note
Use Call Events when your application needs near-real-time or continuous CDR delivery instead of occasional report files.
Start with the endpoint that matches your current task:
To request a new report, create an Export.
To monitor several requests, retrieve all Exports.
To check one request and obtain its download URL, retrieve the Export.
To download a completed report, retrieve its compressed CSV file.
Endpoints#
Action |
Method |
Endpoint |
|---|---|---|
Retrieve all Exports |
|
|
Retrieve Export |
|
|
Create Export |
|
|
Update Export |
|
|
Download completed Export |
|
|
Create Export#
Creates an Export and starts asynchronous report generation.
Set export_type to cdr_in, cdr_out, sms_in, or sms_out and provide the
required filters object. Every type requires from and to values for the date and
time range. You can also provide callback settings and an external_reference_id of up to
100 characters.
A successful request returns 201 Created with status pending. The url remains
null until the export reaches completed.
See Create Export.
POST /v3/exports
Retrieve all Exports#
Retrieves all Exports associated with the account, including Exports created with earlier API versions.
Use this endpoint to monitor requests or find a previously created export. Results can be
filtered by id, external_reference_id, export_type, status, and creation
time (created_at_gteq, created_at_lteq). The export_type and status filters
accept a comma-separated list of values.
Results can be sorted by status, created_at, or external_reference_id and
support pagination and sparse fieldsets.
See Retrieve All Exports.
GET /v3/exports
Retrieve Export#
Retrieves a specific Export by its unique ID.
Use this endpoint to monitor asynchronous processing. When status becomes completed,
the url attribute contains the endpoint for downloading the generated .csv.gz file.
See Retrieve Export.
GET /v3/exports/{id}
Update Export#
Updates the external_reference_id of an Export. No other attribute of an Export can be
changed.
See Update Export.
PATCH /v3/exports/{id}
Download a completed Export#
Downloads the compressed CSV file generated for a completed Export.
Use the filename from the completed Export’s url attribute. The filename is not the
Export resource ID. Send an authenticated GET request to the returned URL with an
access token in the Authorization header. This download also accepts an API key in the
Api-Key header.
The response is a download-only .csv.gz archive rather than a JSON:API document or an
uncompressed CSV response. Download and decompress the archive to read the enclosed CSV
data. The file page documents the columns of every export type and provides sample CSV
files.
See Download Export File.
GET /v3/exports/{filename}.csv.gz
Export filters#
Every filter value is matched exactly unless its description says otherwise. A filter that is sent must not be blank. Only the filters listed for the selected export type are accepted; any other key is rejected.
Inbound CDR filters#
Set export_type to cdr_in and provide:
Filter |
Required |
Meaning |
|---|---|---|
|
Yes |
Start date and time of the CDR range. |
|
Yes |
End date and time of the CDR range. |
|
No |
Limit the report to a specific owned DID number. Omit it to export inbound CDRs for all owned DIDs. |
|
No |
Limit the report to calls from this caller number, as it reached DIDWW. |
|
No |
Limit the report to calls from this caller number, as delivered to the trunk. |
|
No |
Limit the report to calls from the country with this ISO 3166-1 alpha-2 code,
for example |
Outbound CDR filters#
Set export_type to cdr_out and provide:
Filter |
Required |
Meaning |
|---|---|---|
|
Yes |
Start date and time of the CDR range. |
|
Yes |
End date and time of the CDR range. |
|
No |
Limit the report to a specific Outbound Trunk. |
|
No |
Limit the report to calls from this source number. |
|
No |
Limit the report to calls presenting this caller ID (CLI). |
|
No |
Limit the report to calls to this destination number. |
Inbound SMS filters#
Set export_type to sms_in and provide:
Filter |
Required |
Meaning |
|---|---|---|
|
Yes |
Start date and time of the SMS record range. |
|
Yes |
End date and time of the SMS record range. |
|
No |
Limit the report to messages from exactly this sender address. |
|
No |
Limit the report to messages whose sender address contains this value. |
|
No |
Limit the report to messages to exactly this recipient address. |
|
No |
Limit the report to messages whose recipient address contains this value. |
|
No |
Limit the report to messages in this state: |
|
No |
Limit the report to messages delivered through SMS trunks of this type, or of any of
these types: |
|
No |
Limit the report to messages delivered through this SMS trunk of the account, or any of these SMS trunks. |
|
No |
Limit the report to the message with this SMS ID. |
Outbound SMS filters#
Set export_type to sms_out and provide:
Filter |
Required |
Meaning |
|---|---|---|
|
Yes |
Start date and time of the SMS record range. |
|
Yes |
End date and time of the SMS record range. |
|
No |
Limit the report to messages from exactly this sender address. |
|
No |
Limit the report to messages whose sender address contains this value. |
|
No |
Limit the report to messages to exactly this recipient address. |
|
No |
Limit the report to messages whose recipient address contains this value. |
|
No |
Limit the report to messages in this state: |
|
No |
Limit the report to messages sent through this SMS trunk of the account, or any of these SMS trunks. |
|
No |
Limit the report to the message with this SMS ID. |
|
No |
Limit the report to person-to-person ( |
|
No |
Limit the report to messages sent under this sender ID verification of the account, or any of these sender ID verifications. |
See Export Filters Object for the filter data model.
Export statuses#
Status |
Meaning |
|---|---|
|
The export request has been accepted and is waiting to be processed. |
|
DIDWW is generating the report. |
|
Report generation is complete and the |
Callbacks#
Set callback_url and callback_method when creating an Export to receive a
notification when processing is complete. Send both attributes together. The callback
method can be get or post.
The completion payload contains the Export ID, resource type exports, status
completed, and the direct file-download url. The payload is the same for every
export type. A get callback sends these values as query parameters. A post callback
sends them as application/x-www-form-urlencoded data.
See Callbacks Details for the payload and request-signature validation guidance.
Data reference#
See Export Object for all status, callback, file, reference, type, and filter attributes returned by the resource.
Common Export use cases#
Use case |
Description |
|---|---|
Export inbound CDRs |
Generate a report for all owned DIDs or limit it to one DID number, caller number, or caller country. |
Export outbound CDRs |
Generate a report for all outbound traffic or limit it to one Outbound Trunk, source number, CLI, or destination number. |
Export inbound SMS records |
Generate a report of messages received on owned DIDs, optionally limited to selected SMS trunks or trunk types. |
Export outbound SMS records |
Generate a report of sent messages, optionally limited to selected SMS trunks, a service type, or sender ID verifications. |
Monitor report generation |
Retrieve the Export until its status becomes |
Receive completion notifications |
Configure a callback to receive the completed status and direct download URL without polling. |
Reconcile external reports |
Set and filter by |
Process reports offline |
Download and decompress the |
Receive continuous CDR data |
Use Call Events instead of report exports when near-real-time delivery is required. |