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

> Remove one lead from a workflow.

<span data-api-safety-label="destructive"><Badge color="red" size="sm" shape="pill">Destructive</Badge></span>
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 available in [Call History](/docs/monitoring/call-history).

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 `/v1` REST API for the DialNexa voice AI platform.
  version: 1.0.0
servers:
  - url: https://api.dialnexa.com
    description: DialNexa production API
security:
  - bearer: []
tags:
  - name: Agents
  - name: Batch Calls
  - name: Calls
  - name: Knowledge Base
  - name: Languages
  - name: LLMs
  - name: Phone Numbers
  - name: Transcribers
  - name: Webhooks
  - name: Voices
  - name: Workflows
  - name: Workflow Leads
paths:
  /v1/workflows/{workflowId}/leads/{id}:
    delete:
      tags:
        - Workflow Leads
      summary: Delete Workflow Lead
      description: >-
        Removes one lead from a workflow and prevents it from advancing to later
        steps.
      operationId: deleteWorkflowLead
      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 removed successfully.
          content:
            application/json:
              examples:
                success:
                  summary: Successful response
                  value:
                    statusCode: 200
                    message: Lead removed 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
      type: http

````