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:


"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). 

NOTE: The merge_strategy value must be 2, or not set (which defaults to 2). Learn more about merge strategies.

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:


{   "people": [     {       "fields": {         "str::first": "John",         "str::last": "Apple",         "str::email": "",         "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:


{   "people": [     {       "fields": {         "str::first": "John",         "str::last": "Apple",         "str::email": "",         "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": "",         "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 }