> ## 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.
# Delete Workflow Lead
> Soft delete a lead from a workflow.
Destructive
**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.
Removes a single lead from an active workflow. If the lead is currently inside a step that is in flight, for example a live call or a queued retry, that step is allowed to complete before the lead is detached from the workflow. Once removed, the lead does not advance to any further nodes, and any future calls or messages scheduled by downstream nodes are cancelled.
## When to use this
Lead-level removal is the safest way to honor an opt-out, fix a data-quality issue, or pull a single contact out of a long-running multi-step sequence without disrupting other leads in the same workflow. Common cases:
* **Opt-outs and Do Not Call requests**: remove the lead immediately so no further automated outreach is sent.
* **Data correction**: remove a lead that was enrolled with the wrong phone number; re-enroll the corrected record through [Upload Workflow Leads](/docs/api-reference/v1/workflow-leads/add).
* **Compliance escalations**: remove a lead from the workflow while you investigate a complaint, leaving the lead's call history intact in [Call Logs](/docs/api-reference/call-logs/list).
To stop workflow execution for every lead, use [Update Workflow Status](/docs/api-reference/v1/workflows/status) with `action: "pause"`.
## Behavior
* The lead's historical call logs and per-step status remain queryable.
* In-flight steps are allowed to finish (DialNexa does not hang up a live call to honor the removal).
* Subsequent scheduled steps for this lead are cancelled.
## Path parameters
| Parameter | Description |
| ------------ | ------------------------------------------------------------------ |
| `workflowId` | The workflow ID the lead is enrolled in. |
| `id` | The workflow-lead enrollment ID, for example `wlead_p3q8zv5bk2mx`. |
## Errors
* `404 Not Found` is returned when the workflow or lead does not exist, or the lead is not enrolled in the specified workflow.
* `409 Conflict` is returned when the lead is in a terminal state that does not need removal (already completed or already removed).
## Related endpoints
* [Upload Workflow Leads](/docs/api-reference/v1/workflow-leads/add): enroll a new lead.
* [List Workflow Leads](/docs/api-reference/v1/workflow-leads/list): view current enrollments and their status.
* [Lead History](/docs/api-reference/v1/workflow-leads/history): review the steps a lead has already moved through.
## OpenAPI
````yaml DELETE /v1/workflows/{workflowId}/leads/{id}
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/{id}:
delete:
tags:
- Workflow Leads V1
- V1
summary: Delete Workflow Lead
description: Soft deletes one lead from a workflow.
operationId: WorkflowLeadsV1Controller_softDelete
parameters:
- name: workflowId
required: true
in: path
description: Workflow ID
schema:
type: string
example: workflow_abc123
- name: id
required: true
in: path
description: Lead ID
schema:
type: string
example: lead_abc123
responses:
'200':
description: Lead soft-deleted successfully.
content:
application/json:
examples:
success:
summary: Successful response
value:
statusCode: 200
message: Lead soft-deleted successfully
'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: Lead not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
error:
summary: 404 Not Found
value:
statusCode: 404
message: Workflow lead 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
````