Clearing and setting a person's field values

When updating people via the v1/person/merge endpoint, you can clear existing field values and set new values in the same API call.

This works for all field types, including single- and multi-select field types.

Field value clearing is achieved using the clear_fields: {} object. 

This is necessary when you want to overwrite multi-select field values (using “merge_strategy”: 2). Without clear_fields, existing multi-select field values will not be overwritten, they will receive additional values. For example, if a person already has a multi-select field value of “A”, and in the call you provide the value “B”, this person will now have both values “A” and “B” set.

When using clear_fields, you provide the relevant field names in the object with a value of true to indicate that you want them to be overwritten. Here is an example showing different field types:

json
 
"clear_fields": {
                "bol:cm:custom-boolean": true,
                "dtz::b": true,
                "int:cm:custom-currency": true,
                "phn::phone": true,
                "sst:cm:custom-multiselect": true,
                "str::first": true,
                "tme:cm:custom-time-and-date": true,
                "txt:cm:custom-text": true,
                "obj:cm:customobject": true
            }

To set a new value, you provide it in the fields object (as you normally would when updating a person’s data). 

Here’s a payload example for updating one person’s field values. In this example there is a multi-select field called sst:cm:favorite-brands:

json
 
{
  "people": [
    {
      "fields": {
        "str::first": "John",
        "str::last": "Apple",
        "str::email": "japple@email.com",
        "str:cm:job-title": "Sales consultant",
        "sst:cm:favourite-brands": [
            "Reebok", "Converse"
        ],
        "bol:cm:has-membership": true
    },
    "clear_fields": {
        "sst:cm:favorite-brands": true,
        "str:cm:job-title": true,
        "bol:cm:has-membership": true
        }
    }
  ],
  "merge_by": ["str::email"],
  "merge_strategy": 2
}

You can also do this for multiple people in the same payload. Here is an example for two people:

json
 
{
  "people": [
    {
      "fields": {
        "str::first": "John",
        "str::last": "Apple",
        "str::email": "japple@email.com",
        "str:cm:job-title": "Sales consultant",
        "sst:cm:favorite-brands": [
            "Reebok", "Converse"
        ],
        "bol:cm:has-membership": true
    },
    "clear_fields": {
        "sst:cm:favorite-brands": true,
        "str:cm:job-title": true,
        "bol:cm:has-membership": true
        }
    },
{
      "fields": {
        "str::first": "Laura",
        "str::last": "Smith",
        "str::email": "lsmith@email.com",
        "str:cm:job-title": "Dog walker",
        "sst:cm:favorite-brands": [
            "Nike", "Adidas"
        ],
        "bol:cm:has-membership": true
    },
    "clear_fields": {
        "sst:cm:favorite-brands": true,
        "str:cm:job-title": true,
        "bol:cm:has-membership": true
        }
    }
  ],
  "merge_by": ["str::email"],
  "merge_strategy": 2
}