Status Page
API Reference

How data merges on updates

When you update simple data types, such as numbers, strings, booleans, etc., Unit21 simply overwrites the old data.

With complex data types, such as arrays (e.g. location_data and tags) and the custom_data object, you have granular control of the updates, allowing you to:

  • Join old items with new items
  • Replace old items with new items
  • Remove items from the array

For these operations, many endpoints receive a top-level options object. Within this object, there are fields that let you configure exactly how array data is merged.

curl -X POST \
  https://<API_ENDPOINT>/v1/alerts/list \
  -H 'Content-Type: application/json' \
  -H 'u21-key: <YOUR_API_KEY>' \
  -d '{
        "options": {
          "include_associations": false,
          "include_actions": false,
          "include_checklist": false
        }
  }'

For almost all complex data models, you can configure merges with the field options.list_merge_strategy. The only exception is the custom_data object. For custom_data, use the field options.merge_custom_data.

Arrays merged using options.list_merge_strategy

If you are merging this field, Then configure your merge:
  • tags(across all objects)
  • parents(in general_data for entities)
  • document_data
  • location_data
  • digital_data
  • communication data (emails & phone arrays)
  • instrument IDs
  • alert fields (rules, entities, events, instruments)
  • case fields
    		• In the options object, use the field list_merge_strategy. This field has three different parameters that define how operation merges the data.
  • custom_data
    		•  In the options object, use the field merge_custom_data.

    🚧

    For items you cannot modify or delete, please send a request directly to the Unit21 team.

    List Merge Strategy

    The list_merge_strategy configuration in the options object provides three different methods to merge list values in an object update. By default, the union strategy is applied.

    list_merge_strategyDescription
    union(Default) Performs a set-union on the old and new lists, adding values that did not previously exist in the object. If the original list is ["abc", "def"], and the upsert/update request specifies ["def", "ghi"], then the resulting list is ["abc", "def", "ghi"].
    replaceReplaces the entire old list with the newly provided list. If original list is ["abc", "def"], and the upsert/update request specifies ["def", "ghi"], then the resulting list is ["def", "ghi"]. If you provide an empty list, the API deletes all previous list values from the object.
    differencePerforms a set-difference by subtracting values provided in the new list from the old list. If original list is ["abc", "def"], and the request specifies ["def", "ghi"], then the resulting list is ["abc"]. The API ignores values provided in the new list that did not exist in the old list.

    🚧

    One list merge strategy per API request.

    All lists in an update or upsert API request (single or bulk) will be merged according to the specified list_merge_strategy. It is not possible to have different lists be merged with different strategies in one API request.

    Custom Data Merge Strategy

    The default behavior for updating the custom_data field of an object is to perform a full object overwrite. This is equivalent to setting merge_custom_data in the options section as false.

    • When the merge_custom_data field is set to true, a deep recursive merge strategy is used to update custom_data.
    • Any conflicting keys take on the newly provided value. This will apply a recursive merge to both objects and lists within custom_data.
    • List member index positions are used as their keys i.e. merging ["a", "b", "c", "d"] with ["e", "f"] results in ["e", "f", "c", "d"].