Skip to main content
POST
Upload Workflow Leads
Changes state - verify before retry Uploads leads into a workflow from a CSV or Excel file. Each row in the file becomes one enrolled lead. The file must include a phone_number column; ordinary data columns become dynamic variables available in the agent’s prompt at each voice call step.

When to use this

  • Enrolling a cohort: add a new set of leads to a workflow that is already built, whether it is active now or will be activated later.
  • Incremental enrollment: keep feeding new leads into a long-running workflow as they arrive, unlike a batch call where the list is fixed at creation.
  • Re-enrollment after correction: remove a lead that was uploaded with bad data via Delete Workflow Lead, then upload the corrected record here.
For a one-shot list where every contact just gets a single call, Create Batch Call is the simpler tool.

File format

The response groups created lead IDs by phone number and includes a count of created leads. Leads begin processing once the workflow is active. Their progress through the nodes depends on the outcomes of each step.

Upload Workflow Leads With Tags

Send a CSV, XLSX, or XLS file up to 10 MB. Add an optional multipart tags field, such as priority,september, to label every lead. A reserved tags column in the file adds row-specific labels. It is not a prompt variable. Tags are lowercased, whitespace-normalized, and deduplicated, with at most 20 tags per lead and 40 characters per tag. The response includes the applied tags along with lead IDs and count. Check List Workflow Leads after upload. If the workflow is active, new leads can immediately advance into calls and incur charges. After an error or timeout, inspect enrolled leads before retrying the file, because some leads may already have been created.

Destination validation

If the workflow contains Voice Call nodes, uploaded leads are validated before enrollment. A lead’s phone_number must be valid and must be allowed by at least one active Voice Call phone number in the workflow. For non-SIP routes, the destination country and prefix must be enabled in Workspace Settings > Telephony Config. Validation failures return 400 Bad Request with grouped row-level errors so you can fix the file and retry.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

workflowId
string
required

Workflow ID

Example:

"workflow_abc123"

Body

multipart/form-data
file
file
required

CSV, XLSX, or XLS file, at most 10 MB (10485760 bytes).

tags
string

Optional comma- or pipe-separated labels for every lead. Unioned with the reserved tags column, normalized to lowercase, at most 20 tags per lead and 40 characters per tag.

Response

File processed successfully.

success
enum<boolean>
required
Available options:
true
error
enum<boolean>
required
Available options:
false
statusCode
integer
required
Example:

201

message
string
required
Example:

"Success"

data
any
required
timestamp
string<date-time>
required