Update a preference set

Changed on Aug 13, 2026

Sets preferences within the given preference set. By default, this is a destructive operation and will replace any existing preferences with the preferences given. Use '__persistence_strategy': 'merge' to merge with existing preferences instead. If no object exists in the current environment for the given :collection and :object_id, Knock will create the object as part of this request. The preference set :id can be either default or a tenant.id. Learn more about per-tenant preferences.

put/v1/objects/{collection}/{object_id}/preferences/{id}

Request

Base URL: https://api.knock.app
URL: https://api.knock.app/v1/objects/{collection}/{object_id}/preferences/{id}
Auth: HTTP bearer

Path parameters

object_idstring required

Unique identifier for the object.

collectionstring required

The collection this object belongs to.

idstring required

Example:default

Unique identifier for the preference set.

Request body

__persistence_strategy__'merge' | 'replace'

Controls how the preference set is persisted. 'replace' will completely replace the preference set, 'merge' will merge with existing preferences.

Example request

{
  "__persistence_strategy__": "merge",
  "categories": {
    "marketing": false,
    "transactional": {
      "channel_types": {
        "email": false
      }
    }
  },
  "channel_types": {
    "email": true
  },
  "channels": {
    "2f641633-95d3-4555-9222-9f1eb7888a80": {
      "conditions": [
        {
          "argument": "US",
          "operator": "equal_to",
          "variable": "recipient.country_code"
        }
      ]
    },
    "aef6e715-df82-4ab6-b61e-b743e249f7b6": true
  },
  "commercial_subscribed": true,
  "workflows": {
    "dinosaurs-loose": {
      "channel_types": {
        "email": false
      }
    }
  }
}

Response

idstring required

Unique identifier for the preference set.

Example response

{
  "categories": {
    "marketing": false,
    "transactional": {
      "channel_types": {
        "email": false
      }
    }
  },
  "channel_types": {
    "email": true,
    "push": false,
    "sms": {
      "conditions": [
        {
          "argument": "US",
          "operator": "equal_to",
          "variable": "recipient.country_code"
        }
      ]
    }
  },
  "commercial_subscribed": true,
  "id": "default",
  "workflows": null
}

Changes

Aug 13, 2026fcba175ebc76 Revision changes
- breaking
  the request property became not nullable
- breaking
  the request property type changed from boolean to no type
- breaking
  the response's property type changed from boolean to no type for status
- info
  added subschema #1 subschema #3 to the request property anyOf list
- info
  added subschema #1 subschema #3 to the response property anyOf list for the response status
Jul 14, 2026de4604427056 Revision changes
- warning
  added the new not_contains_all enum value to the ////////// response property for the response status
- warning
  added the new not_contains_all enum value to the ////////// response property for the response status
- warning
  added the new not_contains_all enum value to the ////////// response property for the response status
- warning
  added the new not_contains_all enum value to the ////////// response property for the response status
- warning
  added the new not_contains_all enum value to the ////////// response property for the response status
- warning
  added the new not_contains_all enum value to the ////////// response property for the response status
- warning
  added the new not_contains_all enum value to the ////////// response property for the response status
- warning
  added the new not_contains_all enum value to the ////// response property for the response status
- warning
  added the new not_contains_all enum value to the ////// response property for the response status
- warning
  added the new not_contains_all enum value to the ////// response property for the response status
- warning
  added the new not_contains_all enum value to the ////// response property for the response status
- warning
  added the new not_contains_all enum value to the ////// response property for the response status
- warning
  added the new not_contains_all enum value to the ////// response property for the response status
- warning
  added the new not_contains_all enum value to the ////// response property for the response status
- warning
  added the new not_contains_all enum value to the ////// response property for the response status
- warning
  added the new not_contains_all enum value to the ////////// response property for the response status
- warning
  added the new not_contains_all enum value to the ////////// response property for the response status
- warning
  added the new not_contains_all enum value to the ////////// response property for the response status
- warning
  added the new not_contains_all enum value to the ////////// response property for the response status
- warning
  added the new not_contains_all enum value to the ////////// response property for the response status
- warning
  added the new not_contains_all enum value to the ////////// response property for the response status
- warning
  added the new not_contains_all enum value to the ////////// response property for the response status
- warning
  added the new not_contains_all enum value to the ////// response property for the response status
- info
  added the new not_contains_all enum value to the request property //////////
- info
  added the new not_contains_all enum value to the request property //////////
- info
  added the new not_contains_all enum value to the request property //////////
- info
  added the new not_contains_all enum value to the request property //////////
- info
  added the new not_contains_all enum value to the request property //////////
- info
  added the new not_contains_all enum value to the request property //////////
- info
  added the new not_contains_all enum value to the request property //////////
- info
  added the new not_contains_all enum value to the request property //////
- info
  added the new not_contains_all enum value to the request property //////
- info
  added the new not_contains_all enum value to the request property //////
- info
  added the new not_contains_all enum value to the request property //////
- info
  added the new not_contains_all enum value to the request property //////
- info
  added the new not_contains_all enum value to the request property //////
- info
  added the new not_contains_all enum value to the request property //////
- info
  added the new not_contains_all enum value to the request property //////
- info
  added the new not_contains_all enum value to the request property //////////
- info
  added the new not_contains_all enum value to the request property //////////
- info
  added the new not_contains_all enum value to the request property //////////
- info
  added the new not_contains_all enum value to the request property //////////
- info
  added the new not_contains_all enum value to the request property //////////
- info
  added the new not_contains_all enum value to the request property //////////
- info
  added the new not_contains_all enum value to the request property //////////
- info
  added the new not_contains_all enum value to the request property //////

Operation history (6 revisions)