Workflow Leads
Delete Workflow Lead
Soft delete a lead from a workflow.
DELETE
Delete Workflow Lead
Destructive
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.
Recommended. This endpoint is part of the public
/v1 API reference and is the supported path for new integrations. See the migration guide for versioning guidance.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.
- Compliance escalations: remove a lead from the workflow while you investigate a complaint, leaving the lead’s call history intact in Call Logs.
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
Errors
404 Not Foundis returned when the workflow or lead does not exist, or the lead is not enrolled in the specified workflow.409 Conflictis returned when the lead is in a terminal state that does not need removal (already completed or already removed).
Related endpoints
- 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.
Delete Workflow Lead