---
title: "Export contacts"
description: "Export contacts to a CSV file, as the Contacts page's Export does: every contact, or the ones the list's filters match (q, status, phone, segment_id, segment_subscription, as on List contacts). `POST /api/v1/contacts/export`"
url: https://www.unitpost.com/docs/platform/post-contacts-export
section: "Platform API reference"
updated: 2026-10-13
---
# Export contacts

`POST /api/v1/contacts/export`

Export contacts to a CSV file, as the Contacts page's Export does: every contact, or the ones the list's filters match (`q`, `status`, `phone`, `segment_id`, `segment_subscription`, as on [List contacts](https://www.unitpost.com/docs/platform/get-contacts)). It runs as a background job: follow it with [Retrieve a job](https://www.unitpost.com/docs/platform/get-jobs-id), then fetch the file with [Download a job's file](https://www.unitpost.com/docs/platform/get-jobs-id-download). One export runs at a time: another while it runs is a `409` `job_in_progress` naming it (`Location`). `segment_id` also needs `segments:read`. Requires the `contacts:read` capability.

## Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `q` | string | no | Free text: email, first and last name, and with 3+ digits the SMS number. |
| `status` | enum | no | One of: `subscribed`, `unsubscribed`. |
| `phone` | enum | no | One of: `has`, `none`. |
| `segment_id` | string | no | Members of this segment. Also needs `segments:read`. |
| `segment_subscription` | enum | no | With a static `segment_id`: its per-segment opt-out. One of: `subscribed`, `opted_out`. |

## Response fields (202)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | — |
| `id` | string | yes | — |
| `kind` | string | yes | — |
| `status` | enum | yes | One of: `QUEUED`, `RUNNING`, `COMPLETED`, `FAILED`, `CANCELED`. |
| `total` | integer \| null | yes | — |
| `processed` | integer | yes | — |
| `failed` | integer | yes | — |
| `error` | string \| null | yes | — |
| `created_at` | string | yes | — |
| `completed_at` | string \| null | yes | — |

## Responses

| Status | Description |
| --- | --- |
| 202 | The export job (`Location` names it). |
| 400 | The body isn't JSON. |
| 401 | Missing or invalid API key. |
| 403 | Insufficient scope. |
| 404 | Segment not found. |
| 409 | `job_in_progress`: an export is already running (`Location`). |
| 422 | A bad filter value, or an unknown key. |
| 429 | Too many exports this minute (`Retry-After`). |
| 502 | `engine_unavailable`: the job couldn't be started; nothing was exported. Retry. |

## Example request

```bash
curl -X POST 'https://www.unitpost.com/api/v1/contacts/export' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "subscribed"
  }'
```

## Example response (202)

```json
{
  "object": "job",
  "id": "id_123",
  "kind": "string",
  "status": "QUEUED",
  "total": 1,
  "processed": 0,
  "failed": 0,
  "error": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "completed_at": "2026-01-01T00:00:00.000Z"
}
```

## Links

- HTML reference (with Node.js, Python, Ruby, PHP, Laravel, Go, Java, Rust, .NET and CLI examples): https://www.unitpost.com/docs/platform/post-contacts-export
- OpenAPI 3.1 (full schemas): https://www.unitpost.com/api/v1/openapi.json