Ad-hoc audience CSV export

A saved segment is the right home for an audience you target repeatedly. But sometimes you need the rows behind a filter exactly once — a compliance spot-check, a partner handoff, an analyst’s exploratory pull — and creating a segment purely to hold a transient membership is noise. The ad-hoc export endpoint resolves your filter live against your contacts and hands you the CSV directly: nothing is persisted, nothing waits on a refresh schedule.

Ad-hoc vs. saved segment export

Two CSV export surfaces exist; pick by how long the audience needs to live.

	Ad-hoc export	Saved segment export
Endpoint	`POST /api/v1/segments/export.csv`	`GET /api/v1/contacts/segments/:id/export.csv`
Audience source	Filter AST in the request body	A persisted segment’s materialized membership
Wait before download	None — the filter resolves at request time	First export waits on the segment’s refresh cycle
Row ceiling	50,000	500,000 (streamed)
Audit record	One entry per download	One entry per download

Rule of thumb: if you would delete the segment right after downloading, use the ad-hoc export.

Authentication and permissions

PII bulk pulls are privileged, and this endpoint gates exactly like the saved export:

The caller must hold an owner, admin, or developer role.
The API key must carry the contacts:write scope. Viewer roles and contacts:read-only keys are rejected with a 403.
Exports are rate-limited to 5 requests per minute, and every download — row counts included — is written to your audit log (segment.audience_exported).

Request shape

The body carries the same Filter AST the segment builder and POST /api/v1/segments/auto-suggest produce — fields come from the segment filter allowlist, and groups nest up to three levels deep.

curl -X POST https://api.orbit.devotel.io/api/v1/segments/export.csv \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -o enterprise-no-consent.csv \
  -d '{
    "filters": {
      "and": [
        { "field": "custom_attribute.plan_tier", "op": "equals", "value": "enterprise" },
        { "field": "sms_optin", "op": "equals", "value": false }
      ]
    },
    "limit": 10000,
    "filename": "enterprise-no-consent"
  }'

Field	Required	Description
`filters`	yes	The audience definition — the Filter AST shape documented under build a segment.
`limit`	no	Row cap below the 50,000 ceiling (`1`–`50,000`), clamped server-side. Useful for a quick sample.
`filename`	no	Filename stem for the download (sanitized, truncated at 80 characters). A date suffix is appended, so the example above lands as `enterprise-no-consent-2026-08-26.csv`.

Row cap and truncation

A single ad-hoc export resolves at most 50,000 rows (unlike the saved export, which streams up to 500,000). If the filter reaches the cap, the response still succeeds with the first 50,000 rows and sets the X-Export-Truncated: true response header — check that header whenever the row count matters. To pull more than the cap, persist the audience as a segment and use the saved export path.

CSV columns and PII visibility

One row per matched contact, with this header row:

contact_id,first_name,last_name,email,phone,country_code,lifecycle_stage,tags,created_at

Every row passes through the same PII visibility rules as the saved export and the dashboard: the phone and email columns are masked or revealed to match what the caller’s role and reveal context would see in the UI. An owner with an active reveal gets full values; a caller without one gets masked values. A CSV pulled by two different callers can differ in exactly those columns — never assume a second pull by another teammate will match byte-for-byte.

Use cases

GDPR ingest verification. After a bulk import, export “contacts created in the last hour with missing consent fields” and confirm the ingest mapped them before anything downstream picks them up.
Partner handoff. A partner asks for a segment of your audience once. Send the filter, get the CSV, delete nothing because you never created anything.
Exploratory analysis. An analyst iterating on a filter — preview the size with POST /api/v1/contacts/segments/preview, then pull the rows to a spreadsheet the moment the definition is right.

When to save the segment instead

Materialize a real segment — POST /api/v1/contacts/segments — when the audience has a future, because several downstream surfaces only read saved segments:

Scheduled refresh. auto_refresh keeps membership current on a schedule (12 hours up to monthly), so exports and campaigns track a moving population without re-sending the filter.
Campaigns and flows. Targeting, enroll-on-entry, and suppression all reference a segment id; a one-shot export cannot.
Ad-network activation. Audience sync to Meta, Google, TikTok, and the other supported platforms pushes a saved segment.
Above-cap or repeat downloads. The saved export streams over the 50,000-row ad-hoc ceiling, and re-downloading a saved segment skips re-resolving the filter.

Anything else — once, exploratory, or throwaway — belongs on the ad-hoc path.

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

Export a one-off audience to CSV without saving a segment

Ad-hoc audience CSV export

Ad-hoc vs. saved segment export

Authentication and permissions

Request shape

Row cap and truncation

CSV columns and PII visibility

Use cases

When to save the segment instead

See also

​Ad-hoc audience CSV export

​Ad-hoc vs. saved segment export

​Authentication and permissions

​Request shape

​Row cap and truncation

​CSV columns and PII visibility

​Use cases

​When to save the segment instead

​See also

Ad-hoc audience CSV export

Ad-hoc vs. saved segment export

Authentication and permissions

Request shape

Row cap and truncation

CSV columns and PII visibility

Use cases

When to save the segment instead

See also