API
Complete reference documentation for the Knock API.
API reference
The Knock API enables you to add a complete notification engine to your product. This API provides programmatic access to integrating Knock via a REST-ful API.
Client libraries
API keys
Knock authenticates your API requests using your account's API keys. API requests made without authentication or using an incorrect key will return a 401 error. Requests using a valid key but with insufficient permissions will return a 403 error.
You can view and manage your API keys in the Developer Dashboard. There are two types of API keys:
-
Publishable keys are only meant to identify your account with Knock. They aren't secret, and can safely be made public in any of your client-side code. Publishable keys are prefixed with
pk_*. -
Secret keys can perform any API request to Knock, they should be kept secure and private! Be sure to prevent secret keys from being made publicly accessible, such as in client-side code, GitHub, unsecured S3 buckets, and so forth. Secret keys are prefixed with
sk_*.
Each Environment in your account has both a publishable and secret key pair. API requests will be scoped to the provided key's Environment.
Authentication
You must pass your API key to Knock as a Bearer token using the Authorization header.
Rate limits
Each endpoint in the Knock API is rate limited. Knock uses a tier system to determine the rate limit scale for each endpoint. When your request has been rate limited, the Knock API will return a 429 Too Many Requests error in response.
Knock's default behavior scopes rate limits based on the authorizing credential used in your requests. When you use a public or private API key to authorize a request, Knock will scope the rate limit for each endpoint by the environment associated with the key. If you use a signed user token as your authorizing credential, Knock will scope the rate limit by both the key's environment and the signing user. See our guide on enhanced security mode for more details on working with signed user tokens.
If you're concerned about exceeding a Knock rate limit, please contact us and we can help figure out a usage rate that's right for your specific needs.
Batch and bulk endpoint deduplication rate limits
Knock's batch and bulk endpoints may also have an additional layer of rate limiting applied. For these cases, Knock will also limit the number of times you can update a specific entity over a given scale. These limits are in place to prevent too many duplicate modifications applied to the same set of entities.
When you exceed a batch deduplication rate limit, Knock will still return a success (2xx) response if it is able to handle the request. For any entities not updated due to a rate limit hit, Knock will return the data as it exists at request time. Knock will also include an x-ratelimited-{param} header. The {param} value will be the name of the request param within which the rate limit was applied. The value will be a comma-delimited string of the param values that were rejected due to a rate limit hit.
Knock can apply batch deduplication rate limits to all or part of a request. If Knock rejects a subset of your batch, you can expect to see the full set of requested entities in the response body, and the IDs of those that were rejected in the x-ratelimited-{param} header.
Idempotent requests
Knock supports idempotency so that requests can be retried safely without unintended side effects.
To perform an idempotent request, set an Idempotency-Key header on your request. This idempotency key is a unique value that you generate for each request. It is used to identify and prevent the duplicate processing of requests. If you retry a request with the same idempotency key within 24 hours from the original request, Knock will return the same response as the original request. You may use any string up to 255 characters in length as an idempotency key.
Idempotency keys can be random UUIDs, or they can have some meaning in your application. For example, if you are sending a notification after a user has placed an order, you could use a key that is a combination of the reason for the notification, the user ID, and the order ID (e.g. order-placed:user-123:order-456). If your user then cancels the order, you could use an idempotency key like order-cancelled:user-123:order-456. This will ensure each type of notification is only sent once, even if your system retries the request multiple times.
If you are making calls to Knock from a job queue, the ID of the job can be a good choice for an idempotency key. If the job fails and is retried, the same idempotency key will be used.
Data retention
Several V1 API endpoints return data that is subject to deletion according to the data retention policy associated with your account. These endpoints are tagged with the Retention policy applied badge.
For more information, see the data retention docs.
Bulk endpoints
Knock exposes several endpoints that enqueue and return a BulkOperation. These endpoints perform their logic asynchronously, and you use the BulkOperation record to track progress.
In some cases, a bulk endpoint will accept a large set of entities to perform some action upon. In others, a bulk endpoint will accept a set of filter parameters and then execute an action across a large set of data on your account.
See the Bulk operations section for more information on parsing and polling bulk operation statuses.
Trigger data filtering
Some V1 API endpoints that return lists of message data accept a trigger_data parameter. Knock uses this parameter to scope results it returns down to messages generated with the trigger data you provide.
The trigger data that Knock filters against is the combined and truncated data from the time the message was generated.
If a batch step preceded the creation of your message, the trigger data available for filtering will be the combined data for all the workflow triggers bundled into your batch. If a fetch step preceded, then the filterable data will include any data pulled in via the fetch step request.
Knock truncates trigger data for filtering to ensure it can efficiently process your request. The current data truncation rules are:
- Nested data structures (objects and arrays) are removed. Trigger data for filtering will be a JSON object with a single level of key-value pairs.
- Supported values are the JSON scalars string, number, boolean, and
null. - String values are limited to 256 characters in length. Strings that exceed this limit are truncated to the maximum.
Pagination
All top-level API resources expose support for bulk fetches via a list method. For instance, you can list users, list objects in a collection, and list subscriptions.
Resources that return multiple entities support the same cursor-based pagination to interact with the resources, using after, before, and page_size parameters as well as returning a common format for the metadata associated with the page.
Query parameters
Response format
PageInfo response details
Errors
Knock uses standard HTTP response codes to indicate the success or failure of your API requests.
-
2xxsuccess status codes confirm that your request worked as expected. -
4xxerror status codes indicate an error caused by incorrect or missing request information (e.g. providing an incorrect API key). -
5xxerror status codes indicate a Knock server error.
Error codes
4xx
error codes you may encounter while working with the Knock API. We also provide additional context on how to resolve them.Your request needs a JWT signing key. You can learn more about JWT signing keys in our client authentication docs.
This environment requires that you supply a `X-Knock-User-Token` header when using a public API key. You can learn more in our client authentication docs.
The workflow you attempted to invoke is marked with an inactive status. To resolve this error, activate the workflow on its page in the dashboard.
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.)
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
Path parameters
Key of the workflow to trigger.
Request body
A map of properties describing a user or an object to identify in Knock and mark as who or what performed the action.
An optional key that is used to reference a specific workflow trigger request when issuing a workflow cancellation request. Must be provided while triggering a workflow in order to enable subsequent cancellation. Should be unique across trigger requests to avoid unintentional cancellations.
An optional map of data to pass into the workflow execution.
The recipients to trigger the workflow for. Can inline identify users, objects, or use a list of user IDs. Limited to 1,000 recipients.
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
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
Path parameters
The key of the workflow to cancel.
Request body
An optional key that is used to reference a specific workflow trigger request when issuing a workflow cancellation request. Must be provided while triggering a workflow in order to enable subsequent cancellation. Should be unique across trigger requests to avoid unintentional cancellations.
A list of recipients to cancel the notification for. If omitted, cancels for all recipients associated with the cancellation key.
Returns
A 204 No Content response.
Messages
A Message is a notification delivered on a particular channel to a user.
Get message
Retrieves a specific message by its ID.
Endpoint
Path parameters
The unique identifier for the message.
Returns
Represents a single message that was generated by a workflow for a given channel.
Get message content
List messages
Returns a paginated list of messages for the current environment.
Endpoint
Query parameters
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page.
Limits the results to items with the corresponding tenant.
Limits the results to items with the corresponding channel ID.
Limits the results to messages with the given delivery status.
Limits the results to messages with the given engagement status.
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.
Limits the results to messages related to any of the provided categories.
Limits the results to messages triggered by the given workflow key.
Limits the results to messages associated with the top-level workflow run ID returned by the workflow trigger request.
Limits the results to messages for a specific recipient's workflow run.
Limits the results to only messages that were generated with the given data. See trigger data filtering for more information.
Limits the results to messages inserted after or on the given date.
Limits the results to messages inserted before or on the given date.
Limits the results to messages inserted after the given date.
Limits the results to messages inserted before the given date.
Returns
A paginated list of messages.
List events
Returns a paginated list of events for the specified message.
Endpoint
Path parameters
The ID of the message to fetch events for.
Query parameters
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page.
Returns
Returns a paginated list of delivery and engagement events for the specified message.
List delivery logs
Returns a paginated list of delivery logs for the specified message.
Endpoint
Path parameters
The ID of the message to fetch delivery logs for.
Query parameters
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page.
Returns
A message delivery log response.
List activities
Returns a paginated list of activities for the specified message.
Endpoint
Path parameters
The ID of the message to fetch activities for.
Query parameters
The trigger data to filter activities by.
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page.
Returns
Returns a paginated list of activities associated with a given message. For messages produced after a batch step, this will contain one or more activities. Non-batched messages will always return a single activity.
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
Path parameters
The unique identifier for the message.
Returns
Represents a single message that was generated by a workflow for a given channel.
Mark message as unseen
Marks a message as unseen. This reverses the seen state. Read more about message engagement statuses here.
Endpoint
Path parameters
The unique identifier for the message.
Returns
Represents a single message that was generated by a workflow for a given channel.
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
Path parameters
The unique identifier for the message.
Returns
Represents a single message that was generated by a workflow for a given channel.
Mark message as unread
Marks a message as unread. This reverses the read state. Read more about message engagement statuses here.
Endpoint
Path parameters
The unique identifier for the message.
Returns
Represents a single message that was generated by a workflow for a given channel.
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
Path parameters
The unique identifier for the message.
Request body
Metadata about the interaction.
Returns
Represents a single message that was generated by a workflow for a given channel.
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
Path parameters
The unique identifier for the message.
Returns
Represents a single message that was generated by a workflow for a given channel.
Unarchive message
Removes a message from the archived state, making it visible in the default message list in the feed again.
Endpoint
Path parameters
The unique identifier for the message.
Returns
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.
Batch get message contents
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
Request body
The message IDs to update the status of.
Returns
The list of messages that were updated.
Mark messages as unseen
Marks the given messages as unseen. This reverses the seen state. Read more about message engagement statuses here.
Endpoint
Request body
The message IDs to update the status of.
Returns
The list of messages that were updated.
Mark messages as read
Marks the given messages as read. Read more about message engagement statuses here.
Endpoint
Request body
The message IDs to update the status of.
Returns
The list of messages that were updated.
Mark messages as unread
Marks the given messages as unread. This reverses the read state. Read more about message engagement statuses here.
Endpoint
Request body
The message IDs to update the status of.
Returns
The list of messages that were updated.
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
Request body
The message IDs to batch mark as interacted with.
Metadata about the interaction.
Returns
The list of messages that were updated.
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
Request body
The message IDs to update the status of.
Returns
The list of messages that were updated.
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
Request body
The message IDs to update the status of.
Returns
The list of messages that were updated.
List activities
Returns a paginated list of activities for the specified message.
Endpoint
Path parameters
The ID of the message to fetch activities for.
Query parameters
The trigger data to filter activities by.
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page.
Returns
Returns a paginated list of activities associated with a given message. For messages produced after a batch step, this will contain one or more activities. Non-batched messages will always return a single activity.
Message
Represents a single message that was generated by a workflow for a given channel.
Attributes
The typename of the schema.
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.
Timestamp when the message was archived.
The ID for the channel the message was sent through.
Timestamp when the message was clicked.
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. For messages produced after a batch step, includes the payload data from the most-recent trigger request (the final activity in the batch).
A list of engagement statuses.
The unique identifier for the message.
Timestamp when the resource was created.
Timestamp when the message was interacted with.
Timestamp when a link in the message was clicked.
The metadata associated with the message.
Timestamp when the message was read.
A reference to a recipient, either a user identifier (string) or an object reference (ID, collection).
Timestamp when the message was scheduled to be sent.
Timestamp when the message was seen.
The workflow that triggered the message.
The message delivery status.
The ID of the tenant associated with the message. Only present when a tenant is provided on a workflow trigger request.
The timestamp when the resource was last updated.
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
The typename of the schema.
The actor who performed the activity.
The workflow trigger data payload associated with the activity.
Unique identifier for the activity.
Timestamp when the activity was created.
A recipient of a notification, which is either a user or an object.
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
The typename of the schema.
The ID of the environment in which the message delivery occurred.
The unique identifier for the message delivery log.
Timestamp when the message delivery log was created.
A message delivery log request.
A message delivery log response.
The name of the service that processed the delivery.
MessageEvent
A message event. Occurs when a message delivery or engagement status changes.
Attributes
The typename of the schema.
The data associated with the message event. Only present for some event types.
The unique identifier for the message event.
Timestamp when the event was created.
A reference to a recipient, either a user identifier (string) or an object reference (ID, collection).
The type of event that occurred.
Channels
A Channel is a delivery method for a message.
Bulk
Bulk operations available for messages of a given channel.
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
Path parameters
The ID of the channel to update messages for.
The target status to be applied to the messages.
Request body
Limits the results to messages with the given archived status.
Limits the results to messages with the given delivery status.
Limits the results to messages with the given engagement status.
Limits the results to messages that have a tenant or not.
Limits the results to messages inserted after the given date.
Limits the results to messages inserted before the given date.
Limits the results to messages with the given recipient IDs.
Limits the results to messages with the given tenant IDs.
Limits the results to only messages that were generated with the given data. See trigger data filtering for more information.
Limits the results to messages with the given workflow keys.
Returns
A bulk operation entity.
Users
A User is an individual from your system, represented in Knock. They are most commonly a recipient of a notification.
Get user
Retrieve a specific user by their ID.
Endpoint
Path parameters
The ID of the user to retrieve.
Returns
List users
Retrieve a paginated list of users in the environment. Defaults to 50 users per page.
Endpoint
Query parameters
Associated resources to include in the response.
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page.
Returns
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
Path parameters
The ID for the user that you set when identifying them in Knock.
Request body
URL to the user's avatar image.
Channel-specific information that's needed to deliver a notification to an end provider.
The creation date of the user from your system.
The primary email address for the user.
The locale of the user. Used for message localization.
Display name of the user.
The E.164 phone number of the user (required for SMS channels).
A set of preferences for the user.
The timezone of the user. Must be a valid tz database time zone string. Used for recurring schedules.
Any additional custom properties.
Returns
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
Path parameters
The id of the user to merge into.
Request body
The user ID to merge from.
Returns
Delete user
List user messages
Returns a paginated list of messages for a specific user. Allows filtering by message status and provides various sorting options. Messages outside the account's retention window will not be included in the results.
Endpoint
Path parameters
The user ID to list messages for.
Query parameters
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page.
Limits the results to items with the corresponding tenant.
Limits the results to items with the corresponding channel ID.
Limits the results to messages with the given delivery status.
Limits the results to messages with the given engagement status.
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.
Limits the results to messages related to any of the provided categories.
Limits the results to messages triggered by the given workflow key.
Limits the results to messages associated with the top-level workflow run ID returned by the workflow trigger request.
Limits the results to messages for a specific recipient's workflow run.
Limits the results to only messages that were generated with the given data. See trigger data filtering for more information.
Limits the results to messages inserted after or on the given date.
Limits the results to messages inserted before or on the given date.
Limits the results to messages inserted after the given date.
Limits the results to messages inserted before the given date.
Returns
A paginated list of messages.
List user schedules
Returns a paginated list of schedules for a specific user, in descending order.
Endpoint
Path parameters
The user ID to list schedules for.
Query parameters
The workflow key to filter schedules for.
The tenant ID to filter schedules for.
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page.
Returns
A response containing a list of schedules.
List user subscriptions
Retrieves a paginated list of subscriptions for a specific user, in descending order.
Endpoint
Path parameters
The user ID to list subscriptions for.
Query parameters
Associated resources to include in the response.
Only returns subscriptions for the specified object GIDs.
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page.
Returns
A response containing a list of subscriptions.
List user preference sets
Get user preference set
Retrieves a specific preference set for a user identified by the preference set ID.
Endpoint
Path parameters
The ID for the user that you set when identifying them in Knock.
Unique identifier for the preference set.
Query parameters
The unique identifier for the tenant.
Returns
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. This is a destructive operation that will replace the existing preference set for the user.
Endpoint
Path parameters
The ID for the user that you set when identifying them in Knock.
Unique identifier for the preference set.
Request body
An object where the key is the category and the values are the preference settings for that category.
An object where the key is the channel type and the values are the preference settings for that channel type.
An object where the key is the workflow key and the values are the preference settings for that workflow.
Returns
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
Path parameters
The ID for the user that you set when identifying them in Knock.
The unique identifier for the channel.
Returns
Channel data for a given channel type.
Set channel data
Updates or creates channel data for a specific user and channel ID.
Endpoint
Path parameters
The ID for the user that you set when identifying them in Knock.
The unique identifier for the channel.
Request body
Channel data for a given channel type.
Returns
Channel data for a given channel type.
Unset channel data
Deletes channel data for a specific user and channel ID.
Endpoint
Path parameters
The ID for the user that you set when identifying them in Knock.
The unique identifier for the channel.
Returns
A 204 No Content response.
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
List feed items
Returns a paginated list of feed items for a user, including metadata about the feed.
Endpoint
Path parameters
The ID for the user that you set when identifying them in Knock.
The unique identifier for the channel.
Query parameters
The status of the feed items.
The source of the feed items.
The tenant associated with the feed items.
Whether the feed items have a tenant.
The workflow categories of the feed items.
The archived status of the feed items.
The trigger data of the feed items (as a JSON string).
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page.
Returns
A paginated list of feed items.
Get feed settings
Guides
A Guide is a collection of steps that can be used to guide a user through a workflow.
List guides
Returns a list of eligible in-app guides for a specific user and channel.
Endpoint
Path parameters
The ID for the user that you set when identifying them in Knock.
The unique identifier for the channel.
Query parameters
The tenant ID to use for targeting and rendering guides.
The data (JSON encoded object) to use for targeting and rendering guides.
The type of guides to filter by.
Returns
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
Path parameters
The ID for the user that you set when identifying them in Knock.
The unique identifier for the message.
Request body
The unique identifier for the channel.
The content of the guide.
The data of the guide.
The unique identifier for the guide.
The key of the guide.
The step reference of the guide.
Whether the guide is final.
The metadata of the guide.
The tenant ID of the guide.
Returns
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
Path parameters
The ID for the user that you set when identifying them in Knock.
The unique identifier for the message.
Request body
The unique identifier for the channel.
The content of the guide.
The data of the guide.
The unique identifier for the guide.
The key of the guide.
The step reference of the guide.
Whether the guide is final.
The metadata of the guide.
The tenant ID of the guide.
Returns
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
Path parameters
The ID for the user that you set when identifying them in Knock.
The unique identifier for the message.
Request body
The unique identifier for the channel.
The content of the guide.
The data of the guide.
The unique identifier for the guide.
The key of the guide.
The step reference of the guide.
Whether the guide is final.
The metadata of the guide.
The tenant ID of the guide.
Returns
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.
Bulk identify users
Identifies multiple users in a single operation. Allows creating or updating up to 100 users in a single batch with various properties, preferences, and channel data.
Endpoint
Request body
A list of users.
Returns
A bulk operation entity.
Bulk set preferences
Sets preferences for multiple users in a single operation. Supports either setting the same preferences for multiple users or specific preferences for each user.
Endpoint
Request body
A request to set a preference set for a recipient.
A list of user IDs.
Returns
A bulk operation entity.
Bulk delete users
Deletes multiple users in a single operation. Accepts up to 100 user IDs to delete and returns a bulk operation that can be queried for progress.
Endpoint
Request body
A list of user IDs.
Returns
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
The typename of the schema.
URL to the user's avatar image.
The creation date of the user from your system.
The primary email address for the user.
The ID for the user that you set when identifying them in Knock.
Display name of the user.
The E.164 phone number of the user (required for SMS channels).
The timezone of the user. Must be a valid tz database time zone string. Used for recurring schedules.
The timestamp when the resource was last updated.
Any additional custom properties.
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
URL to the user's avatar image.
Channel-specific information that's needed to deliver a notification to an end provider.
The creation date of the user from your system.
The primary email address for the user.
The locale of the user. Used for message localization.
Display name of the user.
The E.164 phone number of the user (required for SMS channels).
A set of preferences for the user.
The timezone of the user. Must be a valid tz database time zone string. Used for recurring schedules.
Any additional custom properties.
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
Channel-specific information that's needed to deliver a notification to an end provider.
The creation date of the user from your system.
The ID for the user that you set when identifying them in Knock.
A set of preferences for the user.
Any additional custom properties.
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.
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
Path parameters
The collection this object belongs to.
Unique identifier for the object.
Request body
A request to set channel data for a type of channel inline.
The locale of the object. Used for message localization.
Inline set preferences for a recipient, where the key is the preference set id.
The timezone of the object. Must be a valid tz database time zone string. Used for recurring schedules.
Any additional custom properties.
Returns
Get an object
Retrieves a specific object by its ID from the specified collection. Returns the object with all its properties.
Endpoint
Path parameters
The collection this object belongs to.
Unique identifier for the object.
Returns
List objects in a collection
Returns a paginated list of objects from the specified collection. Optionally includes preference data for the objects.
Endpoint
Path parameters
The collection this object belongs to.
Query parameters
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page.
Includes preferences of the objects in the response.
Returns
A paginated list of objects in a collection.
Delete an object
List preference sets
Returns a paginated list of preference sets for the specified object.
Endpoint
Path parameters
Unique identifier for the object.
The collection this object belongs to.
Returns
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
Path parameters
Unique identifier for the object.
The collection this object belongs to.
Unique identifier for the preference set.
Returns
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. This is a destructive operation and will replace any existing preferences with the preferences given. 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
Path parameters
Unique identifier for the object.
The collection this object belongs to.
Unique identifier for the preference set.
Request body
An object where the key is the category and the values are the preference settings for that category.
An object where the key is the channel type and the values are the preference settings for that channel type.
An object where the key is the workflow key and the values are the preference settings for that workflow.
Returns
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
Path parameters
The ID of the object to list schedules for.
The collection of the object to list schedules for.
Query parameters
Filter schedules by tenant id.
Filter schedules by workflow id.
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page.
Returns
A response containing a list of schedules.
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
Path parameters
The collection this object belongs to.
Unique identifier for the object.
Query parameters
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page.
Limits the results to items with the corresponding tenant.
Limits the results to items with the corresponding channel ID.
Limits the results to messages with the given delivery status.
Limits the results to messages with the given engagement status.
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.
Limits the results to messages related to any of the provided categories.
Limits the results to messages triggered by the given workflow key.
Limits the results to messages associated with the top-level workflow run ID returned by the workflow trigger request.
Limits the results to messages for a specific recipient's workflow run.
Limits the results to only messages that were generated with the given data. See trigger data filtering for more information.
Limits the results to messages inserted after or on the given date.
Limits the results to messages inserted before or on the given date.
Limits the results to messages inserted after the given date.
Limits the results to messages inserted before the given date.
Returns
A paginated list of messages.
Get channel data
Returns the channel data for the specified object and channel.
Endpoint
Path parameters
Unique identifier for the object.
The collection this object belongs to.
The unique identifier for the channel.
Returns
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
Path parameters
Unique identifier for the object.
The collection this object belongs to.
The unique identifier for the channel.
Request body
Channel data for a given channel type.
Returns
Channel data for a given channel type.
Unset channel data
Unsets the channel data for the specified object and channel.
Endpoint
Path parameters
Unique identifier for the object.
The collection this object belongs to.
The unique identifier for the channel.
Returns
A 204 No Content response.
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
Path parameters
Unique identifier for the object.
The collection this object belongs to.
Query parameters
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.
Additional fields to include in the response.
Recipients to filter by (only used if mode is object).
Objects to filter by (only used if mode is recipient).
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page.
Returns
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
Path parameters
Unique identifier for the object.
The collection this object belongs to.
Request body
The custom properties associated with the subscription relationship.
The recipients of the subscription. You can subscribe up to 100 recipients to an object at a time.
Returns
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
Path parameters
Unique identifier for the object.
The collection this object belongs to.
Request body
The recipients of the subscription. You can subscribe up to 100 recipients to an object at a time.
Returns
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.
Bulk set objects
Bulk sets up to 1,000 objects at a time in the specified collection.
Endpoint
Path parameters
The collection this object belongs to.
Request body
A list of objects.
Returns
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
Path parameters
The collection this object belongs to.
Request body
A list of subscriptions.
Returns
A bulk operation entity.
Bulk delete objects
Bulk deletes objects from the specified collection.
Endpoint
Path parameters
The collection this object belongs to.
Request body
List of object IDs to delete.
Returns
A bulk operation entity.
Object
A custom Object entity which belongs to a collection.
Attributes
The typename of the schema.
The collection this object belongs to.
Timestamp when the resource was created.
Unique identifier for the object.
The timestamp when the resource was last updated.
Any additional custom properties.
InlineIdentifyObjectRequest
A custom Object entity which belongs to a collection.
Attributes
An optional set of channel data for the object. This is a list of ChannelData objects.
The collection this object belongs to.
Timestamp when the resource was created.
Unique identifier for the object.
An optional set of preferences for the object.
Any additional custom properties.
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.
Delete a tenant
Get a tenant
Get a tenant by ID.
Endpoint
Path parameters
The unique identifier for the tenant.
Returns
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
Path parameters
The unique identifier for the tenant.
Request body
The channel data for the tenant.
The preferences for the tenant.
The settings for the tenant. Includes branding and preference set.
Any additional custom properties.
Returns
The response from setting a tenant.
List tenants
List tenants for the current environment.
Endpoint
Query parameters
Filter tenants by ID.
Filter tenants by name.
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page.
Returns
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.
Bulk delete tenants
Delete multiple tenants in a single operation. This operation cannot be undone.
Endpoint
Query parameters
The IDs of the tenants to delete.
Returns
A bulk operation entity.
Bulk set tenants
Set or update up to 1,000 tenants in a single operation.
Endpoint
Request body
The tenants to be upserted.
Returns
A bulk operation entity.
Tenant
A tenant entity.
Attributes
The typename of the schema.
The unique identifier for the tenant.
An optional name for the tenant.
The settings for the tenant. Includes branding and preference set.
Any additional custom properties.
TenantRequest
A tenant to be set in the system. You can supply any additional properties on the tenant object.
Attributes
The channel data for the tenant.
The unique identifier for the tenant.
The preferences for the tenant.
The settings for the tenant. Includes branding and preference set.
Any additional custom properties.
InlineTenantRequest
An request to set a tenant inline.
Attributes
An request to set a tenant inline.
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
Subscription
A subscription object.
Attributes
The typename of the schema.
Timestamp when the resource was created.
A custom Object entity which belongs to a collection.
The custom properties associated with the subscription relationship.
A recipient of a notification, which is either a user or an object.
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
An object where the key is the category and the values are the preference settings for that category.
An object where the key is the channel type and the values are the preference settings for that channel type.
Unique identifier for the preference set.
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
An object where the key is the category and the values are the preference settings for that category.
An object where the key is the channel type and the values are the preference settings for that channel type.
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.
Attributes
Any additional custom properties.
PreferenceSetChannelTypes
Channel type preferences.
Attributes
Whether the channel type is enabled for the preference set.
Whether the channel type is enabled for the preference set.
Whether the channel type is enabled for the preference set.
Whether the channel type is enabled for the preference set.
Whether the channel type is enabled for the preference set.
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
A list of conditions to apply to a channel type.
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. 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
The typename of the schema.
The unique identifier for the channel.
Channel data for a given channel type.
The type of provider.
ChannelDataRequest
A request to set channel data for a type of channel.
Attributes
Channel data for a given channel type.
PushChannelData
The content of a push notification.
Attributes
A list of push channel tokens.
SlackChannelData
Slack channel data
Attributes
List of Slack channel connections.
A Slack connection token.
MsTeamsChannelData
Microsoft Teams channel connection.
Attributes
List of Microsoft Teams connections.
Microsoft Teams tenant ID.
DiscordChannelData
Discord channel data.
Attributes
List of Discord channel connections.
OneSignalChannelData
OneSignal channel data.
Attributes
A list of OneSignal player IDs.
InlineChannelDataRequest
A request to set channel data for a type of channel inline.
Attributes
Any additional custom properties.
Recipient
A recipient of a notification, which is either a user or an object.
Attributes
A recipient of a notification, which is either a user or an object.
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
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.
RecipientReference
A reference to a recipient, either a user identifier (string) or an object reference (ID, collection).
Attributes
A reference to a recipient, either a user identifier (string) or an object reference (ID, collection).
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.
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
Request body
An optional map of data to pass into the workflow execution.
The ending date and time for the schedule.
The recipients to trigger the workflow for. Can inline identify users, objects, or use a list of user IDs. Limited to 1,000 recipients.
The repeat rule for the schedule.
The starting date and time for the schedule.
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.
The key of the workflow.
Returns
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
Query parameters
Filter by workflow key.
Filter by recipient IDs.
Filter by tenant ID.
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page.
Returns
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
Request body
A map of properties describing a user or an object to identify in Knock and mark as who or what performed the action.
An optional map of data to pass into the workflow execution.
The ending date and time for the schedule.
The repeat rule for the schedule.
A list of schedule IDs.
The starting date and time for the schedule.
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
A list of schedules.
Delete schedules
Bulk schedules
Bulk operations available for schedules.
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
Request body
A list of schedules.
Returns
A bulk operation entity.
Schedule
A schedule represents a recurring workflow execution.
Attributes
The typename of the schema.
A map of properties describing a user or an object to identify in Knock and mark as who or what performed the action.
An optional map of data to pass into the workflow execution.
Unique identifier for the schedule.
Timestamp when the resource was created.
The last occurrence of the schedule.
The next occurrence of the schedule.
A recipient of a notification, which is either a user or an object.
The repeat rule for the schedule.
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.
The timestamp when the resource was last updated.
The workflow the schedule is applied to.
ScheduleRepeatRule
The repeat rule for the schedule.
Attributes
The typename of the schema.
The day of the month to repeat the schedule.
The days of the week to repeat the schedule.
The frequency of the schedule.
The hour of the day to repeat the schedule.
The interval of the schedule.
The minute of the hour to repeat the schedule.
Audiences
Add members
List members
Remove members
AudienceMember
An audience member.
Attributes
The typename of the schema.
Timestamp when the resource was created.
The unique identifier for the tenant.
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.
The ID for the user that you set when identifying them in Knock.
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.
Get bulk operation
Retrieves a bulk operation (if it exists) and displays the current state of it.
Endpoint
Path parameters
The ID of the bulk operation to retrieve.
Returns
A bulk operation entity.
BulkOperation
A bulk operation entity.
Attributes
The typename of the schema.
Timestamp when the bulk operation was completed.
The number of failed operations.
A list of items that failed to be processed.
The estimated total number of rows to process.
Timestamp when the bulk operation failed.
Unique identifier for the bulk operation.
Timestamp when the resource was created.
The name of the bulk operation.
The number of rows processed so far.
The URI to the bulk operation's progress.
Timestamp when the bulk operation was started.
The status of the bulk operation.
The number of successful operations.
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.
List channels
List Slack channels for a Slack workspace.
Endpoint
Path parameters
The ID of the Knock Slack channel to get channels for.
Query parameters
A JSON encoded string containing the access token object reference.
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.
The maximum number of channels to return.
Set to true to exclude archived channels from the list.
Mix and match channel types by providing a comma-separated list of any combination of public_channel, private_channel, mpim, im.
Encoded team ID (T1234) to list channels in, required if org token is used.
Returns
The response from a Slack provider request, containing a list of channels.
Check auth
Check if a Slack channel is authenticated.
Endpoint
Path parameters
The ID of the Knock Slack channel to check.
Query parameters
A JSON encoded string containing the access token object reference.
Returns
The response from a Slack auth check request.
Revoke access
Revoke access for a Slack channel.
Endpoint
Path parameters
The ID of the Knock Slack channel to revoke access for.
Query parameters
A JSON encoded string containing the access token object reference.
Returns
A response indicating the operation was successful.
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.
List channels
List the Microsoft Teams channels within a team. By default, archived and private channels are excluded from the results.
Endpoint
Path parameters
The ID of the Knock Microsoft Teams channel to get channels for.
Query parameters
A JSON encoded string containing the Microsoft Teams tenant object reference.
Microsoft Teams team ID.
OData param passed to the Microsoft Graph API to filter channels.
OData param passed to the Microsoft Graph API to select specific properties.
Returns
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
Path parameters
The ID of the Knock Microsoft Teams channel to get teams for.
Query parameters
A JSON encoded string containing the Microsoft Teams tenant object reference.
OData param passed to the Microsoft Graph API to filter teams.
OData param passed to the Microsoft Graph API to select fields on a team.
OData param passed to the Microsoft Graph API to limit the number of teams returned.
OData param passed to the Microsoft Graph API to retrieve the next page of results.
Returns
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
Path parameters
The ID of the Knock Microsoft Teams channel to check.
Query parameters
A JSON encoded string containing the Microsoft Teams tenant object reference.
Returns
The response from a Microsoft Teams auth check request.
Revoke access
Remove a Microsoft Entra tenant ID from a Microsoft Teams tenant object.
Endpoint
Path parameters
The ID of the Knock Microsoft Teams channel to revoke access for.
Query parameters
A JSON encoded string containing the Microsoft Teams tenant object reference.
Returns
A response indicating the operation was successful.
Authentication error response
Shared
Resources that are shared across the API.
Condition
A condition to be evaluated.
Attributes
The argument value to compare against in the condition.
The operator to use in the condition evaluation.
The variable to be evaluated in the condition.
PageInfo
Pagination information for a list of resources.
Attributes
The typename of the schema.
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page.