Skip to main content
POST
Bulk entity export

Overview

Exports entities using the same filters as GET /entities and builds a file (csv, xlsx, or json). With deliveryMode: "download_only", the file remains available in export history without sending email or consuming email credits. With deliveryMode: "email", it is also sent to the specified recipients. Returns 202 with jobId.

Endpoint

Auth, permissions, marketplace

Always requires Authorization, X-Organization-ID, and entities:export. The global_sender_email integration, sender, and balance are checked only for deliveryMode: "email"; billing is per recipient. download_only does not consume email credits.

Domain and sender

Same rules as the PDF email export:
  • fromEmail: verified org domain; no sender row required.
  • fromSenderId: UUID in organization_email_senders.
  • Do not send both.

Request Body

string
download_only to keep the file only in export history, or email to add email delivery. For backward compatibility, omitting it while providing recipients is treated as email.
string[]
Required and non-empty for deliveryMode: "email" (max 26 after deduplication). Must be [] for download_only.
string
required
csv, xlsx, or json.
object
Same shape as GET /entities query filters. Default {}.
string
en, es, or pt for the completion email when deliveryMode is email.
string[]
Optional snake_case export column keys; omit or [] for all allowed columns.
string (uuid)
Sender UUID. Applies only to email and is mutually exclusive with fromEmail.
string
From address on a verified domain. Applies only to email and is mutually exclusive with fromSenderId.

Example without email

Example with email

202 response

Job follow-up

  • GET /entities/export/jobs β€” paginated organization export history.
  • GET /entities/export/jobs/{jobId} β€” status (queued, running, completed, completed_email_failed, failed) and delivery mode.
  • GET /entities/export/jobs/{jobId}/download β€” authenticated download while the file remains available.
  • If email delivery fails after file generation, the job becomes completed_email_failed and remains downloadable from history.
List and detail responses include fileExpiresAt. It is nullable: null means the stored file has no expiration. linkExpiresAt is separate and only indicates when the signed link sent by email stops working. New entity and transaction export files do not expire and remain available in history unless they are explicitly removed.

400 errors

Mode errors include EXPORT_RECIPIENTS_REQUIRED, EXPORT_RECIPIENTS_NOT_ALLOWED, and EXPORT_STORAGE_REQUIRED. With deliveryMode: "email", the pre-flight errors from report-export-email also apply, including unverified domain and insufficient balance.