Skip to main content
POST
/
entities
/
export
/
jobs
Bulk entity export by email
curl --request POST \
  --url http://api.gu1.ai/entities/export/jobs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "recipientEmails": [
    "<string>"
  ],
  "format": "<string>",
  "filters": {},
  "emailLocale": "<string>",
  "columns": [
    "<string>"
  ],
  "fromSenderId": {},
  "fromEmail": "<string>"
}
'

​
Overview

Exports entities using the same filters as GET /entities, builds a file (csv, xlsx, or json), and delivers it by email. Returns 202 with jobId; poll status via GET /entities/export/jobs/{jobId}.

​
Endpoint

POST http://api.gu1.ai/entities/export/jobs

​
Auth, permissions, marketplace

Same as Email entity PDF report: Authorization, X-Organization-ID, entities:export, global_sender_email enabled, billing per recipient in recipientEmails.

​
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

​
recipientEmails
string[]
required
Email recipients (max 26 after deduplication). Only these addresses; the API user’s email is not auto-added.
​
format
string
required
csv, xlsx, or json.
​
filters
object
Same shape as GET /entities query filters. Default {}.
​
emailLocale
string
en, es, or pt for the completion email.
​
columns
string[]
Optional snake_case export column keys; omit or [] for all allowed columns.
​
fromSenderId
string (uuid)
Sender UUID. Mutually exclusive with fromEmail.
​
fromEmail
string
From address on a verified domain. Mutually exclusive with fromSenderId.

​
Example

{
  "recipientEmails": ["analyst@example.com"],
  "format": "xlsx",
  "emailLocale": "en",
  "fromEmail": "exports@your-domain.com",
  "filters": { "type": "person" }
}

​
202 response

{
  "jobId": "job-uuid",
  "message": "…"
}

​
Job follow-up

  • GET /entities/export/jobs/{jobId} — status (queued, running, completed, failed).
  • GET /entities/export/jobs/{jobId}/download — download metadata when available.
  • Completion email may include a signed link (depends on server S3 settings).

​
400 errors

Same pre-flight codes as report-export-email.