Skip to main content
Talk to salesStart

Update lead custom fields in bulk

Set custom field values for an explicit or descriptor-based lead selection.

POST/api/leads/bulk_custom_fields
HTTP referenceScope leads:write (organization admin)Updated September 27, 2026

This page documents the canonical HTTP contract for this endpoint.

Requires user-admin permission in addition to the API key's leads:write scope. Selection belongs to the authenticated organization. Values must be non-empty; provenance uses the schema documented on Update lead custom fields. This mutation queues a background job and returns job/task/operation identifiers; poll GET /api/operation-runs/{operation_run_id} with jobs:read to check completion.

Body parameters

  • valuesrequired

    object

    Non-empty map of defined custom field keys to JSON values; empty strings clear fields.

  • lead_ids · optional

    array<string>

    Explicit Lead IDs; use this or selection.

  • selection · optional

    object

    BulkSelectionModel: {mode: "ids", ids: [...]} or {mode: "descriptor", descriptor: {root: <FilterNode>}}. Descriptor root is a rule or group with kind, field/operator/value or logic/children.

  • scope · optional

    string

    Lead scope.

  • source_table_id · optional

    string

    Research table context.

  • source_table_scope · optional

    string

    Research table scope.

  • provenance · optional

    object

    Optional keyed assertions; same basis/rationale/sources schema as Update lead custom fields. Defaults to {}.

Errors

StatusMeaning
400Invalid selection, values, or provenance.
401Invalid API key or missing auth.
403Organization administrator and leads:write access required.

Docs