Bulk update a company field

Set or clear one writable catalog field across a Company selection. Standard-field and custom-field updates are queued and return an operation_run_id. Custom fields use the existing custom-field writer and require user_admin. Resolve writable fields and field_ref values from the CRM field catalog.

POST/api/companies/bulk_field_update

HTTP referenceScope companies:writeUpdated September 27, 2026

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, poll GET /api/operation-runs/{operation_run_id} to follow the queued mutation. The example shows the standard-field queued response; custom-field updates are also queued. Resolve field_ref values from the CRM field catalog.

Body parameters

selection · optional
object
Company selection; mutually exclusive with company_ids.
company_ids · optional
array<string>
Legacy explicit company IDs; mutually exclusive with selection.
field_refrequired
string
CRM catalog ID for a writable Company field.
operationrequired
string
set or clear.
value · optional
any
Required and non-null for set; omit or send null for clear.

Name	Type	Description
selection	object	Company selection; mutually exclusive with company_ids.
company_ids	array<string>	Legacy explicit company IDs; mutually exclusive with selection.
field_refrequired	string	CRM catalog ID for a writable Company field.
operationrequired	string	set or clear.
value	any	Required and non-null for set; omit or send null for clear.

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 company_ids are mutually exclusive.
404	No companies match the selection.
409	The catalog field has no supported bulk writer.

Example

bash

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

Request body

json

{
  "selection": {
    "mode": "ids",
    "ids": [
      "67c4a4f7b4dd8f2d4999f014"
    ]
  },
  "field_ref": "standard:company:name",
  "operation": "set",
  "value": "Example Company"
}

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:company:name",
  "operation": "set"
}