Skip to main content
DELETE
Delete Workflow Lead
Destructive
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.
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.
  • Compliance escalations: remove a lead from the workflow while you investigate a complaint, leaving the lead’s call history intact in Call Logs.
To stop workflow execution for every lead, use Update Workflow 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

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

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"

id
string
required

Lead ID

Example:

"lead_abc123"

Response

Lead soft-deleted successfully.