Set one custom field to the same value on many contacts, as the Contacts page's Set field does: the contacts you list (contact_ids or emails, up to 1,000, each a contact of this workspace) or every member of a segment (segment_id, however many; also needs segments:read). Send exactly one. key names a field that exists (Create a custom contact field); value is typed against it the way an import types it, and null clears it. With only_empty: true a contact that has its own value keeps it (a contact that only shows the field's default_value has none, so it is filled). Each contact whose value changes gets a contact.updated webhook (changed_fields) and an activity row naming your key; one that already has the value is left as it is. Subscriptions, topics and SMS consent are never touched. It always runs as a background job (202, Location); follow it with Retrieve a job. Listed contacts are checked first: the first that isn't one of yours is a 404 naming it (details), and nothing starts. One bulk operation runs per field at a time, and five bulk contact edits per workspace (409 job_in_progress). Starting one counts against a limit of 30 bulk contact edits a minute per workspace by default (a 429 started nothing; retry after Retry-After). Pass an Idempotency-Key so a retry answers the same job instead of starting another. To give different contacts different values, update each with Update a contact or import them with Start an async contact import. Requires the contacts:write capability.
Parameters1 field
Field
Type
Description
Idempotency-Key
string · header
Any unique string (1–256 characters, e.g. a UUID). Retrying with the same key and the same body within 24 hours returns the first result instead of sending again; the same key with a different body is `409 invalid_idempotent_request`, and one still in flight is `409 concurrent_idempotent_requests`.
Request body6 fields
Field
Type
Description
keyrequired
string
The custom field's key (`plan`). It must exist: create it with POST /contact-fields first.
valuerequired
string | number | boolean | null
The value, typed against the field the way an import types it: a number field takes `42` or `"42"`, a boolean `true` / `"yes"`, a date an ISO 8601 date. `null` clears the field.
only_empty
boolean
Default false: overwrite every value. True: set it only where the contact has no value of its own (the key is missing or null; a contact that shows the field's default has none). Not with `value: null`.
contact_ids
string[]
Contacts of this workspace (`con_…`), up to 1,000.
emails
string[]
Contacts of this workspace by email address, up to 1,000.
segment_id
string
Every member of this segment (`seg_…`), however many. Also needs `segments:read`.