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

Destructive
Marks a single lead as removed from the workflow. The lead disappears from [List Workflow Leads](https://dialnexa.com/docs/api-reference/v1/workflow-leads/list.md) and no longer matches inbound calls. Removal does not cancel steps already scheduled for that lead and does not interrupt a step in flight: if the lead is waiting in a time step, it still moves on when the wait expires, and a Voice Call node it reaches still places a call. Pausing the workflow only holds that call until the workflow is active again; it does not cancel it (see [Update Workflow Status](https://dialnexa.com/docs/api-reference/v1/workflows/status.md#what-pausing-does-not-stop)).

## When to use this

Use lead-level removal to remove a contact from the lead list or correct enrollment data. For an opt-out that must block future outbound calls and workflow processing, add the number to the workspace [DNC list](https://dialnexa.com/docs/platform/dnc-list.md); deleting a lead alone does not cancel scheduled activity. Common cases:

* **Opt-outs and Do Not Call requests**: remove the lead so it stops matching inbound calls and leaves the lead list. Check [Lead History](https://dialnexa.com/docs/api-reference/v1/workflow-leads/history.md) for a step that is still scheduled, because removal does not cancel it.
* **Data correction**: remove a lead that was enrolled with the wrong phone number; re-enroll the corrected record through [Upload Workflow Leads](https://dialnexa.com/docs/api-reference/v1/workflow-leads/add.md). On a draft workflow an upload replaces every lead, so upload the corrected complete file instead.
* **Compliance escalations**: remove a lead from the workflow while you investigate a complaint, leaving the lead's call history available in [Call History](https://dialnexa.com/docs/monitoring/call-history.md).

To stop new leads from starting in the workflow, use [Update Workflow Status](https://dialnexa.com/docs/api-reference/v1/workflows/status.md) with `action: "pause"`; leads already inside a step keep advancing.

## Behavior

* The lead's historical call logs and step history remain queryable.
* In-flight steps are allowed to finish (DialNexa does not hang up a live call to honor the removal).
* Steps already scheduled for the lead are not cancelled by this call and can still place a call.
* The lead's [Lead History](https://dialnexa.com/docs/api-reference/v1/workflow-leads/history.md) stays readable after removal.

## Path parameters

| Parameter | Description |
| - | - |
| `workflowId` | The workflow ID the lead is enrolled in, for example `workflow_m3v7zb9rk2px4q`. |
| `id` | The workflow lead ID, for example `lead_p3q8zv5bk2mx7d`. |

## Errors

* `404 Not Found` is returned when the workflow or lead does not exist, the lead is not enrolled in the specified workflow, or it was already removed.

## Related endpoints

* [Upload Workflow Leads](https://dialnexa.com/docs/api-reference/v1/workflow-leads/add.md): enroll a new lead.
* [List Workflow Leads](https://dialnexa.com/docs/api-reference/v1/workflow-leads/list.md): view current enrollments and their status.
* [Lead History](https://dialnexa.com/docs/api-reference/v1/workflow-leads/history.md): 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: Organization Folders
  - name: Transcribers
  - name: Webhooks
  - name: Voices
  - name: Workflows
  - name: Workflow Leads
  - name: Authentication
  - name: Agent Builder
  - name: Agent Evaluations
paths:
  /v1/workflows/{workflowId}/leads/{id}:
    delete:
      tags:
        - Workflow Leads
      summary: Delete Workflow Lead
      description: >-
        Removes one lead from a workflow. The lead leaves the lead list and no
        longer matches inbound calls. Steps already scheduled or in progress for
        the lead are not cancelled and can still place a call.
      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:
                    success: true
                    error: false
                    statusCode: 200
                    message: Success
                    data:
                      statusCode: 200
                      message: Lead soft-deleted successfully
                    timestamp: '2026-09-07T06:00:00.000Z'
              schema:
                type: object
                required:
                  - success
                  - error
                  - statusCode
                  - message
                  - data
                  - timestamp
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  error:
                    type: boolean
                    enum:
                      - false
                  statusCode:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: Success
                  data:
                    type: object
                    properties:
                      statusCode:
                        type: number
                        example: 200
                      message:
                        type: string
                        description: Confirmation text.
                  timestamp:
                    type: string
                    format: date-time
        '401':
          description: Unauthorized - missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 401 Unauthorized
                  value:
                    statusCode: 401
                    error: true
                    success: false
                    data: []
                    message: Invalid API key
                    errors: []
        '404':
          description: Lead not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 404 Not Found
                  value:
                    statusCode: 404
                    error: true
                    success: false
                    data: []
                    message: Workflow lead with ID Bv7nC2xKs5DqYw not found
                    errors: []
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 500 Internal Server Error
                  value:
                    statusCode: 500
                    error: true
                    success: false
                    data: []
                    message: Internal server error
                    errors: []
      security:
        - bearer: []
components:
  schemas:
    ErrorResponse:
      type: object
      description: Error body on endpoints without response filtering.
      properties:
        statusCode:
          type: integer
          example: 404
        error:
          type: boolean
          enum:
            - true
        success:
          type: boolean
          enum:
            - false
        data:
          oneOf:
            - type: object
              properties:
                code:
                  type: string
                  description: Machine-readable refusal code.
            - type: array
              items: {}
          description: >-
            For a coded refusal, an object with code and the details listed for
            that code. Otherwise an empty array.
        message:
          type: string
        errors:
          type: array
          items:
            type: string
          description: Validation messages for a 400. Empty for other errors.
        validation_errors:
          type: array
          description: >-
            Present when uploaded rows fail number validation (batch and
            workflow lead uploads): one group per distinct error.
          items:
            type: object
            properties:
              error:
                type: string
              rows:
                type: array
                items:
                  type: integer
                description: Row numbers with this error.
              phone_numbers:
                type: array
                items:
                  type: string
        invalid_row_count:
          type: integer
          description: 'Present with validation_errors: how many rows failed.'
      required:
        - statusCode
        - error
        - success
        - data
        - message
        - errors
  securitySchemes:
    bearer:
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.