curl --request POST \
  --url https://api.getnexor.ai/api/public/leads/{id}/status \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "status_key": "qualified",
  "reason": "Met budget threshold via CRM rule"
}
'

{
  "success": true,
  "changed": true,
  "previous_status": "engaged",
  "new_status": "qualified",
  "workflow_run": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "workflow_id": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Set Lead Status

Force a lead’s status within its active workflow run. This is a deliberate override: no downgrade guard and no field-collection gating are applied. If the lead has a single active workflow run, workflow_id may be omitted; pass it to disambiguate when the lead has multiple active runs. Moving the lead into a terminal status fires the usual side effects (cancels pending follow-up tasks and channel swaps, and triggers a workflow transfer when the status is configured for one). HubSpot sync is triggered when applicable.

POST

leads

{id}

status

curl --request POST \
  --url https://api.getnexor.ai/api/public/leads/{id}/status \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "status_key": "qualified",
  "reason": "Met budget threshold via CRM rule"
}
'

{
  "success": true,
  "changed": true,
  "previous_status": "engaged",
  "new_status": "qualified",
  "workflow_run": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "workflow_id": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Authorizations

X-API-Key

string

header

required

API key for authentication. Keys are prefixed with nxr_live_.

Path Parameters

string<uuid>

required

Lead ID

Body

application/json

status_key

string

required

Target workflow status key (e.g. 'qualified', 'lost'). Must exist in the lead's workflow. List valid keys via GET /workflows/{id}.

reason

string

Optional human-readable reason, stored on the run and in the status history.

workflow_id

string<uuid>

Optional. Required only when the lead has multiple active workflow runs.

Response

Status updated (or already in the target status)

success

boolean

changed

boolean

false when the lead was already in the target status (or a concurrent process moved it).

previous_status

string | null

new_status

string

workflow_run

object

Show child attributes

note

string

Present only on a concurrent no-op transition.

Last modified on June 18, 2026

Patch Lead

List Agents