---
title: "Create Export"
method: POST
path: "/exports"
tags: ["Exports"]
---

# Create Export

`POST /exports`

## Request

- Base URL: `https://api.burodeingresos.com`
- URL: `https://api.burodeingresos.com/exports`
- Auth: API key in header `X-API-Key`
- TypeScript: <https://skmtc.dev/burodeingresos/apis/bur-de-ingresos-api/docs/exports/post.ts> (a function with typed inputs; its response is checked against the schema)

Requests an asynchronous CSV export of a **completed** verification bulk. One file is generated per entity. The company is always taken from the API key, never from the request body.

Requests are **idempotent**: the same `bulk_id` with the same `entities` returns `202` with the same `export_id` instead of generating a duplicate. A `failed` or `expired` export can be requested again.

When the files are ready, the `export.completed` webhook event is sent (no download links in the event). Webhooks created before this feature launched must subscribe to the event via `PATCH /webhooks/{webhook_id}`.

## Request body

- CreateExportRequest
  - `bulk_id` string, uuid, required: A completed verification bulk that belongs to your account.
  - `entities` string[], required: Entities to export; one CSV file is generated per entity. Order and duplicates are ignored.
  - `include_payment_info` boolean: Optional. When true, `invoices.csv` includes a `payment_info` column with the payment details of each invoice, with the same fields as `GET /invoices?include_payment_info=true`. Invoices with no associated payments carry an empty array `[]`. The flag is part of the idempotency key: the same `bulk_id` and `entities` with a different `include_payment_info` value is a new export. Defaults to false.
  - `estimates` object: Optional. Options for `estimates.csv`, with the same values, defaults and validation as `GET /estimates/{identifier}`. Only allowed when `entities` includes `estimates`; otherwise the request fails with 400. An invalid value fails with 400 `invalid_parameter`. The resolved options are part of the idempotency key: the same `bulk_id` and `entities` with different estimates options is a new export.
    - `window_months` 3 | 6 | 9 | 12 | 24: Months of history used. See `GET /estimates/{identifier}`.
    - `sources` 'all' | 'invoices' | 'employments': Data used for the estimates. See `GET /estimates/{identifier}`.
    - `as_of` string, date: Computes the estimates as of this date (`YYYY-MM-DD`, Mexico City time). Defaults to the day the export is requested, and that date is kept for the life of the export. Cannot be in the future, and `as_of` minus `window_months` must be within the last 24 months.
    - `history` boolean: When `true`, `estimates.csv` has one row per person per month, going back from the month of `as_of`, up to 18 months. When `false`, one row per person.

## Response `202`

Export accepted — or already requested with the same scope, in which case the same export_id is returned.

- ExportResponse
  - `export_id` string, uuid
  - `bulk_id` string, uuid
  - `estimates` object: Present only when `estimates` was requested. The options `estimates.csv` is computed with, defaults included.
    - `window_months` integer
    - `sources` string
    - `as_of` string, date
    - `history` boolean
  - `status` 'queued' | 'processing' | 'completed' | 'failed' | 'expired'
  - `requested_at` string, date-time
  - `finished_at` string, date-time
  - `expires_at` string, date-time: The export is available for 7 days after completion. After this moment the files are purged.
  - `error_code` string: Present only when status is failed.
  - `error_message` string: Present only when status is failed.
  - `files` ExportFile[]: Empty until the export completes, and empty again once it expires.
    - `name` string
    - `rows` integer
    - `bytes` integer
    - `url` string: Signed download link, valid for about 1 hour. Re-issued fresh on every read of GET /exports/{export_id}. Only present while the export is completed and not expired.
    - `expires_at` string, date-time: Expiration of this download link.

## Other responses

- `400`: Validation error.
- `404`: The bulk_id does not exist on your account.
- `409`: The bulk is still being processed. Wait until it finishes and request the export again.

## Changes

- **2026-11-03** `98eb3984cffb`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/burodeingresos/apis/bur-de-ingresos-api/changes/exports/post.md)

---

[API](https://skmtc.dev/burodeingresos/apis/bur-de-ingresos-api.md) - [All operations](https://skmtc.dev/burodeingresos/apis/bur-de-ingresos-api/llms.txt) - [OpenAPI document](https://skmtc.dev/burodeingresos/apis/bur-de-ingresos-api/revisions/98eb3984cffb?raw)