> ## Documentation Index
> Fetch the complete documentation index at: https://docs.macro.com/llms.txt
> Use this file to discover all available pages before exploring further.

# BulkSetEntityPropertyOptions

> Apply one multi-select option delta — most often a tag — to many entities in a single call. Use this instead of calling SetEntityProperty once per entity when the user asks to tag or label a set of items at once (e.g. "tag the last 50 emails as Follow-up"). Provide the property_definition_id (a tag set's propertyDefinitionId from ListTags) and the option ids to add and/or remove (a tag's option id from ListTags). The same add_option_ids/remove_option_ids delta is applied to every entity, composing atomically with concurrent edits per entity.  Only for multi-select or tag properties; for other value types, or a single entity, use SetEntityProperty. Up to 200 entities per call — split larger sets across multiple calls.  Best-effort: each entity is handled independently. Entities you don't have edit access to are reported with status 'skipped_no_permission' and left unchanged, entities that can't take the property are 'failed', and the rest are 'applied' — one call never fails wholesale because a few entities were not editable. Inspect the per-entity results and the summary to see what happened.

# BulkSetEntityPropertyOptions

Apply one multi-select option delta — most often a tag — to many entities in a single call. Use this instead of calling SetEntityProperty once per entity when the user asks to tag or label a set of items at once (e.g. "tag the last 50 emails as Follow-up"). Provide the property\_definition\_id (a tag set's propertyDefinitionId from ListTags) and the option ids to add and/or remove (a tag's option id from ListTags). The same add\_option\_ids/remove\_option\_ids delta is applied to every entity, composing atomically with concurrent edits per entity.

Only for multi-select or tag properties; for other value types, or a single entity, use SetEntityProperty. Up to 200 entities per call — split larger sets across multiple calls.

Best-effort: each entity is handled independently. Entities you don't have edit access to are reported with status 'skipped\_no\_permission' and left unchanged, entities that can't take the property are 'failed', and the rest are 'applied' — one call never fails wholesale because a few entities were not editable. Inspect the per-entity results and the summary to see what happened.

## Parameters

| Parameter                | Type                | Required | Description                                                                                                            |
| ------------------------ | ------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
| `entities`               | BulkTargetEntity\[] | Yes      | The entities to update (up to 200). Entities the user can't edit are skipped.                                          |
| `property_definition_id` | string              | Yes      | The multi-select property definition id changed on every entity — e.g. a tag set's propertyDefinitionId from ListTags. |
| `add_option_ids`         | string\[]           | No       | Options to add to every entity (e.g. a tag's option id from ListTags), deduped against each entity's current value.    |
| `remove_option_ids`      | string\[]           | No       | Options to remove from every entity. Removing an absent option is a no-op.                                             |