---
title: "Create a CSV download"
method: POST
path: "/phone_numbers/csv_downloads"
tags: ["CSV Downloads"]
---

# Create a CSV download

`POST /phone_numbers/csv_downloads`

Starts generation of a CSV export for phone numbers matching the supplied filters. The `csv_format` parameter selects the output format, and the response contains the resulting download record.

## Query parameters

- `csv_format` 'V1' | 'V2'
- `filter` object
  - `has_bundle` string — Filter by phone number that have bundles.
  - `tag` string — Filter by phone number tags.
  - `connection_id` string — Filter by connection_id.
  - `phone_number` string — Filter by phone number. Requires at least three digits. Non-numerical characters will result in no values being returned.
  - `status` 'purchase-pending' | 'purchase-failed' | 'port-pending' | 'active' | 'deleted' | 'port-failed' | 'emergency-only' | 'ported-out' | 'port-out-pending' — Filter by phone number status.
  - `voice.connection_name` object — Filter by voice connection name pattern matching.
    - `contains` string — Filter contains connection name. Requires at least three characters.
    - `starts_with` string — Filter starts with connection name. Requires at least three characters.
    - `ends_with` string — Filter ends with connection name. Requires at least three characters.
    - `eq` string — Filter by connection name.
  - `voice.usage_payment_method` 'pay-per-minute' | 'channel' — Filter by usage_payment_method.
  - `billing_group_id` string — Filter by the billing_group_id associated with phone numbers. To filter to only phone numbers that have no billing group associated them, set the value of this filter to the string 'null'.
  - `emergency_address_id` string — Filter by the emergency_address_id associated with phone numbers. To filter only phone numbers that have no emergency address associated with them, set the value of this filter to the string 'null'.
  - `customer_reference` string — Filter numbers via the customer_reference set.

## Response `200`

Successful response with details about a CSV download.

- object
  - `data` CsvDownload[]
    - `id` string — Identifies the resource.
    - `record_type` string — Identifies the type of the resource.
    - `url` string — The URL at which the CSV file can be retrieved.
    - `status` 'pending' | 'complete' | 'failed' | 'expired' — Indicates the completion level of the CSV report. Only complete CSV download requests will be able to be retrieved.

## Other responses

- `400` — Bad request, the request was unacceptable, often due to missing a required parameter.
- `401` — Unauthorized
- `404` — The requested resource doesn't exist.
- `422` — Unprocessable entity. Check the 'detail' field in response for details.
- `500` — Unexpected error

## Changes

> 81 revisions in range; 1 not diffed.

- **2026-09-16** `a6a61a29ecdd` — 5 breaking, 5 warning, 10 info
  - the `errors/items/code` response's property type changed from `string` to `integer`, and format from no format to `int32` for status `400`
  - the `errors/items/code` response's property type changed from `string` to `integer`, and format from no format to `int32` for status `401`
  - the `errors/items/code` response's property type changed from `string` to `integer`, and format from no format to `int32` for status `404`
  - the `errors/items/code` response's property type changed from `string` to `integer`, and format from no format to `int32` for status `422`
  - …16 more
- **2026-08-17** `1571b0380bd7` — 15 breaking, 5 info
  - the response property `errors/items/code` became optional for the status `400`
  - the response property `errors/items/code` became optional for the status `401`
  - the response property `errors/items/code` became optional for the status `404`
  - the response property `errors/items/code` became optional for the status `422`
  - …16 more
- …earlier changes not shown

[Full history](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/changes/phone_numbers/csv_downloads/post.md)

---

[API](https://skmtc.dev/team-telnyx/apis/telnyx-api-2.md) · [All operations](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/llms.txt) · [OpenAPI document](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/revisions/f6e9ed754d05?raw)