v1

latestOpenAPI 3.1.0MIT2026-07-243952451019.0 KB

Contacts::ExportAction

Create Export Action

Export a collection of contacts to a CSV file. Supply fields to specify which contact columns appear in the CSV (including custom attribute keys). The action runs asynchronously — poll the returned record with GET /api/v2/contacts/export_actions/{id}. Once complete, file_url contains the download URL for the generated CSV. Exactly one target selection must be supplied: stable_id, stored_filter_id (alias filter_id), target_ids, or target_all. Returns 422 if none is provided or if the supplied value is invalid.

post/workspaces/{workspace_id}/contacts/export_actions

Path parameters

workspace_idinteger required

Request body

Example request

{
  "contacts_export_action": {
    "contacts_export_action": {
      "fields": [
        "email_address",
        "first_name",
        "tag_ids"
      ],
      "stored_filter_id": "7"
    }
  }
}

Response

Created

idinteger

Export Action ID

public_idstring nullable

Export Action public ID

workspace_idinteger

Workspace ID

fieldsstring[] nullable

The contact field keys to include as columns in the exported CSV (e.g. ["email_address", "first_name", "tag_ids"]). Custom attribute keys are also accepted.

file_urlstring nullable

Download URL for the generated CSV file. null until the async export job completes.

filter_idinteger nullable

ID of the Refine::StoredFilter that drives target selection. Populated automatically when stable_id or stored_filter_id is supplied on create. null when the action targets explicit target_ids or target_all.

target_allboolean nullable

When true the action targets every contact in the workspace. Mutually exclusive with stable_id, stored_filter_id, and target_ids.

target_idsinteger[] nullable

Explicit list of targeted contacts as raw integer IDs. The response echoes the stored integer IDs, not the public IDs passed on create.

target_countinteger nullable

Total number of contacts selected for this action. null until the async job has resolved the audience size.

performed_countinteger nullable

Number of contacts processed so far. Poll this field alongside target_count to track async progress.

created_by_idinteger nullable

ID of the workspace membership that created this action.

approved_by_idinteger nullable

ID of the membership that approved this action (reserved for future use).

scheduled_forstring date-time nullable

When set, the action will not execute until this datetime. null means execute immediately.

started_atstring date-time nullable

Datetime the async job began processing contacts. null until started.

completed_atstring date-time nullable

Datetime the async job finished. null until complete.

created_atstring date-time nullable

Created at datetime

updated_atstring date-time nullable

Updated at datetime

Example response

{
  "id": 1,
  "public_id": "dE6fG7",
  "workspace_id": 42000,
  "fields": [
    "email_address",
    "first_name",
    "tag_ids"
  ],
  "file_url": null,
  "filter_id": 7,
  "target_all": false,
  "target_ids": [],
  "target_count": 1500,
  "performed_count": 0,
  "created_by_id": 5,
  "approved_by_id": null,
  "scheduled_for": null,
  "started_at": null,
  "completed_at": null,
  "created_at": "2025-01-01T00:00:00.000Z",
  "updated_at": "2025-01-01T00:00:00.000Z"
}