Bulk update status - Autotouch AI

This page documents the canonical HTTP contract for this endpoint.

This endpoint stages the update as an asynchronous job and returns queued_count, not completed update count. Selection is organization-scoped from authentication. Poll the job with GET /api/bulk-jobs/{job_id} using the same authenticated user and organization.

Body parameters

statusrequired
string
One of: new, qualified, contacting, converted, customer, unqualified, bad_data, nurture.
lead_ids · optional
array<string>
Explicit lead IDs. Provide either lead_ids or selection.
selection · optional
object
Either {mode:"ids",ids:[non-empty IDs]} or {mode:"descriptor",descriptor:{root:FilterNode}}; extra keys are rejected inside selection.
scope · optional
string
Optional org or user selection scope.
source_table_id · optional
string
Optional Research Table context for descriptor selection.
source_table_scope · optional
string
Optional company or lead Research Table scope.
unqualified_reason · optional
string
Optional reason used when status is unqualified.
unqualifiedReason · optional
string
Accepted alias for unqualified_reason.
lead_status_reason · optional
string
Optional reason used when status is unqualified.
leadStatusReason · optional
string
Accepted alias for lead_status_reason.
status_reason · optional
string
Accepted status reason alias.
statusReason · optional
string
Accepted status reason alias.
note · optional
string
Optional note attached to queued update.

Name	Type	Description
statusrequired	string	One of: new, qualified, contacting, converted, customer, unqualified, bad_data, nurture.
lead_ids	array<string>	Explicit lead IDs. Provide either lead_ids or selection.
selection	object	Either {mode:"ids",ids:[non-empty IDs]} or {mode:"descriptor",descriptor:{root:FilterNode}}; extra keys are rejected inside selection.
scope	string	Optional org or user selection scope.
source_table_id	string	Optional Research Table context for descriptor selection.
source_table_scope	string	Optional company or lead Research Table scope.
unqualified_reason	string	Optional reason used when status is unqualified.
unqualifiedReason	string	Accepted alias for unqualified_reason.
lead_status_reason	string	Optional reason used when status is unqualified.
leadStatusReason	string	Accepted alias for lead_status_reason.
status_reason	string	Accepted status reason alias.
statusReason	string	Accepted status reason alias.
note	string	Optional note attached to queued update.

Errors

Status	Meaning
400	Invalid status or selection.
401	Invalid API key or missing auth.
403	Missing leads:write scope.

Example

bash

curl -X POST "https://app.autotouch.ai/api/leads/bulk_update_status" \
    -H "Authorization: Bearer stk_your_key_id.your_secret" \
    -H "Content-Type: application/json" \
    -d '{"lead_ids":["67c4b113b4dd8f2d4999f0f1"],"status":"contacting"}'

Request body

json

{
    "lead_ids": ["67c4b113b4dd8f2d4999f0f1", "67c4b113b4dd8f2d4999f0f2"],
    "status": "contacting"
  }

Response example

json

{
    "success": true,
    "status": "queued",
    "job_id": "job_123",
    "task_id": "job_123",
    "matched_count": 2,
    "queued_count": 2,
    "message": "Queued status update for 2 leads"
  }