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

cdr_in

Export inbound CDRs for a required date and time range. The results can optionally be limited by DID number, caller number, or caller country.

cdr_out

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.

sms_in

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.

sms_out

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:

Endpoints#

Action

Method

Endpoint

Retrieve all Exports

GET

/v3/exports

Retrieve Export

GET

/v3/exports/{id}

Create Export

POST

/v3/exports

Update Export

PATCH

/v3/exports/{id}

Download completed Export

GET

/v3/exports/{filename}.csv.gz

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

from

Yes

Start date and time of the CDR range.

to

Yes

End date and time of the CDR range.

did_number

No

Limit the report to a specific owned DID number. Omit it to export inbound CDRs for all owned DIDs.

source_number

No

Limit the report to calls from this caller number, as it reached DIDWW.

source_number_out

No

Limit the report to calls from this caller number, as delivered to the trunk.

source_country_iso

No

Limit the report to calls from the country with this ISO 3166-1 alpha-2 code, for example GB.

Outbound CDR filters#

Set export_type to cdr_out and provide:

Filter

Required

Meaning

from

Yes

Start date and time of the CDR range.

to

Yes

End date and time of the CDR range.

voice_out_trunk.id

No

Limit the report to a specific Outbound Trunk.

source

No

Limit the report to calls from this source number.

cli

No

Limit the report to calls presenting this caller ID (CLI).

destination

No

Limit the report to calls to this destination number.

Inbound SMS filters#

Set export_type to sms_in and provide:

Filter

Required

Meaning

from

Yes

Start date and time of the SMS record range.

to

Yes

End date and time of the SMS record range.

source_address_eq

No

Limit the report to messages from exactly this sender address.

source_address_cont

No

Limit the report to messages whose sender address contains this value.

destination_address_eq

No

Limit the report to messages to exactly this recipient address.

destination_address_cont

No

Limit the report to messages whose recipient address contains this value.

status

No

Limit the report to messages in this state: success, failed, or queued.

trunk_type

No

Limit the report to messages delivered through SMS trunks of this type, or of any of these types: smpp_smsc, smpp_esme, sms_to_email, http_in.

sms_trunk.id

No

Limit the report to messages delivered through this SMS trunk of the account, or any of these SMS trunks.

sms_id

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

from

Yes

Start date and time of the SMS record range.

to

Yes

End date and time of the SMS record range.

source_address_eq

No

Limit the report to messages from exactly this sender address.

source_address_cont

No

Limit the report to messages whose sender address contains this value.

destination_address_eq

No

Limit the report to messages to exactly this recipient address.

destination_address_cont

No

Limit the report to messages whose recipient address contains this value.

status

No

Limit the report to messages in this state: routing_error, in_progress, queued, failed, or success.

sms_trunk.id

No

Limit the report to messages sent through this SMS trunk of the account, or any of these SMS trunks.

sms_id

No

Limit the report to the message with this SMS ID.

service_type

No

Limit the report to person-to-person (p2p) or application-to-person (a2p) traffic.

sender_id_verification.id

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

pending

The export request has been accepted and is waiting to be processed.

processing

DIDWW is generating the report.

completed

Report generation is complete and the url is available for download.

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 completed and its download URL is available.

Receive completion notifications

Configure a callback to receive the completed status and direct download URL without polling.

Reconcile external reports

Set and filter by external_reference_id to associate API exports with an external reporting system.

Process reports offline

Download and decompress the .csv.gz file for billing, analytics, or archival processing.

Receive continuous CDR data

Use Call Events instead of report exports when near-real-time delivery is required.