Remove Workflow Lead

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

DELETE /workflows/{workflowId}/leads/{id}

Remove a workflow lead

cURL

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

200

{
  "message": "Lead removed from workflow."
}

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 Add Lead to Workflow.
• Compliance escalations: remove a lead from the workflow while you investigate a complaint, leaving the lead’s call history intact in Call Logs.

To remove every lead, pause or cancel the entire workflow instead. See Cancel Workflow or Pause Workflow.

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

Request

curl -X DELETE "https://api.dialnexa.com/v1/workflows/wfl_m3v7zb9rk2px/leads/wlead_p3q8zv5bk2mx" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{ "message": "success" }

Related endpoints

• Add Lead to Workflow: 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

Pass your API key as a Bearer token in the Authorization header.

Path Parameters

workflowId · string · required

id · string · required

Response

200

application/json

Success.

message · string

Example:

"Lead removed from workflow."