# Export

Use the Export resource to generate and download non-real-time Call Detail Record reports
through the DIDWW API.

An Export is an asynchronous request for inbound or outbound CDR data. 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.

Two 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 to a specific DID number. |
| `cdr_out` | Export outbound CDRs for a required date and time range. The results can optionally be limited to a specific Outbound Trunk ID. |

Attention

Inbound and outbound CDRs can be exported only for the current month and the previous
two months. DIDWW automatically deletes a completed CDR 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` |
| 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` or `cdr_out` and provide the required `filters`
object. Both types require `from` and `to` values for the CDR 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.

Use this endpoint to monitor requests or find a previously created export. Results can be
filtered by `external_reference_id`. The following additional filters apply to the
criteria stored for each export type:

- `cdr_in` supports `from`, `to`, and `did_number`.
- `cdr_out` supports `from`, `to`, and `voice_out_trunk.id`.

Results can be sorted by `status` or `created_at` 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}
```

## 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.

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 all inbound and outbound CDR columns and provides sample CSV
files.

See [Download Export File](get-csv-file-of-export.html).

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

## Export filters

### 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. |

### 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. |

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 CDR 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. 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`. 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. |
| Export outbound CDRs | Generate a report for all outbound traffic or limit it to one Outbound Trunk. |
| 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.
- [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.

On this page