# 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](../../../call-events/index.html#cdr-streaming) 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](create-export.html).
- To monitor several requests, [retrieve all Exports](get-exports.html).
- To check one request and obtain its download URL, [retrieve the Export](get-export.html).
- To download a completed report, [retrieve its compressed CSV file](get-csv-file-of-export.html).

## 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](create-export.html).

```
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-exports.html).

```
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-export.html).

```
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](update-export.html).

```
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-csv-file-of-export.html).

```
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](export-filters-object.html) 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](../callbacks-details.html) for the payload and request-signature
validation guidance.

## Data reference

See [Export Object](export-object.html) 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. |

## Related resources

- [DIDs](../inventory-resources/did/index.html) - Retrieve the owned DID numbers that can
  be used to limit an inbound CDR export.
- [Outbound Trunks](../inventory-resources/voice-out-trunks/index.html) - Retrieve the
  Outbound Trunk ID that can be used to limit an outbound CDR export.
- [SMS Trunks](../inventory-resources/sms-trunks/index.html) - Retrieve the SMS trunk IDs
  that can be used to limit an SMS export.
- [Callbacks Details](../callbacks-details.html) - Receive completion notifications and
  validate callback signatures.
- [Call Events](../../../call-events/index.html#cdr-streaming) - Receive near-real-time inbound or outbound CDRs
  instead of generating report files.
- [Call Logs](../../../logs-analytics/call-logs/index.html) - Review inbound and outbound
  call activity in the DIDWW documentation.
- [SMS Logs](../../../logs-analytics/sms-logs/index.html) - Review inbound and outbound
  SMS activity in the DIDWW documentation.
- [Sender ID Verifications](../inventory-resources/sender-id-verifications/index.html) -
  Retrieve the sender ID verification IDs that can be used to limit an outbound SMS export.
- [Sender ID Verifications overview](../../../sms/sender-id-verifications/index.html) - Learn
  how sender ID verifications work.
