Assign Workflow to Lead

POST /leads/{id}/assign-workflow

Assign a lead to a workflow. If the lead has no active workflow, this enrolls them (movementType: "enrollment"). If the lead already has an active workflow, the existing run is deactivated and replaced (movementType: "reassignment").

The lead will automatically start the new workflow's cadence sequence unless the workflow is paused.

Path Parameters

Parameter	Type	Required	Description
id	string (uuid)	Yes	Lead ID

Request Body

Field	Type	Required	Description
workflowId	string (uuid)	Yes	ID of the workflow to assign. Use GET /workflows to list available workflows
reason	string	No	Reason for the assignment. Stored on the deactivated workflow run when reassigning
actorId	string	No	ID of the user or system performing the assignment. Used for audit trail

Examples

Enroll lead into workflow

curl -X POST https://api.getnexor.ai/api/public/leads/123e4567-e89b-12d3-a456-426614174000/assign-workflow \
  -H "Content-Type: application/json" \
  -H "X-API-Key: nxr_live_your_api_key" \
  -d '{
    "workflowId": "123e4567-e89b-12d3-a456-426614174000"
  }'

Reassign to different workflow with reason

curl -X POST https://api.getnexor.ai/api/public/leads/123e4567-e89b-12d3-a456-426614174000/assign-workflow \
  -H "Content-Type: application/json" \
  -H "X-API-Key: nxr_live_your_api_key" \
  -d '{
    "workflowId": "987fcdeb-51a2-43e7-b678-426614174999",
    "reason": "Lead qualified for premium workflow",
    "actorId": "user-abc-123"
  }'

Responses

201 — Workflow assigned successfully

New enrollment (lead had no workflow):

{
  "workflowRunId": "550e8400-e29b-41d4-a716-446655440000",
  "workflowId": "123e4567-e89b-12d3-a456-426614174000",
  "workflowName": "Premium Outreach",
  "movementType": "enrollment",
  "paused": false
}

Reassignment (lead moved from another workflow):

{
  "workflowRunId": "550e8400-e29b-41d4-a716-446655440001",
  "workflowId": "987fcdeb-51a2-43e7-b678-426614174999",
  "workflowName": "VIP Follow-up",
  "movementType": "reassignment",
  "paused": false
}

Response Fields

Field	Type	Description
workflowRunId	string (uuid)	ID of the newly created workflow run
workflowId	string (uuid)	ID of the assigned workflow
workflowName	string	Name of the assigned workflow
movementType	"enrollment" | "reassignment"	Whether this was a new enrollment or a reassignment
paused	boolean	Whether the workflow is currently paused. If true, the cadence won't start until unpaused

400 — Validation error

{
  "error": "workflowId is required"
}

401 — Authentication error

See Authentication.

500 — Internal server error