# Exports

Generate downloadable CSV/XLSX dumps of contacts. The flow is asynchronous:
`store` enqueues an `ExportContacts` job and returns immediately. Poll `show`
until `status=completed`, then download via the signed `download` URL.

## List exports

`GET /api/exports`

Returns paginated export jobs owned by the authenticated user, newest first.

### Query parameters

- `per_page` (integer) — Rows per page. Default 20, maximum 100. See [Lists, paging and filters](#lists-paging-and-filters).

### Example request

```bash
curl --request GET \
    --get "https://klozzo.com/api/exports?per_page=20" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
```

### Response `200`

```json
{
    "data": [
        {
            "id": null,
            "format": "csv",
            "status": "pending",
            "total_rows": 0,
            "file_name": null,
            "filters": null,
            "columns": null,
            "error": null,
            "started_at": null,
            "finished_at": null,
            "expires_at": null,
            "created_at": null,
            "download_url": null
        },
        {
            "id": null,
            "format": "csv",
            "status": "pending",
            "total_rows": 0,
            "file_name": null,
            "filters": null,
            "columns": null,
            "error": null,
            "started_at": null,
            "finished_at": null,
            "expires_at": null,
            "created_at": null,
            "download_url": null
        }
    ],
    "links": {
        "first": "/?page=1",
        "last": "/?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "links": [
            {
                "url": null,
                "label": "« Previous",
                "page": null,
                "active": false
            },
            {
                "url": "/?page=1",
                "label": "1",
                "page": 1,
                "active": true
            },
            {
                "url": null,
                "label": "Next »",
                "page": null,
                "active": false
            }
        ],
        "path": "/",
        "per_page": 20,
        "to": 2,
        "total": 2
    }
}
```

## Create an export

`POST /api/exports`

Queues an export of contacts and answers immediately with
`status=pending`. Poll the
resource (`GET /api/exports/{id}`) until `status=completed`, then call
`GET /api/exports/{id}/download` to stream the file.

### Body parameters

- `format` (string) — Output format. One of `csv` (default), `xlsx`.
- `filters` (object) — Same shape as smart-list filters; restrict the export to matching rows.
- `columns` (string[]) — Whitelist of contact columns to include. Omit to use the default set.
- `location_id` (integer) — Scope the export to a specific location.

### Example request

```bash
curl --request POST \
    "https://klozzo.com/api/exports" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"format\": \"csv\",
    \"filters\": [],
    \"columns\": [
        \"first_name\",
        \"last_name\",
        \"email\"
    ],
    \"location_id\": 1
}"
```

### Response `200`

```json
{
    "data": {
        "id": null,
        "format": "csv",
        "status": "pending",
        "total_rows": 0,
        "file_name": null,
        "filters": null,
        "columns": null,
        "error": null,
        "started_at": null,
        "finished_at": null,
        "expires_at": null,
        "created_at": null,
        "download_url": null
    }
}
```

### Response `422` — A format that does not exist

```json
{
    "message": "Format no es una opción válida.",
    "errors": {
        "format": [
            "Format no es una opción válida."
        ]
    }
}
```

### Response `422` — A column that is not a column

```json
{
    "message": "Columns.0 no puede tener más de 64 caracteres.",
    "errors": {
        "columns.0": [
            "Columns.0 no puede tener más de 64 caracteres."
        ]
    }
}
```

## Fetch an export

`GET /api/exports/{id}`

Returns the full export record including current `status` and (when ready)
a download URL.

### Path parameters

- `id` (integer, required) — Export ID.

### Example request

```bash
curl --request GET \
    --get "https://klozzo.com/api/exports/8" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
```

### Response `200`

```json
{
    "data": {
        "id": null,
        "format": "csv",
        "status": "pending",
        "total_rows": 0,
        "file_name": null,
        "filters": null,
        "columns": null,
        "error": null,
        "started_at": null,
        "finished_at": null,
        "expires_at": null,
        "created_at": null,
        "download_url": null
    }
}
```

## Delete an export

`DELETE /api/exports/{id}`

Deletes the export record and the underlying file from storage. Subsequent
download attempts will return 404.

### Path parameters

- `id` (integer, required) — Export ID.

### Example request

```bash
curl --request DELETE \
    "https://klozzo.com/api/exports/8" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
```

### Response `200`

```json
{
    "message": "Export deleted."
}
```

## Download export file

`GET /api/exports/{export_id}/download` (public — no token)

Streams the finished export file through a pre-signed link that needs no
token. Available only when `status=completed` and the
file has not been pruned.

**Do not build this URL yourself.** It is a pre-signed link: take the
`download_url` the export returns and follow it as-is. It carries no token
— the signature is the credential — which is what lets you hand it to a
browser, a download manager or a colleague without leaking an API key.
It stops working on `expires_at`, and a tampered or expired signature
answers `403`, not `404`.

### Path parameters

- `export_id` (integer, required) — Export ID.

### Example request

```bash
curl --request GET \
    --get "https://klozzo.com/api/exports/8/download" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
```

### Response `200` — streamed file download

```json
"<binary CSV or XLSX>"
```

### Response `403` — expired or tampered signature

```json
{
    "message": "Invalid signature."
}
```

### Response `404` — not ready or pruned

```json
{
    "message": "Not Found"
}
```