Upload Workflow Leads

POST

workflows

{workflowId}

leads

curl --request POST \
  --url https://api.dialnexa.com/v1/workflows/{workflowId}/leads \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file=@example-file

import requests

url = "https://api.dialnexa.com/v1/workflows/{workflowId}/leads"

files = { "file": ("example-file", open("example-file", "rb")) }
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('file', 'workflow-leads.csv');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://api.dialnexa.com/v1/workflows/{workflowId}/leads', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.dialnexa.com/v1/workflows/{workflowId}/leads",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\nworkflow-leads.csv\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.dialnexa.com/v1/workflows/{workflowId}/leads"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\nworkflow-leads.csv\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.dialnexa.com/v1/workflows/{workflowId}/leads")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\nworkflow-leads.csv\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.dialnexa.com/v1/workflows/{workflowId}/leads")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\nworkflow-leads.csv\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "error": false,
  "statusCode": 201,
  "message": "Success",
  "data": {
    "statusCode": 201,
    "message": "Leads uploaded successfully",
    "data": {
      "+919876543210": [
        "lead_abc123"
      ],
      "+919123456789": [
        "lead_def456"
      ]
    },
    "count": 2,
    "tags": [
      "priority"
    ],
    "dnd_skipped_count": 0
  },
  "timestamp": "2026-09-07T06:00:00.000Z"
}

Changes state - verify before retry Uploads leads into a workflow from a CSV or Excel file. Each row with a phone number becomes one enrolled lead. Ordinary data columns become dynamic variables available in the agent’s prompt at each voice call step.

Draft workflows are replaced, others are appended

What an upload does to the leads already in the workflow depends on the workflow’s status:

Workflow status	Effect of an upload	When the new leads start
`draft`	Replaces every lead in the workflow. Earlier lead IDs stop working.	When the workflow is activated.
`active`	Adds to the existing leads.	Immediately.
`paused`	Adds to the existing leads.	Only after `activate`. `resume` does not start them.
`completed` or `cancelled`	Adds to the existing leads.	Never: these workflows cannot be activated again.

So on a draft workflow, upload the complete lead list in one file. To add more leads later, activate the workflow first.

When to use this

Enrolling a cohort: add a set of leads to a workflow that is already built.
Incremental enrollment: keep feeding new leads into an active workflow as they arrive, unlike a batch call where the list is fixed at creation.
Re-enrollment after correction: on an active workflow, remove a lead that was uploaded with bad data via Delete Workflow Lead, then upload the corrected record here. On a draft workflow, upload the corrected complete file instead.

For a one-shot list where every contact just gets a single call, Create Batch Call is the simpler tool.

File format

Send a CSV, XLSX, or XLS file up to 10 MB in the multipart file field; a larger file returns 413. The file name must end in .csv, .xlsx or .xls, and the part’s Content-Type must be text/csv, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet or application/vnd.ms-excel. A part sent as application/octet-stream is rejected with 400.

phone_number,name,city,product
+919876543210,Priya Sharma,Mumbai,home_loan
+919123456789,Rahul Mehra,Delhi,car_loan

Write phone numbers in international format with the country code, for example +919876543210. A number without a country code is read as if its first digits were one: 9876543210 is read as +98... and fails destination validation. Numbers are stored exactly as written in the file.

Column	Meaning
`phone_number`	Required. The header can also be `phone`, `mobile`, `mobile_number`, `cell`, `telephone` or `tel`; case, spaces, hyphens and underscores are ignored. In a CSV, a row with an empty phone number is skipped; in an Excel file it fails the upload.
`tags`	Optional, reserved. Row-specific labels, comma- or pipe-separated. Not a prompt variable.
`notes`	Optional, reserved. Plain text is stored as `{"text": "..."}`; a JSON object of at most 15 keys is stored as sent. A value that starts with `{` or `[` but is not valid JSON, or a JSON array, returns `400`. Not a prompt variable.
`agent_transfer_destinations`	Optional, reserved. Pipe-separated transfer destinations, checked for format: an invalid value fails the upload with `400`. Workflow leads do not store this column; transfers on workflow calls use the destinations configured on the agent. Not a prompt variable.
Any other column	A dynamic variable, stored as `{ "key": "<header>", "value": "<cell>" }` in the lead’s `dynamic_variables`. A blank cell adds no entry; values are trimmed and inner whitespace is collapsed.

Response

A 201 response carries, inside data:

data: the created lead IDs (lead_...) grouped by phone number, as written in the file.
count: the number of leads created.
dnd_skipped_count: rows left out because their number is on the workspace’s DND list. 0 when none was.
tags: every tag applied in this upload.
errors: present only when some rows failed, one message per row. Rows are numbered from Row 1 in order of the rows that have a phone number; blank rows and rows without a number are skipped and not counted. The message is then Leads uploaded with N row(s) failed. instead of Leads uploaded successfully, and the status is still 201. On an active workflow, a row whose lead was created but could not be started is also listed here; that lead is included in count and data. Check List Workflow Leads before uploading such a row again, so the contact is not enrolled twice.
unused_columns and allowed_columns: present only when some data columns are not referenced by any node or agent prompt in the workflow. The columns are still stored on the leads. The reserved notes and agent_transfer_destinations columns can also be listed in unused_columns.

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. On a draft workflow, a retry replaces them.

Destination validation

If the workflow contains Voice Call nodes, every row is validated before any lead is created. 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. Validation failures return 400 Bad Request with grouped row-level errors and no lead is created, so you can fix the file and retry. These errors number rows by their line in the file, with the header as row 1, so the first data row is row 2.

Numbers on the DND list

Rows whose number is on the workspace’s DND list are skipped: no lead is created and nothing is processed for them, and dnd_skipped_count in the response counts them. If every row’s number is on the DND list, the upload returns 400 Bad Request (All N numbers in this file are on your workspace's DND list, so there is nothing to call.) and creates nothing; on a draft workflow the existing leads are kept. A lead whose number is added to the DND list after upload is stopped before its next step of any kind, with the lead status dnd_blocked. The DND list is managed in the dashboard, not through the API.

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

required

CSV, XLSX, or XLS file, at most 10 MB (10485760 bytes). The part's Content-Type must be text/csv, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet or application/vnd.ms-excel, and the file name must end in .csv, .xlsx or .xls.

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

object

required

Show child attributes

timestamp

string<date-time>

required

Upload Workflow Leads

curl --request POST \
  --url https://api.dialnexa.com/v1/workflows/{workflowId}/leads \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file=@example-file

import requests

url = "https://api.dialnexa.com/v1/workflows/{workflowId}/leads"

files = { "file": ("example-file", open("example-file", "rb")) }
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('file', 'workflow-leads.csv');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://api.dialnexa.com/v1/workflows/{workflowId}/leads', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.dialnexa.com/v1/workflows/{workflowId}/leads",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\nworkflow-leads.csv\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.dialnexa.com/v1/workflows/{workflowId}/leads"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\nworkflow-leads.csv\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.dialnexa.com/v1/workflows/{workflowId}/leads")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\nworkflow-leads.csv\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.dialnexa.com/v1/workflows/{workflowId}/leads")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\nworkflow-leads.csv\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "error": false,
  "statusCode": 201,
  "message": "Success",
  "data": {
    "statusCode": 201,
    "message": "Leads uploaded successfully",
    "data": {
      "+919876543210": [
        "lead_abc123"
      ],
      "+919123456789": [
        "lead_def456"
      ]
    },
    "count": 2,
    "tags": [
      "priority"
    ],
    "dnd_skipped_count": 0
  },
  "timestamp": "2026-09-07T06:00:00.000Z"
}

Overview

Endpoints

Draft workflows are replaced, others are appended

When to use this

File format

Tags

Response

Destination validation

Numbers on the DND list

Authorizations

Path Parameters

Body

Response

​Draft workflows are replaced, others are appended

​When to use this

​File format

​Tags

​Response

​Destination validation

​Numbers on the DND list

Authorizations

Path Parameters

Body

Response

Draft workflows are replaced, others are appended

When to use this

File format

Tags

Response

Destination validation

Numbers on the DND list