---
title: "Set an object"
method: PUT
path: "/v1/objects/{collection}/{id}"
tags: ["Objects"]
---

# Set an object

`PUT /v1/objects/{collection}/{id}`

Creates a new object or updates an existing one in the specified collection. This operation is used to identify objects with their properties, as well as optional preferences and channel data.

## Path parameters

- `collection` string, required
- `id` string, required

## Request body

- SetObjectRequest — A set of parameters to set an object with. Does not include the object id or collection.
  - `channel_data` InlineChannelDataRequest — A request to set channel data for a type of channel inline.
  - `locale` string, nullable — The locale of the object. Used for [message localization](/concepts/translations).
  - `preferences` InlinePreferenceSetRequest — Inline set preferences for a recipient, where the key is the preference set id. Preferences that are set inline will be merged into any existing preferences rather than replacing them.
  - `timezone` string, nullable — The timezone of the object. Must be a valid [tz database time zone string](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). Used for [recurring schedules](/concepts/schedules#scheduling-workflows-with-recurring-schedules-for-recipients).

## Response `200`

OK

- Object — A custom [Object](/concepts/objects) entity which belongs to a collection.
  - `__typename` string, required — The typename of the schema.
  - `collection` string, required — The collection this object belongs to.
  - `created_at` string, date-time, nullable — Timestamp when the resource was created.
  - `id` string, required — Unique identifier for the object.
  - `properties` object — The custom properties associated with the object.
  - `updated_at` string, date-time, required — The timestamp when the resource was last updated.

## Changes

- **2025-10-27** `40ca41599f57` — 1 breaking, 5 info
  - removed `#/components/schemas/PushChannelData, #/components/schemas/OneSignalChannelData, #/components/schemas/AwsSnsPushChannelData` from the `channel_data/additionalProperties/` request property `oneOf` list
  - added the new optional request property `preferences/additionalProperties/categories/anyOf[subschema #1: PreferenceSetRequestCategories]/additionalProperties/oneOf[subschema #2: PreferenceSetWorkflowCategorySettingObject]/channels`
  - added the new optional request property `preferences/additionalProperties/channels`
  - added the new optional request property `preferences/additionalProperties/commercial_subscribed`
  - …2 more
- **2025-09-08** `2d3aac5f3ddf` — 1 info
  - added `#/components/schemas/AwsSnsPushChannelData` to the `channel_data/additionalProperties/` request property `oneOf` list
- **2025-08-19** `e4ea1ded040e` — 1 info
  - added the new optional request property `preferences/additionalProperties/__persistence_strategy__`
- …earlier changes not shown

[Full history](https://skmtc.dev/knocklabs/apis/knock-api/changes/v1/objects/:collection/:id/put.md)

---

[API](https://skmtc.dev/knocklabs/apis/knock-api.md) · [All operations](https://skmtc.dev/knocklabs/apis/knock-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/knocklabs/knock-api/revisions/40ca41599f57/schema)