📘

Migration Notes from 0.5 API

While the Buzz 0.5 and 2.0 APIs co-exist, your individual account must be set to work with one or the other APIs with regard to targeting. If you are not sure whether your account is ready to work with the new targeting-expressions resources please contact your account manager. Note, the bulk edit functionality is only available for the 2.0 API.

## Bulk Edit Concepts

You can edit targeting expressions in bulk using the [/line-items/bulk-targeting](🔗) resource. There are three actions supported and multiple actions and values can be included in one request.

A bulk edit request consists of an `ids` field containing a list of line item IDs and a `commands` field containing a list of command objects. A command object consists of a required `key` for targeting key, a required `action` field, and action-specific fields `to_group`, `from_groups`, `add`, `remove` described below. In addition to the validation described below, a command object should either have `from_groups` or have `to_group set` each containing the key group, predicate group, and pairs to instruct the application where to remove predicates from and where to add predicates to. See the [targeting doc](🔗) for detailed explanation on predicate groups.

## Example Requests

Below are some truncated snippet examples of a bulk edit request:

If no values are passed in the remove field on a command with action `remove`, all targeted values within the key group-predicate group pairs passed in the `from_groups` of the targeting key will be removed. A combination of `remove` and `add` actions can be used to conduct a "Replace all values with" / "Set targeting key to" functionality. If action is set to `replace`, both `add` and `remove` fields are required. In a `replace` command, predicates in `add` will be added to a targeting expression if and only if the targeting expression had any matching predicates in the `remove` field.

See examples below:

## Range Targeting and Time Targeting Key

For non-time targeting keys that use the `in_range` (currently, only `ip_address`), the only available options will be `remove` without values specified (equivalent to "clear all values". Optionally an add action can be conducted following the remove action (equivalent to "Replace all values with").

This applies to the time targeting keys `time_of_week` and `user_time_of_week` as well. In addition, any `remove` action will translate to two remove commands, one for `user_time_of_week` and one for `time_of_week`, followed by an optional add command.

## Segment Recency

When using the bulk edit feature on segment targeting, options for setting segment recency differ between the edit actions.

For any `remove` or `replace` action, a recency value is neither required nor accepted in the `remove` field. The `remove` in the operation will simply look up the segment irrespective of any recency value it may have applied.

For any actions where a segment is added to targeting through an `add` or `replace`, a `recency` value may be defined in the `add` field.

The [Targeting](🔗) guide have a detailed explanation on how segment recency works. Here's a bulk edit example:

## Processing Rules

The entire bulk edit operation is conducted within a single transaction. Prior to applying the bulk edit commands, the API will iterate over all of the Line Items for the IDs provided and check for existing targeting expressions. If any line items are missing targeting expressions, new, empty targeting expressions will be created and assigned to the line items. All of this will be done within the transaction and will be rolled back if validation errors are detected after applying the bulk edit commands.

## Success Response

The successful response body will be a list of objects each with `id`, `targeting_expression_id`, and `created` field indicating whether or not a new targeting expression was created for the line item. Example:

## Error Response

There are 2 classes of possible validation errors:

1. Badly formatted input

2. The bulk operations left targeting expression(s) in an invalid state.

For badly formatted input, the error response will mirror the request. For example: if more than the maximum number of ids allowed are provided:

When the bulk operations left targeting expressions in an invalid state, the error response body will mirror the success response body. It will be a list of dicts containing `line_item_id`, `targeting_expression_id` and any surfaced errors. The errors object will be the same field-level validation errors object that is returned from unsuccessful requests to the targeting-expressions endpoint. For example, if a bulk edit left modules empty for one of the targeting expressions: