Set a field on many contacts

Set a field on many contacts

POST/api/v1/contacts/set-field

POST /contacts/set-field
curl -X POST 'https://www.unitpost.com/api/v1/contacts/set-field' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 202
{
  "object": "job",
  "id": "id_123",
  "kind": "string",
  "status": "QUEUED",
  "total": 1,
  "processed": 0,
  "failed": 0,
  "error": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "completed_at": "2026-01-01T00:00:00.000Z"
}

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
FieldTypeDescription
Idempotency-Keystring · headerAny 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
FieldTypeDescription
keyrequiredstringThe custom field's key (`plan`). It must exist: create it with POST /contact-fields first.
valuerequiredstring | number | boolean | nullThe 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_emptybooleanDefault 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_idsstring[]Contacts of this workspace (`con_…`), up to 1,000.
emailsstring[]Contacts of this workspace by email address, up to 1,000.
segment_idstringEvery member of this segment (`seg_…`), however many. Also needs `segments:read`.
Response · 202 fields10 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
kindrequiredstring—
statusrequiredenumQUEUED | RUNNING | COMPLETED | FAILED | CANCELED—
totalrequiredinteger | null—
processedrequiredinteger—
failedrequiredinteger—
errorrequiredstring | null—
created_atrequiredstring—
completed_atrequiredstring | null—
202400401403404409422429502

Search docs and guides

Search the docs and product guides.