Bulk update a lead field

This page documents the canonical HTTP contract for this endpoint.

Developer API keys need the listed scope. A valid authenticated user session may also call this route.

For standard fields, the queued result is admission, not completion. Poll GET /api/operation-runs/{operation_run_id}. Custom-field updates use the existing user-admin custom-field writer and are also queued; poll the returned operation_run_id until terminal state. Choose an editable field and field_ref from the CRM field catalog.

Body parameters

selection · optional
object
Lead selection; mutually exclusive with lead_ids.
lead_ids · optional
array<string>
Legacy explicit lead IDs; mutually exclusive with selection.
field_refrequired
string
CRM catalog ID for a writable Lead field.
operationrequired
string
set or clear.
value · optional
any
Required and non-null for set; omit or send null for clear.
provenance · optional
object
Optional qualification provenance for eligible custom-field conclusions; not accepted for clear or standard fields.

Name	Type	Description
selection	object	Lead selection; mutually exclusive with lead_ids.
lead_ids	array<string>	Legacy explicit lead IDs; mutually exclusive with selection.
field_refrequired	string	CRM catalog ID for a writable Lead field.
operationrequired	string	set or clear.
value	any	Required and non-null for set; omit or send null for clear.
provenance	object	Optional qualification provenance for eligible custom-field conclusions; not accepted for clear or standard fields.

Errors

Status	Meaning
401	Authentication is missing or invalid.
403	The credential is invalid or lacks the required scope.
400	Selection or field lookup failed.
422	Operation must be set or clear; set requires a non-null, non-empty value; clear may omit value or send null; non-null values are rejected; selection and lead_ids are mutually exclusive.
404	No leads match the selection.
409	The catalog field has no supported bulk writer.

Example

bash

curl -X POST "https://app.autotouch.ai/api/leads/bulk_field_update" \
  -H "Authorization: Bearer $AUTOTOUCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"selection":{"mode":"ids","ids":["67c4a4f7b4dd8f2d4999f014"]},"field_ref":"standard:lead:title","operation":"set","value":"Director"}'

Request body

json

{
  "selection": {
    "mode": "ids",
    "ids": [
      "67c4a4f7b4dd8f2d4999f014"
    ]
  },
  "field_ref": "standard:lead:title",
  "operation": "set",
  "value": "Director"
}

Response example

json

{
  "success": true,
  "status": "queued",
  "job_id": "job-id",
  "task_id": "job-id",
  "operation_run_id": "operation-run-id",
  "matched_count": 1,
  "queued_count": 1,
  "field_ref": "standard:lead:title",
  "operation": "set"
}