> ## 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.

# Remove Workflow Lead

> Remove a single lead from an active workflow without stopping the workflow itself.

<Warning>
  **Legacy endpoint - deprecated.** Unversioned endpoints are scheduled for removal on **July 31, 2026**. Use the [`/v1` version](/docs/api-reference/v1/workflow-leads/delete) for new integrations. This endpoint remains available for existing integrations until then.
</Warning>

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 remove every lead, pause or cancel the entire workflow instead. See [Cancel Workflow](/docs/api-reference/workflows/cancel) or [Pause Workflow](/docs/api-reference/workflows/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 /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:
  /workflows/{workflowId}/leads/{id}:
    delete:
      tags:
        - Workflow Leads
      summary: Soft delete a lead (mark as deleted)
      description: >-
        **Legacy endpoint - deprecated, scheduled for removal on July 31,
        2026.** Use the `/v1` version for new integrations. 
      operationId: WorkflowLeadsController_softDelete
      parameters:
        - name: workflowId
          required: true
          in: path
          schema:
            type: string
        - name: id
          required: true
          in: path
          schema:
            type: string
        - name: x-organization-id
          in: header
          description: RSA encrypted organization ID (base64 format)
          required: true
          schema:
            type: string
            example: BASE64_ENCRYPTED_ORG_ID_HERE
      responses:
        '200':
          description: Lead soft deleted successfully
        '404':
          description: Lead not found
        '500':
          description: Internal server error
      deprecated: true
components:
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http

````