Skip to main content

​
What is a Workflow Campaign?

A campaign runs one published workflow version over a batch of contacts. Where the run endpoint handles one contact per request, a campaign takes uploads of up to 150,000 rows and turns each accepted row into an execution when started. Two things are fixed at creation time:
  • The version pin. Passing "version": null pins the latest published version at that moment; publishing newer versions later never changes a created campaign.
  • The entry schema. Uploads are validated against the pinned version’s start-node fields.
The lifecycle is draft → scheduled → running → (paused ↔ running) → completed or aborted.

​
Running a campaign

1

Create the campaign

Use the Create Campaign API with the workflow to run:
2

Fetch the CSV template

The template endpoint returns the exact header row this campaign expects — the pinned version’s declared fields in author order:
3

Upload entries

Upload contacts with the Upload Entries API — as CSV or as a JSON array; the Content-Type header decides:
Validation runs in two stages. A whole-upload shape check first — an undeclared column rejects everything with 422 unknown_field, a missing required column with missing_required_field, and nothing is persisted. Then rows are validated individually: failures are reported per row (invalid_phone, invalid_field_type, missing_required_value, duplicate_reference_id, …) while good rows are accepted. For CSV, row counts the header as line 1, so the first data row is 2.
Fix-and-reupload just works: a row whose earlier version failed validation is replaced in place and counted in corrected. reference_id is each contact’s identity — omit it and one is derived from the row’s content, so identical rows deduplicate automatically.
4

Start the campaign

If the pinned definition contains an agent node, starting the campaign places real calls to every pending entry.
While it runs you can pause (nothing new starts; timer waits hold), resume, or abort (terminal — every execution stops before its next external action). A single contact can be stopped with the Cancel Execution API.
5

Monitor progress

List executions as they progress, filtered by status or outcome:
And pull the aggregated report — the termination_reasons keys are your end nodes’ labels, and funnel counts attempts per node of your definition:

​
Next Steps

Workflow Campaign APIs

Every campaign endpoint in detail

Workflow Execution APIs

Follow one contact node by node

Quickstart

Build and publish the workflow a campaign runs

Batch Calling

Single-call batches, when you don’t need a graph