> ## Documentation Index
> Fetch the complete documentation index at: https://dialnexa.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Upload Workflow Leads
> Upload leads to a workflow.
Changes state - verify before retry
**Recommended.** This endpoint is part of the public `/v1` API reference and is the supported path for new integrations. See the [migration guide](/docs/api-reference/v1/migrating-to-v1) for versioning guidance.
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; all other 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](/docs/api-reference/v1/workflow-leads/delete), then upload the corrected record here.
For a one-shot list where every contact just gets a single call, [Create Batch Call](/docs/api-reference/v1/batches/create) is the simpler tool.
## File format
```
phone_number,name,city,product
9876543210,Priya Sharma,Mumbai,home_loan
9123456789,Rahul Mehra,Delhi,car_loan
```
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.
## 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.
## OpenAPI
````yaml POST /v1/workflows/{workflowId}/leads
openapi: 3.0.0
info:
title: DialNexa API
description: >-
Public REST API for the DialNexa voice AI platform. Versioned endpoints are
under /v1; unversioned endpoints are legacy and deprecated.
version: 1.0.0
servers:
- url: https://api.dialnexa.com
description: DialNexa production API
security:
- bearer: []
tags:
- name: API Keys
- name: Agent Functions
- name: Agents V1
- name: Agents2
- name: Batch Calls
- name: Batch Calls V1
- name: Call Logs
- name: Calls
- name: Calls V1
- name: Campaign Leads
- name: Campaigns
- name: External Webhooks
- name: Knowledge Base
- name: Knowledge Base V1
- name: LLMs
- name: LLMs V1
- name: Languages
- name: Languages V1
- name: Organization Phone Numbers
- name: Organization Phone Numbers V1
- name: Phone Number Pricing
- name: Phone Number Pricing V1
- name: Transcribers
- name: Transcribers V1
- name: User Webhooks
- name: User Webhooks V1
- name: V1
- name: Voices
- name: Voices V1
- name: Webcall
- name: Workflow Leads
- name: Workflow Leads V1
- name: Workflows
- name: Workflows V1
paths:
/v1/workflows/{workflowId}/leads:
post:
tags:
- Workflow Leads V1
- V1
summary: Upload Workflow Leads
description: Uploads and enrolls leads in one workflow from a supported file.
operationId: WorkflowLeadsV1Controller_uploadFile
parameters:
- name: workflowId
required: true
in: path
description: Workflow ID
schema:
type: string
example: workflow_abc123
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
file:
type: string
format: binary
description: CSV or Excel file with leads data
examples:
request:
summary: Upload workflow leads file
value:
file: workflow-leads.csv
responses:
'201':
description: File processed successfully.
content:
application/json:
examples:
success:
summary: Successful response
value:
statusCode: 201
message: Leads uploaded successfully
data:
'+919876543210':
- lead_abc123
count: 1
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
error:
summary: 400 Bad Request
value:
statusCode: 400
message: File must be a CSV or Excel file (.csv, .xlsx, .xls)
error: Bad Request
'401':
description: Unauthorized - missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
error:
summary: 401 Unauthorized
value:
statusCode: 401
message: API key is missing or invalid
error: Unauthorized
'403':
description: Forbidden - workflow does not belong to your organization.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
error:
summary: 403 Forbidden
value:
statusCode: 403
message: You do not have permission to access this workflow
error: Forbidden
'404':
description: Workflow not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
error:
summary: 404 Not Found
value:
statusCode: 404
message: Workflow not found
error: Not Found
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
error:
summary: 500 Internal Server Error
value:
statusCode: 500
message: Internal server error
error: Internal Server Error
security:
- bearer: []
components:
schemas:
ErrorResponse:
type: object
properties:
statusCode:
type: integer
example: 400
message:
oneOf:
- type: string
- type: array
items:
type: string
example: phone_number must be a valid E.164 phone number
error:
type: string
example: Bad Request
required:
- statusCode
- message
- error
securitySchemes:
bearer:
scheme: bearer
bearerFormat: JWT
type: http
````