---
title: "Add subscriptions"
method: POST
path: "/v1/objects/{collection}/{object_id}/subscriptions"
tags: ["Subscriptions", "Objects"]
---

# Add subscriptions

`POST /v1/objects/{collection}/{object_id}/subscriptions`

Add subscriptions for an object. If a subscription already exists, it will be updated. This endpoint also handles [inline identifications](/managing-recipients/identifying-recipients#inline-identifying-recipients) for the `recipient`.

## Path parameters

- `object_id` string, required
- `collection` string, required

## Request body

- UpsertSubscriptionsRequest — A request to upsert subscriptions for a set of recipients.
  - `properties` object, nullable — The custom properties associated with the subscription relationship.
  - `recipients` RecipientRequest[], required — The recipients of the subscription. You can subscribe up to 100 recipients to an object at a time.
    - union — Specifies a recipient in a request. This can either be a user identifier (string), an inline user request (object), or an inline object request, which is determined by the presence of a `collection` property.
      - string — The ID of the user which is used as the reference for the recipient.
      - object — A set of parameters to inline-identify a user with. Inline identifying the user will ensure that the user is available before the request is executed in Knock. It will perform an upsert for the user you're supplying, replacing any properties specified.
        - `avatar` string, nullable — A URL for the avatar of the user.
        - `channel_data` InlineChannelDataRequest — A request to set channel data for a type of channel inline.
        - `created_at` string, date-time, nullable — The creation date of the user from your system.
        - `email` string, nullable — The primary email address for the user.
        - `id` string, required — The unique identifier of the user.
        - `locale` string, nullable — The locale of the user. Used for [message localization](/concepts/translations).
        - `name` string, nullable — Display name of the user.
        - `phone_number` string, nullable — The [E.164](https://www.twilio.com/docs/glossary/what-e164) phone number of the user (required for SMS channels).
        - `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 user. 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).
      - object — A custom [Object](/concepts/objects) entity which belongs to a collection.
        - `channel_data` union — An optional set of [channel data](/managing-recipients/setting-channel-data) for the object. This is a list of `ChannelData` objects.
          - object — A request to set channel data for a type of channel inline.
          - unknown
        - `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.
        - `name` string, nullable — An optional name for the object.
        - `preferences` union — An optional set of [preferences](/concepts/preferences) for the object.
          - object — 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.
          - unknown

## Response `200`

OK

- Subscription[] — A response containing a list of subscriptions.
  - `__typename` string, required — The typename of the schema.
  - `inserted_at` string, date-time, required — Timestamp when the resource was created.
  - `object` Object, required — 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.
  - `properties` object, nullable — The custom properties associated with the subscription relationship.
  - `recipient` union, required — A recipient of a notification, which is either a user or an object.
    - object — A [User](/concepts/users) represents an individual in your system who can receive notifications through Knock. Users are the most common recipients of notifications and are always referenced by your internal identifier.
      - `__typename` string, required — The typename of the schema.
      - `avatar` string, nullable — A URL for the avatar of the user.
      - `created_at` string, date-time, nullable — The creation date of the user from your system.
      - `email` string, nullable — The primary email address for the user.
      - `id` string, required — The unique identifier of the user.
      - `name` string, nullable — Display name of the user.
      - `phone_number` string, nullable — The [E.164](https://www.twilio.com/docs/glossary/what-e164) phone number of the user (required for SMS channels).
      - `timezone` string, nullable — The timezone of the user. 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).
      - `updated_at` string, date-time, required — The timestamp when the resource was last updated.
    - 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.
  - `updated_at` string, date-time, required — The timestamp when the resource was last updated.

---

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