Delete Workflow Lead

DELETE

workflows

{workflowId}

leads

{id}

Delete Workflow Lead

curl --request DELETE \
  --url https://api.dialnexa.com/v1/workflows/{workflowId}/leads/{id} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.dialnexa.com/v1/workflows/{workflowId}/leads/{id}"

headers = {"Authorization": "Bearer <token>"}

response = requests.delete(url, headers=headers)

print(response.text)

const options = {method: 'DELETE', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.dialnexa.com/v1/workflows/{workflowId}/leads/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.dialnexa.com/v1/workflows/{workflowId}/leads/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.dialnexa.com/v1/workflows/{workflowId}/leads/{id}"

	req, _ := http.NewRequest("DELETE", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.dialnexa.com/v1/workflows/{workflowId}/leads/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "success": true,
  "error": false,
  "statusCode": 200,
  "message": "Success",
  "data": {
    "statusCode": 200,
    "message": "Lead soft-deleted successfully"
  },
  "timestamp": "2026-09-07T06:00:00.000Z"
}

{
  "statusCode": 401,
  "error": true,
  "success": false,
  "data": [],
  "message": "Invalid API key",
  "errors": []
}

{
  "statusCode": 404,
  "error": true,
  "success": false,
  "data": [],
  "message": "Workflow lead with ID Bv7nC2xKs5DqYw not found",
  "errors": []
}

{
  "statusCode": 500,
  "error": true,
  "success": false,
  "data": [],
  "message": "Internal server error",
  "errors": []
}

Destructive Marks a single lead as removed from the workflow. The lead disappears from List Workflow Leads 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).

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 DND list; 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 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. 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.

To stop new leads from starting in the workflow, use Update Workflow Status 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 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.

Upload Workflow Leads: enroll a new lead.
List Workflow Leads: view current enrollments and their status.
Lead History: review the steps a lead has already moved through.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

workflowId

string

required

Workflow ID

Example:

"workflow_abc123"

string

required

Lead ID

Example:

"lead_abc123"

Response

Lead removed successfully.

success

enum<boolean>

required

Available options:

true

error

enum<boolean>

required

Available options:

false

statusCode

integer

required

Example:

200

message

string

required

Example:

"Success"

data

object

required

Show child attributes

timestamp

string<date-time>

required

Delete Workflow Lead

curl --request DELETE \
  --url https://api.dialnexa.com/v1/workflows/{workflowId}/leads/{id} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.dialnexa.com/v1/workflows/{workflowId}/leads/{id}"

headers = {"Authorization": "Bearer <token>"}

response = requests.delete(url, headers=headers)

print(response.text)

const options = {method: 'DELETE', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.dialnexa.com/v1/workflows/{workflowId}/leads/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.dialnexa.com/v1/workflows/{workflowId}/leads/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.dialnexa.com/v1/workflows/{workflowId}/leads/{id}"

	req, _ := http.NewRequest("DELETE", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.dialnexa.com/v1/workflows/{workflowId}/leads/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "success": true,
  "error": false,
  "statusCode": 200,
  "message": "Success",
  "data": {
    "statusCode": 200,
    "message": "Lead soft-deleted successfully"
  },
  "timestamp": "2026-09-07T06:00:00.000Z"
}

{
  "statusCode": 401,
  "error": true,
  "success": false,
  "data": [],
  "message": "Invalid API key",
  "errors": []
}

{
  "statusCode": 404,
  "error": true,
  "success": false,
  "data": [],
  "message": "Workflow lead with ID Bv7nC2xKs5DqYw not found",
  "errors": []
}

{
  "statusCode": 500,
  "error": true,
  "success": false,
  "data": [],
  "message": "Internal server error",
  "errors": []
}

Overview

Endpoints

When to use this

Behavior

Path parameters

Errors

Authorizations

Path Parameters

Response

​When to use this

​Behavior

​Path parameters

​Errors

​Related endpoints

Authorizations

Path Parameters

Response

When to use this

Behavior

Path parameters

Errors

Related endpoints