API reference

Workflows

A Workflow orchestrates the delivery of messages to your end users. When you configure a workflow you'll determine which channels its messages should route to, what those messages should look like on each channel, as well as any functions—batch, throttle, delay—you want applied to the messages prior to delivery.

To send notifications, you’ll trigger your workflows. A workflow is triggered by a trigger call, typically when an event occurs in your product that you want your users to know about (e.g. a new comment.)

Endpoints

POST/v1/workflows/{key}/trigger

POST/v1/workflows/{key}/cancel

Idempotent

Trigger workflow

Trigger a workflow (specified by the key) to run for the given recipients, using the parameters provided. Returns an identifier for the workflow run request. All workflow runs are executed asynchronously. This endpoint also handles inline identifications for the actor, recipient, and tenant fields.

Endpoint

POST/v1/workflows/{key}/trigger

Rate limit

Tier 5

Path parameters

keystringrequired

Key of the workflow to trigger.

Request body

actorunknown

A map of properties describing a user or an object to identify in Knock and mark as who or what performed the action.

cancellation_keystringnullable

An optional key that is used to reference a specific workflow trigger request when issuing a [workflow cancellation](/send-notifications/canceling-workflows) request. Must be provided while triggering a workflow in order to enable subsequent cancellation. Should be unique across trigger requests to avoid unintentional cancellations.

dataobjectnullable

An optional map of data to pass into the workflow execution. There is a 10MB limit on the size of the full `data` payload. Any individual string value greater than 1024 bytes in length will be [truncated](/developer-tools/api-logs#log-truncation) in your logs.

recipientsRecipientRequest[]required

The recipients to trigger the workflow for. Can inline identify users, objects, or use a list of user IDs. Limited to 1,000 recipients.

tenantunknown

The tenant to trigger the workflow for. Triggering with a tenant will use any tenant-level overrides associated with the tenant object, and all messages produced from workflow runs will be tagged with the tenant.

Returns

TriggerWorkflowResponse

The response from triggering a workflow.

Cancel workflow

When invoked for a workflow using a specific workflow key and cancellation key, will cancel any queued workflow runs associated with that key/cancellation key pair. Can optionally be provided one or more recipients to scope the request to.

Endpoint

POST/v1/workflows/{key}/cancel

Rate limit

Tier 5

Path parameters

keystringrequired

The key of the workflow to cancel.

Request body

cancellation_keystringrequired

An optional key that is used to reference a specific workflow trigger request when issuing a [workflow cancellation](/send-notifications/canceling-workflows) request. Must be provided while triggering a workflow in order to enable subsequent cancellation. Should be unique across trigger requests to avoid unintentional cancellations.

recipientsRecipientReference[]nullable

A list of recipients to cancel the notification for. If omitted, cancels for all recipients associated with the cancellation key.

Returns

204 No Content

Messages

A Message is a notification delivered on a particular channel to a user.

Endpoints

GET/v1/messages/{message_id}

GET/v1/messages/{message_id}/content

GET/v1/messages

GET/v1/messages/{message_id}/events

GET/v1/messages/{message_id}/delivery_logs

GET/v1/messages/{message_id}/activities

PUT/v1/messages/{message_id}/seen

DELETE/v1/messages/{message_id}/seen

PUT/v1/messages/{message_id}/read

DELETE/v1/messages/{message_id}/read

PUT/v1/messages/{message_id}/interacted

PUT/v1/messages/{message_id}/archived

DELETE/v1/messages/{message_id}/archived

Retention policy applied

Get message

Retrieves a specific message by its ID.

Endpoint

GET/v1/messages/{message_id}

Rate limit

Tier 4

Path parameters

message_idstringrequired

The unique identifier for the message.

Returns

Message

Represents a single message that was generated by a workflow for a given channel.

Retention policy applied

Get message content

Returns the fully rendered contents of a message, where the response depends on which channel the message was sent through.

Endpoint

GET/v1/messages/{message_id}/content

Rate limit

Tier 4

Path parameters

message_idstringrequired

The ID of the message to fetch contents of.

Returns

MessageContents

The content of a message.

Retention policy applied

List messages

Returns a paginated list of messages for the current environment.

Endpoint

GET/v1/messages

Rate limit

Tier 4

Query parameters

afterstring

The cursor to fetch entries after.

beforestring

The cursor to fetch entries before.

page_sizeinteger

The number of items per page (defaults to 50).

tenantstring

Limits the results to items with the corresponding tenant.

channel_idstring

Limits the results to items with the corresponding channel ID.

status[]string[]

Limits the results to messages with the given delivery status.

engagement_status[]string[]

Limits the results to messages with the given engagement status.

message_ids[]string[]

Limits the results to only the message IDs given (max 50). Note: when using this option, the results will be subject to any other filters applied to the query.

workflow_categories[]string[]

Limits the results to messages related to any of the provided categories.

sourcestring

Limits the results to messages triggered by the given workflow key.

workflow_run_idstring

Limits the results to messages associated with the top-level workflow run ID returned by the workflow trigger request.

workflow_recipient_run_idstring

Limits the results to messages for a specific recipient's workflow run.

trigger_datastring

Limits the results to only messages that were generated with the given data. See [trigger data filtering](/api-reference/overview/trigger-data-filtering) for more information.

inserted_at.gtestring

Limits the results to messages inserted after or on the given date.

inserted_at.ltestring

Limits the results to messages inserted before or on the given date.

inserted_at.gtstring

Limits the results to messages inserted after the given date.

inserted_at.ltstring

Limits the results to messages inserted before the given date.

Returns

ListMessagesResponse

A paginated list of messages.

Retention policy applied

List events

Returns a paginated list of events for the specified message.

Endpoint

GET/v1/messages/{message_id}/events

Rate limit

Tier 3

Path parameters

message_idstringrequired

The ID of the message to fetch events for.

Query parameters

afterstring

The cursor to fetch entries after.

beforestring

The cursor to fetch entries before.

page_sizeinteger

The number of items per page (defaults to 50).

Returns

ListMessageEventsResponse

Returns a paginated list of [delivery and engagement](/send-notifications/message-statuses) events for the specified message.

Retention policy applied

List delivery logs

Returns a paginated list of delivery logs for the specified message.

Endpoint

GET/v1/messages/{message_id}/delivery_logs

Rate limit

Tier 3

Path parameters

message_idstringrequired

The ID of the message to fetch delivery logs for.

Query parameters

afterstring

The cursor to fetch entries after.

beforestring

The cursor to fetch entries before.

page_sizeinteger

The number of items per page (defaults to 50).

Returns

ListMessageDeliveryLogsResponse

A message delivery log response.

Retention policy applied

List activities

Returns a paginated list of activities for the specified message.

Endpoint

GET/v1/messages/{message_id}/activities

Rate limit

Tier 4

Path parameters

message_idstringrequired

The ID of the message to fetch activities for.

Query parameters

trigger_datastring

The trigger data to filter activities by.

afterstring

The cursor to fetch entries after.

beforestring

The cursor to fetch entries before.

page_sizeinteger

The number of items per page (defaults to 50).

Returns

ListActivitiesResponse

Returns a paginated list of `activities` associated with a given message. For messages produced after a [batch step](/designing-workflows/batch-function), this will contain one or more activities. Non-batched messages will always return a single activity.

Retention policy applied

Mark message as seen

Marks a message as seen. This indicates that the user has viewed the message in their feed or inbox. Read more about message engagement statuses here.

Endpoint

PUT/v1/messages/{message_id}/seen

Rate limit

Tier 2

Path parameters

message_idstringrequired

The unique identifier for the message.

Returns

Message

Represents a single message that was generated by a workflow for a given channel.

Retention policy applied

Mark message as unseen

Marks a message as unseen. This reverses the seen state. Read more about message engagement statuses here.

Endpoint

DELETE/v1/messages/{message_id}/seen

Rate limit

Tier 2

Path parameters

message_idstringrequired

The unique identifier for the message.

Returns

Message

Represents a single message that was generated by a workflow for a given channel.

Retention policy applied

Mark message as read

Marks a message as read. This indicates that the user has read the message content. Read more about message engagement statuses here.

Endpoint

PUT/v1/messages/{message_id}/read

Rate limit

Tier 2

Path parameters

message_idstringrequired

The unique identifier for the message.

Returns

Message

Represents a single message that was generated by a workflow for a given channel.

Retention policy applied

Mark message as unread

Marks a message as unread. This reverses the read state. Read more about message engagement statuses here.

Endpoint

DELETE/v1/messages/{message_id}/read

Rate limit

Tier 2

Path parameters

message_idstringrequired

The unique identifier for the message.

Returns

Message

Represents a single message that was generated by a workflow for a given channel.

Retention policy applied

Mark message as interacted

Marks a message as interacted with by the user. This can include any user action on the message, with optional metadata about the specific interaction. Cannot include more than 5 key-value pairs, must not contain nested data. Read more about message engagement statuses here.

Endpoint

PUT/v1/messages/{message_id}/interacted

Rate limit

Tier 2

Path parameters

message_idstringrequired

The unique identifier for the message.

Request body

metadataobject

Metadata about the interaction.

Returns

Message

Represents a single message that was generated by a workflow for a given channel.

Retention policy applied

Archive message

Archives a message for the user. Archived messages are hidden from the default message list in the feed but can still be accessed and unarchived later.

Endpoint

PUT/v1/messages/{message_id}/archived

Rate limit

Tier 2

Path parameters

message_idstringrequired

The unique identifier for the message.

Returns

Message

Represents a single message that was generated by a workflow for a given channel.

Retention policy applied

Unarchive message

Removes a message from the archived state, making it visible in the default message list in the feed again.

Endpoint

DELETE/v1/messages/{message_id}/archived

Rate limit

Tier 2

Path parameters

message_idstringrequired

The unique identifier for the message.

Returns

Message

Represents a single message that was generated by a workflow for a given channel.

Batch operations

Operations that can be performed on a batch of messages.

Endpoints

GET/v1/messages/batch/content

POST/v1/messages/batch/seen

POST/v1/messages/batch/unseen

POST/v1/messages/batch/read

POST/v1/messages/batch/unread

POST/v1/messages/batch/interacted

POST/v1/messages/batch/archived

POST/v1/messages/batch/unarchived

Retention policy applied

Batch get message contents

Get the contents of multiple messages in a single request.

Endpoint

GET/v1/messages/batch/content

Rate limit

Tier 4

Query parameters

message_ids[]string[]required

The IDs of the messages to fetch contents of.

Returns

BatchGetMessageContentsResponse

A list of `MessageContents`

Retention policy applied

Mark messages as seen

Marks the given messages as seen. This indicates that the user has viewed the message in their feed or inbox. Read more about message engagement statuses here.

Endpoint

POST/v1/messages/batch/seen

Rate limit

Tier 3

Request body

message_idsstring[]required

The message IDs to update the status of.

Returns

BatchListMessagesResponse

The list of messages that were updated.

Retention policy applied

Mark messages as unseen

Marks the given messages as unseen. This reverses the seen state. Read more about message engagement statuses here.

Endpoint

POST/v1/messages/batch/unseen

Rate limit

Tier 3

Request body

message_idsstring[]required

The message IDs to update the status of.

Returns

BatchListMessagesResponse

The list of messages that were updated.

Retention policy applied

Mark messages as read

Marks the given messages as read. Read more about message engagement statuses here.

Endpoint

POST/v1/messages/batch/read

Rate limit

Tier 3

Request body

message_idsstring[]required

The message IDs to update the status of.

Returns

BatchListMessagesResponse

The list of messages that were updated.

Retention policy applied

Mark messages as unread

Marks the given messages as unread. This reverses the read state. Read more about message engagement statuses here.

Endpoint

POST/v1/messages/batch/unread

Rate limit

Tier 3

Request body

message_idsstring[]required

The message IDs to update the status of.

Returns

BatchListMessagesResponse

The list of messages that were updated.

Retention policy applied

Mark messages as interacted

Marks the given messages as interacted with by the user. This can include any user action on the message, with optional metadata about the specific interaction. Cannot include more than 5 key-value pairs, must not contain nested data. Read more about message engagement statuses here.

Endpoint

POST/v1/messages/batch/interacted

Rate limit

Tier 3

Request body

message_idsstring[]required

The message IDs to batch mark as interacted with.

metadataobjectnullable

Metadata about the interaction.

Returns

BatchListMessagesResponse

The list of messages that were updated.

Retention policy applied

Mark messages as archived

Marks the given messages as archived. Archived messages are hidden from the default message list in the feed but can still be accessed and unarchived later.

Endpoint

POST/v1/messages/batch/archived

Rate limit

Tier 3

Request body

message_idsstring[]required

The message IDs to update the status of.

Returns

BatchListMessagesResponse

The list of messages that were updated.

Retention policy applied

Mark messages as unarchived

Marks the given messages as unarchived. This reverses the archived state. Archived messages are hidden from the default message list in the feed but can still be accessed and unarchived later.

Endpoint

POST/v1/messages/batch/unarchived

Rate limit

Tier 3

Request body

message_idsstring[]required

The message IDs to update the status of.

Returns

BatchListMessagesResponse

The list of messages that were updated.

Message

Represents a single message that was generated by a workflow for a given channel.

Attributes

__typenamestringrequired

The typename of the schema.

actorsRecipientReference[]

One or more actors that are associated with this message. Note: this is a list that can contain up to 10 actors if the message is produced from a [batch](/designing-workflows/batch-function).

archived_atstringnullable

Timestamp when the message was archived.

channelobject

A configured channel, which is a way to route messages to a provider.

channel_idstringrequired

Deprecated, use channel.id instead.

clicked_atstringnullable

Timestamp when the message was clicked.

dataobjectnullable

Data associated with the message’s workflow run. Includes the workflow trigger request’s `data` payload merged with any additional data returned by a [fetch function](/designing-workflows/fetch-function). For messages produced after a [batch step](/designing-workflows/batch-function), includes the payload `data` from the most-recent trigger request (the final `activity` in the batch).

engagement_statusesstring[]required

A list of engagement statuses.

idstringrequired

The unique identifier for the message.

inserted_atstringrequired

Timestamp when the resource was created.

interacted_atstringnullable

Timestamp when the message was interacted with.

link_clicked_atstringnullable

Timestamp when a link in the message was clicked.

metadataobjectnullable

The metadata associated with the message.

read_atstringnullable

Timestamp when the message was read.

recipientRecipientReferencerequired

A reference to a recipient, either a user identifier (string) or an object reference (ID, collection).

scheduled_atstringnullable

Timestamp when the message was scheduled to be sent.

seen_atstringnullable

Timestamp when the message was seen.

sourceobjectrequired

The workflow or guide that triggered the message.

statusstringrequired

The message delivery status.

One of: "queued", "sent", "delivered", "delivery_attempted", "undelivered", "not_sent", "bounced"

tenantstringnullable

The ID of the `tenant` associated with the message. Only present when a `tenant` is provided on a workflow trigger request.

updated_atstringrequired

The timestamp when the resource was last updated.

workflowstringnullable

The key of the workflow that generated the message.

Activity

An activity associated with a workflow trigger request. Messages produced after a batch step can be associated with one or more activities. Non-batched messages will always be associated with a single activity.

Attributes

__typenamestring

The typename of the schema.

actorobject

The actor who performed the activity.

dataobjectnullable

The workflow trigger `data` payload associated with the activity.

idstring

Unique identifier for the activity.

inserted_atstring

Timestamp when the activity was created.

recipientRecipient

A recipient of a notification, which is either a user or an object.

updated_atstring

Timestamp when the activity was last updated.

MessageDeliveryLog

A message delivery log contains a request from Knock to a downstream provider and the response that was returned.

Attributes

__typenamestringrequired

The typename of the schema.

environment_idstringrequired

The ID of the environment in which the message delivery occurred.

idstringrequired

The unique identifier for the message delivery log.

inserted_atstringrequired

Timestamp when the message delivery log was created.

requestMessageDeliveryLogRequestrequired

A message delivery log request.

responseMessageDeliveryLogResponserequired

A message delivery log response.

service_namestringrequired

The name of the service that processed the delivery.

MessageEvent

A message event. Occurs when a message delivery or engagement status changes.

Attributes

__typenamestringrequired

The typename of the schema.

dataobjectnullable

The data associated with the message event. Only present for some event types.

idstringrequired

The unique identifier for the message event.

inserted_atstringrequired

Timestamp when the event was created.

recipientRecipientReferencerequired

A reference to a recipient, either a user identifier (string) or an object reference (ID, collection).

typestringrequired

The type of event that occurred.

One of: "message.archived", "message.bounced", "message.delivered", "message.delivery_attempted", "message.interacted", "message.link_clicked", "message.not_sent", "message.queued", "message.read", "message.seen", "message.sent", "message.unarchived", "message.undelivered", "message.unread", "message.unseen"

Channels

A Channel is a delivery method for a message.

Bulk

Bulk operations available for messages of a given channel.

Endpoints

POST/v1/channels/{channel_id}/messages/bulk/{action}

Retention policy applied

Bulk update message statuses for channel

Bulk update the status of messages for a specific channel. The channel is specified by the channel_id parameter. The action to perform is specified by the action parameter, where the action is a status change action (e.g. archive, unarchive).

Endpoint

POST/v1/channels/{channel_id}/messages/bulk/{action}

Rate limit

Tier 2

Path parameters

channel_idstringrequired

The ID of the channel to update messages for.

actionstringrequired

The target status to be applied to the messages.

One of: "seen", "unseen", "read", "unread", "archived", "unarchived", "interacted", "archive", "unarchive", "delete"

Request body

archivedstring

Limits the results to messages with the given archived status.

One of: "exclude", "include", "only"

delivery_statusstring

Limits the results to messages with the given delivery status.

One of: "queued", "sent", "delivered", "delivery_attempted", "undelivered", "not_sent", "bounced"

engagement_statusstring

Limits the results to messages with the given engagement status.

One of: "seen", "unseen", "read", "unread", "archived", "unarchived", "link_clicked", "interacted"

has_tenantboolean

Limits the results to messages that have a tenant or not.

newer_thanstring

Limits the results to messages inserted after the given date.

older_thanstring

Limits the results to messages inserted before the given date.

recipient_idsstring[]

Limits the results to messages with the given recipient IDs.

tenantsstring[]

Limits the results to messages with the given tenant IDs.

trigger_datastring

Limits the results to only messages that were generated with the given data. See [trigger data filtering](/api-reference/overview/trigger-data-filtering) for more information.

workflowsstring[]

Limits the results to messages with the given workflow keys.

Returns

BulkOperation

A bulk operation entity.

Users

A User 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.

Endpoints

GET/v1/users/{user_id}

GET/v1/users

PUT/v1/users/{user_id}

POST/v1/users/{user_id}/merge

DELETE/v1/users/{user_id}

GET/v1/users/{user_id}/messages

GET/v1/users/{user_id}/schedules

GET/v1/users/{user_id}/subscriptions

GET/v1/users/{user_id}/preferences

GET/v1/users/{user_id}/preferences/{id}

PUT/v1/users/{user_id}/preferences/{id}

GET/v1/users/{user_id}/channel_data/{channel_id}

PUT/v1/users/{user_id}/channel_data/{channel_id}

DELETE/v1/users/{user_id}/channel_data/{channel_id}

Get user

Retrieve a specific user by their ID.

Endpoint

GET/v1/users/{user_id}

Rate limit

Tier 4

Path parameters

user_idstringrequired

The ID of the user to retrieve.

Returns

User

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.

List users

Retrieve a paginated list of users in the environment. Defaults to 50 users per page.

Endpoint

GET/v1/users

Rate limit

Tier 4

Query parameters

include[]string[]

Associated resources to include in the response.

afterstring

The cursor to fetch entries after.

beforestring

The cursor to fetch entries before.

page_sizeinteger

The number of items per page (defaults to 50).

Returns

ListUsersResponse

A paginated list of users.

Identify user

Create or update a user with the provided identification data. When you identify an existing user, the system merges the properties you specific with what is currently set on the user, updating only the fields included in your requests.

Endpoint

PUT/v1/users/{user_id}

Rate limit

Tier 3

Path parameters

user_idstringrequired

The unique identifier of the user.

Request body

avatarstringnullable

A URL for the avatar of the user.

channel_dataunknownnullable

Channel-specific information that's needed to deliver a notification to an end provider.

created_atstringnullable

The creation date of the user from your system.

emailstringnullable

The primary email address for the user.

localestringnullable

The locale of the user. Used for [message localization](/concepts/translations).

namestringnullable

Display name of the user.

phone_numberstringnullable

The [E.164](https://www.twilio.com/docs/glossary/what-e164) phone number of the user (required for SMS channels).

preferencesunknownnullable

A set of preferences for the user.

timezonestringnullable

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

Returns

User

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.

Merge users

Merge two users together, where the user specified with the from_user_id param will be merged into the user specified by user_id.

Endpoint

POST/v1/users/{user_id}/merge

Rate limit

Tier 2

Path parameters

user_idstringrequired

The id of the user to merge into.

Request body

from_user_idstringrequired

The user ID to merge from.

Returns

User

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.

Delete user

Permanently delete a user and all associated data.

Endpoint

DELETE/v1/users/{user_id}

Rate limit

Tier 2

Path parameters

user_idstringrequired

The ID of the user to delete.

Returns

204 No Content

Retention policy applied

List user messages

Returns a paginated list of messages for a specific user. Messages are sorted with the most recent ones appearing first. Messages outside the account's retention window will not be included in the results.

Endpoint

GET/v1/users/{user_id}/messages

Rate limit

Tier 4

Path parameters

user_idstringrequired

The user ID to list messages for.

Query parameters

afterstring

The cursor to fetch entries after.

beforestring

The cursor to fetch entries before.

page_sizeinteger

The number of items per page (defaults to 50).

tenantstring

Limits the results to items with the corresponding tenant.

channel_idstring

Limits the results to items with the corresponding channel ID.

status[]string[]

Limits the results to messages with the given delivery status.

engagement_status[]string[]

Limits the results to messages with the given engagement status.

message_ids[]string[]

Limits the results to only the message IDs given (max 50). Note: when using this option, the results will be subject to any other filters applied to the query.

workflow_categories[]string[]

Limits the results to messages related to any of the provided categories.

sourcestring

Limits the results to messages triggered by the given workflow key.

workflow_run_idstring

Limits the results to messages associated with the top-level workflow run ID returned by the workflow trigger request.

workflow_recipient_run_idstring

Limits the results to messages for a specific recipient's workflow run.

trigger_datastring

Limits the results to only messages that were generated with the given data. See [trigger data filtering](/api-reference/overview/trigger-data-filtering) for more information.

inserted_at.gtestring

Limits the results to messages inserted after or on the given date.

inserted_at.ltestring

Limits the results to messages inserted before or on the given date.

inserted_at.gtstring

Limits the results to messages inserted after the given date.

inserted_at.ltstring

Limits the results to messages inserted before the given date.

Returns

ListMessagesResponse

A paginated list of messages.

List user schedules

Returns a paginated list of schedules for a specific user, in descending order.

Endpoint

GET/v1/users/{user_id}/schedules

Rate limit

Tier 4

Path parameters

user_idstringrequired

The user ID to list schedules for.

Query parameters

workflowstring

The workflow key to filter schedules for.

tenantstring

The tenant ID to filter schedules for.

afterstring

The cursor to fetch entries after.

beforestring

The cursor to fetch entries before.

page_sizeinteger

The number of items per page (defaults to 50).

Returns

ListSchedulesResponse

A response containing a list of schedules.

List user subscriptions

Retrieves a paginated list of subscriptions for a specific user, in descending order.

Endpoint

GET/v1/users/{user_id}/subscriptions

Rate limit

Tier 4

Path parameters

user_idstringrequired

The user ID to list subscriptions for.

Query parameters

include[]string[]

Associated resources to include in the response.

objects[]RecipientReference[]

Only returns subscriptions for the specified object references.

afterstring

The cursor to fetch entries after.

beforestring

The cursor to fetch entries before.

page_sizeinteger

The number of items per page (defaults to 50).

Returns

ListSubscriptionsResponse

A response containing a list of subscriptions.

List user preference sets

Retrieves a list of all preference sets for a specific user.

Endpoint

GET/v1/users/{user_id}/preferences

Rate limit

Tier 4

Path parameters

user_idstringrequired

The unique identifier of the user.

Returns

ListUserPreferenceSetsResponse

A list of preference sets for the user.

Get user preference set

Retrieves a specific preference set for a user identified by the preference set ID.

Endpoint

GET/v1/users/{user_id}/preferences/{id}

Rate limit

Tier 4

Path parameters

user_idstringrequired

The unique identifier of the user.

idstringrequired

Unique identifier for the preference set.

Default: "default"

Query parameters

tenantstring

The unique identifier for the tenant.

Returns

PreferenceSet

A preference set represents a specific set of notification preferences for a recipient. A recipient can have multiple preference sets.

Update user preference set

Updates a complete preference set for a user. 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.

Endpoint

PUT/v1/users/{user_id}/preferences/{id}

Rate limit

Tier 3

Path parameters

user_idstringrequired

The unique identifier of the user.

idstringrequired

Unique identifier for the preference set.

Default: "default"

Request body

__persistence_strategy__string

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

One of: "merge", "replace"

categoriesunknown

An object where the key is the category and the values are the preference settings for that category.

channel_typesunknown

An object where the key is the channel type and the values are the preference settings for that channel type.

channelsunknown

An object where the key is the channel ID and the values are the preference settings for that channel ID.

commercial_subscribedbooleannullable

Whether the recipient is subscribed to commercial communications. When false, the recipient will not receive commercial workflow notifications.

workflowsunknown

An object where the key is the workflow key and the values are the preference settings for that workflow.

Returns

PreferenceSet

A preference set represents a specific set of notification preferences for a recipient. A recipient can have multiple preference sets.

Get channel data

Retrieves the channel data for a specific user and channel ID.

Endpoint

GET/v1/users/{user_id}/channel_data/{channel_id}

Rate limit

Tier 4

Path parameters

user_idstringrequired

The unique identifier of the user.

channel_idstringrequired

The unique identifier for the channel.

Returns

ChannelData

Channel data for a given channel type.

Set channel data

Updates or creates channel data for a specific user and channel ID. If no user exists in the current environment for the given user_id, Knock will create the user entry as part of this request.

Endpoint

PUT/v1/users/{user_id}/channel_data/{channel_id}

Rate limit

Tier 3

Path parameters

user_idstringrequired

The unique identifier of the user.

channel_idstringrequired

The unique identifier for the channel.

Request body

dataobjectrequired

Channel data for a given channel type.

Returns

ChannelData

Channel data for a given channel type.

Unset channel data

Deletes channel data for a specific user and channel ID.

Endpoint

DELETE/v1/users/{user_id}/channel_data/{channel_id}

Rate limit

Tier 3

Path parameters

user_idstringrequired

The unique identifier of the user.

channel_idstringrequired

The unique identifier for the channel.

Returns

204 No Content

Feeds

A feed exposes the messages delivered to an in-app feed channel, formatted specially to be consumed in a notification feed.

A feed will always return a list of FeedItems, which are pointers to a message delivered and contain all of the information needed in order to render an item within a notification feed.

Note: Feeds are a specialized form of messages that are designed purely for in-app rendering, and as such return information that is required on the client to do so.

Endpoints

GET/v1/users/{user_id}/feeds/{id}

GET/v1/users/{user_id}/feeds/{id}/settings

List feed items

Returns a paginated list of feed items for a user in reverse chronological order, including metadata about the feed. If the user has not yet been identified within Knock, an empty feed will be returned.

You can customize the response using response filters to exclude or only include specific properties on your resources.

Notes:

When making this call from a client-side environment, use your publishable key along with a user token.
This endpoint’s rate limit is always scoped per-user and per-environment. This is true even for requests made without a signed user token.
Any attachments present in trigger data are automatically excluded from both the data and activities fields of UserInAppFeedResponse.

Endpoint

GET/v1/users/{user_id}/feeds/{id}

Rate limit

Tier 2

Path parameters

user_idstringrequired

The unique identifier of the user.

idstringrequired

The unique identifier for the channel.

Query parameters

statusstring

The status of the feed items.

One of: "unread", "read", "unseen", "seen", "all"

sourcestring

The workflow key associated with the message in the feed.

tenantstring

The tenant associated with the feed items.

has_tenantboolean

Whether the feed items have a tenant.

workflow_categories[]string[]

The workflow categories of the feed items.

archivedstring

The archived status of the feed items.

One of: "exclude", "include", "only"

trigger_datastring

The trigger data of the feed items (as a JSON string).

localestring

The locale to render the feed items in. Must be in the IETF 5646 format (e.g. `en-US`). When not provided, will default to the locale that the feed items were rendered in. Only available for enterprise plan customers using custom translations.

afterstring

The cursor to fetch entries after.

beforestring

The cursor to fetch entries before.

page_sizeinteger

The number of items per page (defaults to 50).

Returns

UserInAppFeedResponse

A paginated list of feed items.

Get feed settings

Returns the feed settings for a user.

Endpoint

GET/v1/users/{user_id}/feeds/{id}/settings

Rate limit

Tier 4

Path parameters

user_idstringrequired

The unique identifier of the user.

idstringrequired

The unique identifier for the channel.

Returns

UserInAppFeedSettingsResponse

The response for the user's feed settings.

Guides

A Guide is a collection of steps that can be used to guide a user through a workflow.

Endpoints

GET/v1/users/{user_id}/guides/{channel_id}

PUT/v1/users/{user_id}/guides/messages/{message_id}/seen

PUT/v1/users/{user_id}/guides/messages/{message_id}/interacted

PUT/v1/users/{user_id}/guides/messages/{message_id}/archived

List guides

Returns a list of eligible in-app guides for a specific user and channel.

Endpoint

GET/v1/users/{user_id}/guides/{channel_id}

Rate limit

Tier 2

Path parameters

user_idstringrequired

The unique identifier of the user.

channel_idstringrequired

The unique identifier for the channel.

Query parameters

tenantstring

The tenant ID to use for targeting and rendering guides.

datastring

The data (JSON encoded object) to use for targeting and rendering guides.

typestring

The type of guides to filter by.

Returns

GuidesResponse

A response for a list of guides.

Mark guide as seen

Records that a guide has been seen by a user, triggering any associated seen events.

Endpoint

PUT/v1/users/{user_id}/guides/messages/{message_id}/seen

Rate limit

Tier 2

Path parameters

user_idstringrequired

The unique identifier of the user.

Request body

channel_idstringrequired

The unique identifier for the channel.

contentobject

The content of the guide.

dataobject

The data of the guide.

guide_idstringrequired

The unique identifier for the guide.

guide_keystringrequired

The key of the guide.

guide_step_refstringrequired

The step reference of the guide.

is_finalboolean

Whether the guide is final.

metadataobject

The metadata of the guide.

tenantstringnullable

The tenant ID of the guide.

Returns

GuideActionResponse

A response for a guide action.

Mark guide as interacted

Records that a user has interacted with a guide, triggering any associated interacted events.

Endpoint

PUT/v1/users/{user_id}/guides/messages/{message_id}/interacted

Rate limit

Tier 2

Path parameters

user_idstringrequired

The unique identifier of the user.

Request body

channel_idstringrequired

The unique identifier for the channel.

contentobject

The content of the guide.

dataobject

The data of the guide.

guide_idstringrequired

The unique identifier for the guide.

guide_keystringrequired

The key of the guide.

guide_step_refstringrequired

The step reference of the guide.

is_finalboolean

Whether the guide is final.

metadataobject

The metadata of the guide.

tenantstringnullable

The tenant ID of the guide.

Returns

GuideActionResponse

A response for a guide action.

Mark guide as archived

Records that a guide has been archived by a user, triggering any associated archived events.

Endpoint

PUT/v1/users/{user_id}/guides/messages/{message_id}/archived

Rate limit

Tier 2

Path parameters

user_idstringrequired

The unique identifier of the user.

Request body

channel_idstringrequired

The unique identifier for the channel.

contentobject

The content of the guide.

dataobject

The data of the guide.

guide_idstringrequired

The unique identifier for the guide.

guide_keystringrequired

The key of the guide.

guide_step_refstringrequired

The step reference of the guide.

is_finalboolean

Whether the guide is final.

metadataobject

The metadata of the guide.

tenantstringnullable

The tenant ID of the guide.

Returns

GuideActionResponse

A response for a guide action.

Bulk operations

Bulk operations available for users. These endpoints return a BulkOperation that executes the job asynchronously. Progress can be tracked via the Bulk operations API.

Endpoints

POST/v1/users/bulk/identify

POST/v1/users/bulk/preferences

POST/v1/users/bulk/delete

Bulk identify users

Identifies multiple users in a single operation. Allows creating or updating up to 1,000 users in a single batch with various properties, preferences, and channel data.

Endpoint

POST/v1/users/bulk/identify

Rate limit

Tier 1

Request body

usersInlineIdentifyUserRequest[]required

A list of users.

Returns

BulkOperation

A bulk operation entity.

Bulk set preferences

Bulk sets the preferences for up to 1,000 users at a time. The preference set :id can be either default or a tenant.id. Learn more about per-tenant preferences. Note that this is a destructive operation and will replace any existing users' preferences with the preferences sent.

Endpoint

POST/v1/users/bulk/preferences

Rate limit

Tier 1

Request body

preferencesPreferenceSetRequestrequired

A request to set a preference set for a recipient.

user_idsstring[]required

A list of user IDs.

Returns

BulkOperation

A bulk operation entity.

Bulk delete users

Permanently deletes up to 1,000 users at a time.

Endpoint

POST/v1/users/bulk/delete

Rate limit

Tier 1

Request body

user_idsstring[]required

A list of user IDs.

Returns

BulkOperation

A bulk operation entity.

User

A User 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.

Attributes

__typenamestringrequired

The typename of the schema.

avatarstringnullable

A URL for the avatar of the user.

created_atstringnullable

The creation date of the user from your system.

emailstringnullable

The primary email address for the user.

idstringrequired

The unique identifier of the user.

namestringnullable

Display name of the user.

phone_numberstringnullable

The [E.164](https://www.twilio.com/docs/glossary/what-e164) phone number of the user (required for SMS channels).

timezonestringnullable

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_atstringrequired

The timestamp when the resource was last updated.

IdentifyUserRequest

A set of parameters to identify a user with. Does not include the user ID, as that's specified elsewhere in the request. You can supply any additional properties you'd like to upsert for the user.

Attributes

avatarstringnullable

A URL for the avatar of the user.

channel_dataunknownnullable

Channel-specific information that's needed to deliver a notification to an end provider.

created_atstringnullable

The creation date of the user from your system.

emailstringnullable

The primary email address for the user.

localestringnullable

The locale of the user. Used for [message localization](/concepts/translations).

namestringnullable

Display name of the user.

phone_numberstringnullable

The [E.164](https://www.twilio.com/docs/glossary/what-e164) phone number of the user (required for SMS channels).

preferencesunknownnullable

A set of preferences for the user.

timezonestringnullable

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

InlineIdentifyUserRequest

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.

Attributes

avatarstringnullable

A URL for the avatar of the user.

channel_dataunknownnullable

Channel-specific information that's needed to deliver a notification to an end provider.

created_atstringnullable

The creation date of the user from your system.

emailstringnullable

The primary email address for the user.

idstringrequired

The unique identifier of the user.

localestringnullable

The locale of the user. Used for [message localization](/concepts/translations).

namestringnullable

Display name of the user.

phone_numberstringnullable

The [E.164](https://www.twilio.com/docs/glossary/what-e164) phone number of the user (required for SMS channels).

preferencesunknownnullable

A set of preferences for the user.

timezonestringnullable

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

Objects

An Object represents a resource in your system that you've stored in Knock. It can be used to send out-of-app notifications to non-user recipients (such as a public channel in a chat app), or to trigger notifications to subscribers of a non-user resource such as a shared document.

Endpoints

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

GET/v1/objects/{collection}/{id}

GET/v1/objects/{collection}

DELETE/v1/objects/{collection}/{id}

GET/v1/objects/{collection}/{object_id}/preferences

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

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

GET/v1/objects/{collection}/{id}/schedules

GET/v1/objects/{collection}/{id}/messages

GET/v1/objects/{collection}/{object_id}/channel_data/{channel_id}

PUT/v1/objects/{collection}/{object_id}/channel_data/{channel_id}

DELETE/v1/objects/{collection}/{object_id}/channel_data/{channel_id}

GET/v1/objects/{collection}/{object_id}/subscriptions

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

DELETE/v1/objects/{collection}/{object_id}/subscriptions

Set an object

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.

Endpoint

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

Rate limit

Tier 3

Path parameters

collectionstringrequired

The collection this object belongs to.

idstringrequired

Unique identifier for the object.

Request body

channel_dataInlineChannelDataRequest

A request to set channel data for a type of channel inline.

localestringnullable

The locale of the object. Used for [message localization](/concepts/translations).

namestringnullable

An optional name for the object.

preferencesInlinePreferenceSetRequest

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.

timezonestringnullable

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

Returns

Object

A custom [Object](/concepts/objects) entity which belongs to a collection.

Get an object

Retrieves a specific object by its ID from the specified collection. Returns the object with all its properties.

Endpoint

GET/v1/objects/{collection}/{id}

Rate limit

Tier 4

Path parameters

collectionstringrequired

The collection this object belongs to.

idstringrequired

Unique identifier for the object.

Returns

Object

A custom [Object](/concepts/objects) entity which belongs to a collection.

List objects in a collection

Returns a paginated list of objects from the specified collection. Optionally includes preference data for the objects.

Endpoint

GET/v1/objects/{collection}

Rate limit

Tier 4

Path parameters

collectionstringrequired

The collection this object belongs to.

Query parameters

afterstring

The cursor to fetch entries after.

beforestring

The cursor to fetch entries before.

page_sizeinteger

The number of items per page (defaults to 50).

include[]string[]

Includes preferences of the objects in the response.

Returns

ListObjectsResponse

A paginated list of objects in a collection.

Delete an object

Permanently removes an object from the specified collection. This operation cannot be undone.

Endpoint

DELETE/v1/objects/{collection}/{id}

Rate limit

Tier 3

Path parameters

collectionstringrequired

The collection this object belongs to.

idstringrequired

Unique identifier for the object.

Returns

204 No Content

List preference sets

Returns a paginated list of preference sets for the specified object.

Endpoint

GET/v1/objects/{collection}/{object_id}/preferences

Rate limit

Tier 4

Path parameters

object_idstringrequired

Unique identifier for the object.

collectionstringrequired

The collection this object belongs to.

Returns

ListObjectPreferenceSetsResponse

A list of preference sets for the object

Get object preference set

Returns the preference set for the specified object and preference set id.

Endpoint

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

Rate limit

Tier 4

Path parameters

object_idstringrequired

Unique identifier for the object.

collectionstringrequired

The collection this object belongs to.

idstringrequired

Unique identifier for the preference set.

Default: "default"

Returns

PreferenceSet

A preference set represents a specific set of notification preferences for a recipient. A recipient can have multiple preference sets.

Update a preference set

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.

Endpoint

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

Rate limit

Tier 3

Path parameters

object_idstringrequired

Unique identifier for the object.

collectionstringrequired

The collection this object belongs to.

idstringrequired

Unique identifier for the preference set.

Default: "default"

Request body

__persistence_strategy__string

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

One of: "merge", "replace"

categoriesunknown

An object where the key is the category and the values are the preference settings for that category.

channel_typesunknown

An object where the key is the channel type and the values are the preference settings for that channel type.

channelsunknown

An object where the key is the channel ID and the values are the preference settings for that channel ID.

commercial_subscribedbooleannullable

Whether the recipient is subscribed to commercial communications. When false, the recipient will not receive commercial workflow notifications.

workflowsunknown

An object where the key is the workflow key and the values are the preference settings for that workflow.

Returns

PreferenceSet

A preference set represents a specific set of notification preferences for a recipient. A recipient can have multiple preference sets.

List object schedules

Returns a paginated list of schedules for an object.

Endpoint

GET/v1/objects/{collection}/{id}/schedules

Rate limit

Tier 4

Path parameters

idstringrequired

The ID of the object to list schedules for.

collectionstringrequired

The collection of the object to list schedules for.

Query parameters

tenantstring

Filter schedules by tenant id.

workflowstring

Filter schedules by workflow id.

afterstring

The cursor to fetch entries after.

beforestring

The cursor to fetch entries before.

page_sizeinteger

The number of items per page (defaults to 50).

Returns

ListSchedulesResponse

A response containing a list of schedules.

Retention policy applied

List messages

Returns a paginated list of messages for a specific object in the given collection. Allows filtering by message status and provides various sorting options.

Endpoint

GET/v1/objects/{collection}/{id}/messages

Rate limit

Tier 4

Path parameters

collectionstringrequired

The collection this object belongs to.

idstringrequired

Unique identifier for the object.

Query parameters

afterstring

The cursor to fetch entries after.

beforestring

The cursor to fetch entries before.

page_sizeinteger

The number of items per page (defaults to 50).

tenantstring

Limits the results to items with the corresponding tenant.

channel_idstring

Limits the results to items with the corresponding channel ID.

status[]string[]

Limits the results to messages with the given delivery status.

engagement_status[]string[]

Limits the results to messages with the given engagement status.

message_ids[]string[]

Limits the results to only the message IDs given (max 50). Note: when using this option, the results will be subject to any other filters applied to the query.

workflow_categories[]string[]

Limits the results to messages related to any of the provided categories.

sourcestring

Limits the results to messages triggered by the given workflow key.

workflow_run_idstring

Limits the results to messages associated with the top-level workflow run ID returned by the workflow trigger request.

workflow_recipient_run_idstring

Limits the results to messages for a specific recipient's workflow run.

trigger_datastring

Limits the results to only messages that were generated with the given data. See [trigger data filtering](/api-reference/overview/trigger-data-filtering) for more information.

inserted_at.gtestring

Limits the results to messages inserted after or on the given date.

inserted_at.ltestring

Limits the results to messages inserted before or on the given date.

inserted_at.gtstring

Limits the results to messages inserted after the given date.

inserted_at.ltstring

Limits the results to messages inserted before the given date.

Returns

ListMessagesResponse

A paginated list of messages.

Get channel data

Returns the channel data for the specified object and channel.

Endpoint

GET/v1/objects/{collection}/{object_id}/channel_data/{channel_id}

Rate limit

Tier 4

Path parameters

object_idstringrequired

Unique identifier for the object.

collectionstringrequired

The collection this object belongs to.

channel_idstringrequired

The unique identifier for the channel.

Returns

ChannelData

Channel data for a given channel type.

Set channel data

Sets the channel data for the specified object and channel. 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.

Endpoint

PUT/v1/objects/{collection}/{object_id}/channel_data/{channel_id}

Rate limit

Tier 3

Path parameters

object_idstringrequired

Unique identifier for the object.

collectionstringrequired

The collection this object belongs to.

channel_idstringrequired

The unique identifier for the channel.

Request body

dataobjectrequired

Channel data for a given channel type.

Returns

ChannelData

Channel data for a given channel type.

Unset channel data

Unsets the channel data for the specified object and channel.

Endpoint

DELETE/v1/objects/{collection}/{object_id}/channel_data/{channel_id}

Rate limit

Tier 3

Path parameters

object_idstringrequired

Unique identifier for the object.

collectionstringrequired

The collection this object belongs to.

channel_idstringrequired

The unique identifier for the channel.

Returns

204 No Content

List subscriptions

List subscriptions for an object. Either list the recipients that subscribe to the provided object, or list the objects that the provided object is subscribed to. Determined by the mode query parameter.

Endpoint

GET/v1/objects/{collection}/{object_id}/subscriptions

Rate limit

Tier 4

Path parameters

object_idstringrequired

Unique identifier for the object.

collectionstringrequired

The collection this object belongs to.

Query parameters

modestring

Mode of the request. `recipient` to list the objects that the provided object is subscribed to, `object` to list the recipients that subscribe to the provided object.

One of: "recipient", "object"

Default: "object"

include[]string[]

Additional fields to include in the response.

recipients[]RecipientReference[]

Recipients to filter by (only used if mode is `object`).

objects[]ObjectReference[]

Objects to filter by (only used if mode is `recipient`).

afterstring

The cursor to fetch entries after.

beforestring

The cursor to fetch entries before.

page_sizeinteger

The number of items per page (defaults to 50).

Returns

ListSubscriptionsResponse

A response containing a list of subscriptions.

Add subscriptions

Add subscriptions for an object. If a subscription already exists, it will be updated. This endpoint also handles inline identifications for the recipient.

Endpoint

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

Rate limit

Tier 3

Path parameters

object_idstringrequired

Unique identifier for the object.

collectionstringrequired

The collection this object belongs to.

Request body

propertiesobjectnullable

The custom properties associated with the subscription relationship.

recipientsRecipientRequest[]required

The recipients of the subscription. You can subscribe up to 100 recipients to an object at a time.

Returns

SubscriptionsResponse

A response containing a list of subscriptions.

Delete subscriptions

Delete subscriptions for the specified recipients from an object. Returns the list of deleted subscriptions.

Endpoint

DELETE/v1/objects/{collection}/{object_id}/subscriptions

Rate limit

Tier 3

Path parameters

object_idstringrequired

Unique identifier for the object.

collectionstringrequired

The collection this object belongs to.

Request body

recipientsRecipientReference[]required

The recipients of the subscription. You can subscribe up to 100 recipients to an object at a time.

Returns

SubscriptionsResponse

A response containing a list of subscriptions.

Bulk operations

Bulk operations available for objects. These endpoints return a BulkOperation that executes the job asynchronously. Progress can be tracked via the Bulk operations API.

Endpoints

POST/v1/objects/{collection}/bulk/set

POST/v1/objects/{collection}/bulk/subscriptions/add

POST/v1/objects/{collection}/bulk/delete

POST/v1/objects/{collection}/bulk/subscriptions/delete

Bulk set objects

Bulk sets up to 1,000 objects at a time in the specified collection.

Endpoint

POST/v1/objects/{collection}/bulk/set

Rate limit

Tier 1

Path parameters

collectionstringrequired

The collection this object belongs to.

Request body

objectsBulkSetObjectRequest[]required

A list of objects.

Returns

BulkOperation

A bulk operation entity.

Bulk add subscriptions

Add subscriptions for all objects in a single collection. If a subscription for an object in the collection already exists, it will be updated. This endpoint also handles inline identifications for the recipient field.

Endpoint

POST/v1/objects/{collection}/bulk/subscriptions/add

Rate limit

Tier 1

Path parameters

collectionstringrequired

The collection this object belongs to.

Request body

subscriptionsobject[]required

A nested list of subscriptions.

Returns

BulkOperation

A bulk operation entity.

Bulk delete objects

Bulk deletes objects from the specified collection.

Endpoint

POST/v1/objects/{collection}/bulk/delete

Rate limit

Tier 1

Path parameters

collectionstringrequired

The collection this object belongs to.

Request body

object_idsstring[]required

List of object IDs to delete.

Returns

BulkOperation

A bulk operation entity.

Bulk delete subscriptions

Delete subscriptions for many objects in a single collection type. If a subscription for an object in the collection doesn't exist, it will be skipped.

Endpoint

POST/v1/objects/{collection}/bulk/subscriptions/delete

Rate limit

Tier 1

Path parameters

collectionstringrequired

The collection this object belongs to.

Request body

subscriptionsobject[]required

A nested list of subscriptions.

Returns

BulkOperation

A bulk operation entity.

Object

A custom Object entity which belongs to a collection.

Attributes

__typenamestringrequired

The typename of the schema.

collectionstringrequired

The collection this object belongs to.

created_atstringnullable

Timestamp when the resource was created.

idstringrequired

Unique identifier for the object.

propertiesobject

The custom properties associated with the object.

updated_atstringrequired

The timestamp when the resource was last updated.

InlineIdentifyObjectRequest

A custom Object entity which belongs to a collection.

Attributes

channel_dataunknown

An optional set of [channel data](/managing-recipients/setting-channel-data) for the object. This is a list of `ChannelData` objects.

collectionstringrequired

The collection this object belongs to.

created_atstringnullable

Timestamp when the resource was created.

idstringrequired

Unique identifier for the object.

namestringnullable

An optional name for the object.

preferencesunknown

An optional set of [preferences](/concepts/preferences) for the object.

Tenants

A Tenant a grouping with configurable settings that can be applied to a workflow when it's triggered in order to override account-level settings such as branding. Use tenants when sending a notification to user(s) that you want to configure specific brand elements for, such as a separate organization logo.

Endpoints

DELETE/v1/tenants/{id}

GET/v1/tenants/{id}

PUT/v1/tenants/{id}

GET/v1/tenants

Delete a tenant

Delete a tenant and all associated data. This operation cannot be undone.

Endpoint

DELETE/v1/tenants/{id}

Rate limit

Tier 2

Path parameters

idstringrequired

The unique identifier for the tenant.

Returns

204 No Content

Get a tenant

Get a tenant by ID.

Endpoint

GET/v1/tenants/{id}

Rate limit

Tier 4

Path parameters

idstringrequired

The unique identifier for the tenant.

Query parameters

resolve_full_preference_settingsboolean

When true, merges environment-level default preferences into the tenant's `settings.preference_set` field before returning the response. Defaults to false.

Returns

Tenant

A tenant entity.

Set a tenant

Sets a tenant within an environment, performing an upsert operation. Any existing properties will be merged with the incoming properties.

Endpoint

PUT/v1/tenants/{id}

Rate limit

Tier 3

Path parameters

idstringrequired

The unique identifier for the tenant.

Query parameters

resolve_full_preference_settingsboolean

When true, merges environment-level default preferences into the tenant's `settings.preference_set` field before returning the response. Defaults to false.

Request body

channel_dataunknown

The channel data for the tenant.

namestringnullable

An optional name for the tenant.

settingsobject

The settings for the tenant. Includes branding and preference set.

Returns

SetTenantResponse

The response from setting a tenant.

List tenants

List tenants for the current environment.

Endpoint

GET/v1/tenants

Rate limit

Tier 4

Query parameters

tenant_idstring

Filter tenants by ID.

namestring

Filter tenants by name.

afterstring

The cursor to fetch entries after.

beforestring

The cursor to fetch entries before.

page_sizeinteger

The number of items per page (defaults to 50).

Returns

ListTenantsResponse

A response containing a list of tenants.

Bulk operations

Bulk operations available for tenants. These endpoints return a BulkOperation that executes the job asynchronously. Progress can be tracked via the Bulk operations API.

Endpoints

POST/v1/tenants/bulk/delete

POST/v1/tenants/bulk/set

Bulk delete tenants

Delete up to 1,000 tenants at a time in a single operation. This operation cannot be undone.

Endpoint

POST/v1/tenants/bulk/delete

Rate limit

Tier 1

Query parameters

tenant_ids[]string[]required

The IDs of the tenants to delete.

Returns

BulkOperation

A bulk operation entity.

Bulk set tenants

Set or update up to 1,000 tenants in a single operation.

Endpoint

POST/v1/tenants/bulk/set

Rate limit

Tier 1

Request body

tenantsInlineTenantRequest[]required

The tenants to be upserted.

Returns

BulkOperation

A bulk operation entity.

Tenant

A tenant entity.

Attributes

__typenamestringrequired

The typename of the schema.

idstringrequired

The unique identifier for the tenant.

namestringnullable

An optional name for the tenant.

settingsobjectnullable

The settings for the tenant. Includes branding and preference set.

TenantRequest

A tenant to be set in the system. You can supply any additional properties on the tenant object.

Attributes

channel_dataunknown

The channel data for the tenant.

idstringrequired

The unique identifier for the tenant.

namestringnullable

An optional name for the tenant.

preferencesunknown

The preferences for the tenant.

settingsobject

The settings for the tenant. Includes branding and preference set.

InlineTenantRequest

An request to set a tenant inline.

Attributes

Recipients

A Recipient represents a person or a non-user entity from your system, represented in Knock. They are most commonly the recipient of a notification, but can also be used to denote an actor that a notification is sent on behalf of.

Subscriptions

Subscriptions express the relationship between a Recipient (the subscriber) and an Object. Subscribers are notified when the object that they are subscribed to is a recipient on a workflow trigger request.

Subscription

A subscription object.

Attributes

__typenamestringrequired

The typename of the schema.

inserted_atstringrequired

Timestamp when the resource was created.

objectObjectrequired

A custom [Object](/concepts/objects) entity which belongs to a collection.

propertiesobjectnullable

The custom properties associated with the subscription relationship.

recipientRecipientrequired

A recipient of a notification, which is either a user or an object.

updated_atstringrequired

The timestamp when the resource was last updated.

Preferences

Preferences determine whether a recipient should receive a particular type of notification. By default all preferences are opted in unless a preference explicitly opts the recipient out of the notification.

The preference set :id can be either "default" or a tenant.id. Learn more about per-tenant preferences.

PreferenceSet

A preference set represents a specific set of notification preferences for a recipient. A recipient can have multiple preference sets.

Attributes

categoriesunknown

An object where the key is the category and the values are the preference settings for that category.

channel_typesunknown

An object where the key is the channel type and the values are the preference settings for that channel type.

channelsunknown

An object where the key is the channel ID and the values are the preference settings for that channel ID.

commercial_subscribedbooleannullable

Whether the recipient is subscribed to commercial communications. When false, the recipient will not receive commercial workflow notifications.

idstringrequired

Unique identifier for the preference set.

workflowsunknown

An object where the key is the workflow key and the values are the preference settings for that workflow.

PreferenceSetRequest

A request to set a preference set for a recipient.

Attributes

__persistence_strategy__string

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

One of: "merge", "replace"

categoriesunknown

An object where the key is the category and the values are the preference settings for that category.

channel_typesunknown

An object where the key is the channel type and the values are the preference settings for that channel type.

channelsunknown

An object where the key is the channel ID and the values are the preference settings for that channel ID.

commercial_subscribedbooleannullable

Whether the recipient is subscribed to commercial communications. When false, the recipient will not receive commercial workflow notifications.

workflowsunknown

An object where the key is the workflow key and the values are the preference settings for that workflow.

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.

Attributes

PreferenceSetChannelTypes

Channel type preferences.

Attributes

chatunknown

Whether the channel type is enabled for the preference set.

emailunknown

Whether the channel type is enabled for the preference set.

httpunknown

Whether the channel type is enabled for the preference set.

in_app_feedunknown

Whether the channel type is enabled for the preference set.

pushunknown

Whether the channel type is enabled for the preference set.

smsunknown

Whether the channel type is enabled for the preference set.

PreferenceSetChannelTypeSetting

A set of settings for a channel type. Currently, this can only be a list of conditions to apply.

Attributes

conditionsCondition[]required

A list of conditions to apply to a channel type.

PreferenceSetChannelSetting

A set of settings for a specific channel. Currently, this can only be a list of conditions to apply.

Attributes

conditionsCondition[]required

A list of conditions to apply to a specific channel.

Channel data

Channel data is channel-specific information stored on a Knock user or object that's needed to deliver a notification to an end provider.

For a push channel, this includes device-specific tokens that map the recipient to the device they use, as well as device metadata for supported providers. For chat apps, such as Slack, this includes the access token used to send notifications to a customer's Slack channel.

The shape of the data payload varies depending on the channel type; you can learn more about channel data schemas here.

ChannelData

Channel data for a given channel type.

Attributes

__typenamestringrequired

The typename of the schema.

channel_idstringrequired

The unique identifier for the channel.

dataobjectrequired

Channel data for a given channel type.

providerstring

The type of provider.

One of: "push_fcm", "push_apns", "push_aws_sns", "push_expo", "push_one_signal", "chat_slack", "chat_ms_teams", "chat_discord", "http_knock_webhook"

ChannelDataRequest

A request to set channel data for a type of channel.

Attributes

dataobjectrequired

Channel data for a given channel type.

PushChannelDataTokensOnly

Push channel data.

Attributes

tokensstring[]required

A list of push channel tokens.

PushChannelDataDevicesOnly

Push channel data.

Attributes

devicesobject[]required

A list of devices. Each device contains a token, and optionally a locale and timezone.

SlackChannelData

Slack channel data.

Attributes

connectionsobject[]required

List of Slack channel connections.

tokenSlackChannelDataTokenObjectnullable

A Slack connection token.

AWSSNSPushChannelDataTargetARNsOnly

AWS SNS push channel data.

Attributes

target_arnsstring[]required

A list of platform endpoint ARNs. See [Setting up an Amazon SNS platform endpoint for mobile notifications](https://docs.aws.amazon.com/sns/latest/dg/mobile-platform-endpoint.html).

AWSSNSPushChannelDataDevicesOnly

AWS SNS push channel data.

Attributes

devicesobject[]required

A list of devices. Each device contains a target_arn, and optionally a locale and timezone.

MsTeamsChannelData

Microsoft Teams channel data.

Attributes

connectionsobject[]required

List of Microsoft Teams connections.

ms_teams_tenant_idstringnullable

Microsoft Teams tenant ID.

DiscordChannelData

Discord channel data.

Attributes

connectionsobject[]required

List of Discord channel connections.

OneSignalChannelDataPlayerIdsOnly

OneSignal channel data.

Attributes

player_idsstring[]required

A list of OneSignal player IDs.

InlineChannelDataRequest

A request to set channel data for a type of channel inline.

Attributes

Recipient

A recipient of a notification, which is either a user or an object.

Attributes

RecipientRequest

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.

Attributes

RecipientReference

A reference to a recipient, either a user identifier (string) or an object reference (ID, collection).

Attributes

Schedules

A Schedule allows you to automatically trigger a workflow at a given time for one or more recipients. You can think of a schedule as a managed, recipient-timezone-aware cron job that Knock will run on your behalf.

Endpoints

POST/v1/schedules

GET/v1/schedules

PUT/v1/schedules

DELETE/v1/schedules

Create schedules

Creates one or more schedules for a workflow with the specified recipients, timing, and data. Schedules can be one-time or recurring. This endpoint also handles inline identifications for the actor, recipient, and tenant fields.

Endpoint

POST/v1/schedules

Rate limit

Tier 3

Request body

actorobject

A map of properties describing a user or an object to identify in Knock and mark as who or what performed the action.

dataobjectnullable

An optional map of data to pass into the workflow execution. There is a 10MB limit on the size of the full `data` payload. Any individual string value greater than 1024 bytes in length will be [truncated](/developer-tools/api-logs#log-truncation) in your logs.

ending_atstringnullable

The ending date and time for the schedule.

recipientsRecipientRequest[]required

The recipients to set the schedule for. Limited to 100 recipients per request.

repeatsScheduleRepeatRule[]

The repeat rule for the schedule.

scheduled_atstringnullable

The starting date and time for the schedule.

tenantunknown

The tenant to trigger the workflow for. Triggering with a tenant will use any tenant-level overrides associated with the tenant object, and all messages produced from workflow runs will be tagged with the tenant.

workflowstringrequired

The key of the workflow.

Returns

SchedulesResponse

A list of schedules.

List schedules

Returns a paginated list of schedules for the current environment, filtered by workflow and optionally by recipients and tenant.

Endpoint

GET/v1/schedules

Rate limit

Tier 4

Query parameters

workflowstringrequired

Filter by workflow key.

recipients[]RecipientReference[]

Filter by recipient references.

tenantstring

Filter by tenant ID.

afterstring

The cursor to fetch entries after.

beforestring

The cursor to fetch entries before.

page_sizeinteger

The number of items per page (defaults to 50).

Returns

ListSchedulesResponse

A response containing a list of schedules.

Update schedules

Updates one or more existing schedules with new timing, data, or other properties. All specified schedule IDs will be updated with the same values. This endpoint also handles inline identifications for the actor, recipient, and tenant fields.

Endpoint

PUT/v1/schedules

Rate limit

Tier 3

Request body

actorunknown

A map of properties describing a user or an object to identify in Knock and mark as who or what performed the action.

dataobjectnullable

An optional map of data to pass into the workflow execution. There is a 10MB limit on the size of the full `data` payload. Any individual string value greater than 1024 bytes in length will be [truncated](/developer-tools/api-logs#log-truncation) in your logs.

ending_atstringnullable

The ending date and time for the schedule.

repeatsScheduleRepeatRule[]

The repeat rule for the schedule.

schedule_idsstring[]required

A list of schedule IDs.

scheduled_atstringnullable

The starting date and time for the schedule.

tenantunknown

The tenant to trigger the workflow for. Triggering with a tenant will use any tenant-level overrides associated with the tenant object, and all messages produced from workflow runs will be tagged with the tenant.

Returns

SchedulesResponse

A list of schedules.

Delete schedules

Permanently deletes one or more schedules identified by the provided schedule IDs. This operation cannot be undone.

Endpoint

DELETE/v1/schedules

Rate limit

Tier 3

Request body

schedule_idsstring[]required

A list of schedule IDs.

Returns

SchedulesResponse

A list of schedules.

Bulk schedules

Bulk operations available for schedules.

Endpoints

POST/v1/schedules/bulk/create

Create schedules in bulk

Bulk creates up to 1,000 schedules at a time. This endpoint also handles inline identifications for the actor, recipient, and tenant fields.

Endpoint

POST/v1/schedules/bulk/create

Rate limit

Tier 1

Request body

schedulesobject[]required

A list of schedules.

Returns

BulkOperation

A bulk operation entity.

Schedule

A schedule represents a recurring workflow execution.

Attributes

__typenamestring

The typename of the schema.

actorunknown

A map of properties describing a user or an object to identify in Knock and mark as who or what performed the action.

dataobjectnullable

An optional map of data to pass into the workflow execution. There is a 10MB limit on the size of the full `data` payload. Any individual string value greater than 1024 bytes in length will be [truncated](/developer-tools/api-logs#log-truncation) in your logs.

idstringrequired

Unique identifier for the schedule.

inserted_atstringrequired

Timestamp when the resource was created.

last_occurrence_atstringnullable

The last occurrence of the schedule.

next_occurrence_atstringnullable

The next occurrence of the schedule.

recipientRecipientrequired

A recipient of a notification, which is either a user or an object.

repeatsScheduleRepeatRule[]required

The repeat rule for the schedule.

tenantstringnullable

The tenant to trigger the workflow for. Triggering with a tenant will use any tenant-level overrides associated with the tenant object, and all messages produced from workflow runs will be tagged with the tenant.

updated_atstringrequired

The timestamp when the resource was last updated.

workflowstringrequired

The workflow the schedule is applied to.

ScheduleRepeatRule

The repeat rule for the schedule.

Attributes

__typenamestring

The typename of the schema.

day_of_monthintegernullable

The day of the month to repeat the schedule.

daysstring[]nullable

The days of the week to repeat the schedule.

frequencystringrequired

The frequency of the schedule.

One of: "daily", "weekly", "monthly", "hourly"

hoursintegernullable

The hour of the day to repeat the schedule.

intervalinteger

The interval of the schedule.

Default: 1

minutesintegernullable

The minute of the hour to repeat the schedule.

Audiences

An Audience represents a user segment. Use the Audiences API to sync user segments from your data warehouse to Knock. Audiences can be used to target messages or orchestrate workflows via branch and step conditions. They can also be used as the recipient of a Broadcast.

Endpoints

POST/v1/audiences/{key}/members

GET/v1/audiences/{key}/members

DELETE/v1/audiences/{key}/members

Add members

Adds one or more members to the specified audience.

Endpoint

POST/v1/audiences/{key}/members

Rate limit

Tier 3

Path parameters

keystringrequired

The key of the audience.

Request body

membersAudienceMemberRequest[]required

A list of audience members to add. Limited to 1,000 members per request.

Returns

204 No Content

List members

Returns a paginated list of members for the specified audience.

Endpoint

GET/v1/audiences/{key}/members

Rate limit

Tier 4

Path parameters

keystringrequired

The key of the audience.

Returns

ListAudienceMembersResponse

A paginated list of audience members.

Remove members

Removes one or more members from the specified audience.

Endpoint

DELETE/v1/audiences/{key}/members

Rate limit

Tier 3

Path parameters

keystringrequired

The key of the audience.

Request body

membersAudienceMemberRequest[]required

A list of audience members to remove.

Returns

204 No Content

AudienceMember

An audience member.

Attributes

__typenamestringrequired

The typename of the schema.

added_atstringrequired

Timestamp when the resource was created.

tenantstringnullable

The unique identifier for the tenant.

userUserrequired

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.

user_idstringrequired

The unique identifier of the user.

Bulk operations

A Bulk Operation is a set of changes applied across 0 or more records triggered via a call to the Knock API and performed asynchronously. The BulkOperation record represents the state of the operation, including recording the number of rows that have been modified during the operation.

Please note here: the estimated_total_rows field may have a different value to the processed_rows field due to the asynchronous nature of the operation.

Endpoints

GET/v1/bulk_operations/{id}

Get bulk operation

Retrieves a bulk operation (if it exists) and displays the current state of it.

Endpoint

GET/v1/bulk_operations/{id}

Rate limit

Tier 4

Path parameters

idstringrequired

The ID of the bulk operation to retrieve.

Returns

BulkOperation

A bulk operation entity.

BulkOperation

A bulk operation entity.

Attributes

__typenamestringrequired

The typename of the schema.

completed_atstringnullable

Timestamp when the bulk operation was completed.

error_countinteger

The number of failed operations.

error_itemsobject[]

A list of items that failed to be processed.

estimated_total_rowsintegerrequired

The estimated total number of rows to process.

failed_atstringnullable

Timestamp when the bulk operation failed.

idstringrequired

Unique identifier for the bulk operation.

inserted_atstringrequired

Timestamp when the resource was created.

namestringrequired

The name of the bulk operation.

processed_rowsintegerrequired

The number of rows processed so far.

progress_pathstring

The URI to the bulk operation's progress.

started_atstringnullable

Timestamp when the bulk operation was started.

statusstringrequired

The status of the bulk operation.

One of: "queued", "processing", "completed", "failed"

success_countintegerrequired

The number of successful operations.

updated_atstringrequired

The timestamp when the resource was last updated.

Providers

A Provider is a channel-specific configuration that determines how a message is delivered to a recipient.

Slack

A Slack provider is a channel-specific configuration that determines how a message is delivered to a recipient via Slack.

Endpoints

GET/v1/providers/slack/{channel_id}/channels

GET/v1/providers/slack/{channel_id}/auth_check

PUT/v1/providers/slack/{channel_id}/revoke_access

List channels

List Slack channels for a Slack workspace.

Endpoint

GET/v1/providers/slack/{channel_id}/channels

Rate limit

Tier 2

Path parameters

channel_idstringrequired

The ID of the Knock Slack channel to get channels for.

Query parameters

access_token_objectstringrequired

A JSON encoded string containing the access token object reference.

query_options.cursorstring

Paginate through collections of data by setting the cursor parameter to a next_cursor attribute returned by a previous request's response_metadata. Default value fetches the first "page" of the collection.

query_options.limitinteger

The maximum number of channels to return. Defaults to 200.

query_options.exclude_archivedboolean

Set to true to exclude archived channels from the list. Defaults to `true` when not explicitly provided.

query_options.typesstring

Mix and match channel types by providing a comma-separated list of any combination of public_channel, private_channel, mpim, im. Defaults to `"public_channel,private_channel"`. If the user's Slack ID is unavailable, this option is ignored and only public channels are returned.

query_options.team_idstring

Encoded team ID (T1234) to list channels in, required if org token is used.

Returns

ChannelsForSlackProviderResponse

The response from a Slack provider request, containing a list of channels.

AuthenticationError

Authentication error response

Check auth

Check if a Slack channel is authenticated.

Endpoint

GET/v1/providers/slack/{channel_id}/auth_check

Rate limit

Tier 2

Path parameters

channel_idstringrequired

The ID of the Knock Slack channel to check.

Query parameters

access_token_objectstringrequired

A JSON encoded string containing the access token object reference.

Returns

SlackAuthCheckResponse

The response from a Slack auth check request.

Revoke access

Revoke access for a Slack channel.

Endpoint

PUT/v1/providers/slack/{channel_id}/revoke_access

Rate limit

Tier 2

Path parameters

channel_idstringrequired

The ID of the Knock Slack channel to revoke access for.

Query parameters

access_token_objectstringrequired

A JSON encoded string containing the access token object reference.

Returns

SuccessResponse

A response indicating the operation was successful.

AuthenticationError

Authentication error response

Microsoft Teams

A Microsoft Teams provider is a channel-specific configuration that determines how a message is delivered to a recipient via Microsoft Teams.

Endpoints

GET/v1/providers/ms-teams/{channel_id}/channels

GET/v1/providers/ms-teams/{channel_id}/teams

GET/v1/providers/ms-teams/{channel_id}/auth_check

PUT/v1/providers/ms-teams/{channel_id}/revoke_access

List channels

List the Microsoft Teams channels within a team. By default, archived and private channels are excluded from the results.

Endpoint

GET/v1/providers/ms-teams/{channel_id}/channels

Rate limit

Tier 2

Path parameters

channel_idstringrequired

The ID of the Knock Microsoft Teams channel to get channels for.

Query parameters

ms_teams_tenant_objectstringrequired

A JSON encoded string containing the Microsoft Teams tenant object reference.

team_idstringrequired

Microsoft Teams team ID.

query_options.$filterstring

[OData param](https://learn.microsoft.com/en-us/graph/query-parameters) passed to the Microsoft Graph API to filter channels.

query_options.$selectstring

[OData param](https://learn.microsoft.com/en-us/graph/query-parameters) passed to the Microsoft Graph API to select specific properties.

Returns

ChannelsForMsTeamsProviderResponse

The response from a Microsoft Teams provider request, containing a list of channels.

List teams

Get a list of teams belonging to the Microsoft Entra tenant. By default, archived and private channels are excluded from the results.

Endpoint

GET/v1/providers/ms-teams/{channel_id}/teams

Rate limit

Tier 2

Path parameters

channel_idstringrequired

The ID of the Knock Microsoft Teams channel to get teams for.

Query parameters

ms_teams_tenant_objectstringrequired

A JSON encoded string containing the Microsoft Teams tenant object reference.

query_options.$filterstring

[OData param](https://learn.microsoft.com/en-us/graph/query-parameters) passed to the Microsoft Graph API to filter teams.

query_options.$selectstring

[OData param](https://learn.microsoft.com/en-us/graph/query-parameters) passed to the Microsoft Graph API to select fields on a team.

query_options.$topinteger

[OData param](https://learn.microsoft.com/en-us/graph/query-parameters) passed to the Microsoft Graph API to limit the number of teams returned.

query_options.$skiptokenstring

[OData param](https://learn.microsoft.com/en-us/graph/query-parameters) passed to the Microsoft Graph API to retrieve the next page of results.

Returns

TeamsForMsTeamsProviderResponse

The response from a Microsoft Teams provider request, containing a list of teams.

Check auth

Check if a connection to Microsoft Teams has been authorized for a given Microsoft Teams tenant object.

Endpoint

GET/v1/providers/ms-teams/{channel_id}/auth_check

Rate limit

Tier 2

Path parameters

channel_idstringrequired

The ID of the Knock Microsoft Teams channel to check.

Query parameters

ms_teams_tenant_objectstringrequired

A JSON encoded string containing the Microsoft Teams tenant object reference.

Returns

MsTeamsAuthCheckResponse

The response from a Microsoft Teams auth check request.

Revoke access

Remove a Microsoft Entra tenant ID from a Microsoft Teams tenant object.

Endpoint

PUT/v1/providers/ms-teams/{channel_id}/revoke_access

Rate limit

Tier 2

Path parameters

channel_idstringrequired

The ID of the Knock Microsoft Teams channel to revoke access for.

Query parameters

ms_teams_tenant_objectstringrequired

A JSON encoded string containing the Microsoft Teams tenant object reference.

Returns

SuccessResponse

A response indicating the operation was successful.

AuthenticationError

Authentication error response

Shared

Resources that are shared across the API.

Condition

A condition to be evaluated.

Attributes

argumentstringrequirednullable

The argument value to compare against in the condition.

operatorstringrequired

The operator to use in the condition evaluation.

One of: "equal_to", "not_equal_to", "greater_than", "less_than", "greater_than_or_equal_to", "less_than_or_equal_to", "contains", "not_contains", "empty", "not_empty", "contains_all", "is_timestamp", "is_not_timestamp", "is_timestamp_on_or_after", "is_timestamp_before", "is_timestamp_on_or_after_date", "is_timestamp_before_date", "is_timestamp_between", "is_audience_member", "is_not_audience_member"

variablestringrequired

The variable to be evaluated in the condition.

PageInfo

Pagination information for a list of resources.

Attributes

__typenamestringrequired

The typename of the schema.

afterstringnullable

The cursor to fetch entries after.

beforestringnullable

The cursor to fetch entries before.

page_sizeintegerrequired

The number of items per page (defaults to 50).

API reference

Overview

Workflows

Trigger workflow

Endpoint

Rate limit

Path parameters

Request body

Returns

Cancel workflow

Endpoint

Rate limit

Path parameters

Request body

Returns

Messages

Get message

Endpoint

Rate limit

Path parameters

Returns

Get message content

Endpoint

Rate limit

Path parameters

Returns

List messages

Endpoint

Rate limit

Query parameters

Returns

List events

Endpoint

Rate limit

Path parameters

Query parameters

Returns

List delivery logs

Endpoint

Rate limit

Path parameters

Query parameters

Returns

List activities

Endpoint

Rate limit

Path parameters

Query parameters

Returns

Mark message as seen

Endpoint

Rate limit

Path parameters

Returns

Mark message as unseen

Endpoint

Rate limit

Path parameters

Returns

Mark message as read

Endpoint

Rate limit

Path parameters

Returns

Mark message as unread

Endpoint

Rate limit

Path parameters

Returns

Mark message as interacted

Endpoint

Rate limit

Path parameters

Request body

Returns

Archive message

Endpoint

Rate limit

Path parameters