API
Complete reference documentation for the Knock API.
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.
| Scale | Limit |
|---|---|
| Batch Tier 1 | 1 update / second / entity |
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
Rate limit
Tier 5Path 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.
This value allows you to track individual messages associated with this trigger request.
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
Rate limit
Tier 5Path 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
Rate limit
Tier 4Path parameters
The unique identifier for the message.
Returns
Represents a single message that was generated by a workflow for a given channel.
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 categories associated with the message.
The key of the workflow that triggered the message.
The ID of the version of 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.
Get message content
Returns the fully rendered contents of a message, where the response depends on which channel the message was sent through.
Endpoint
Rate limit
Tier 4Path parameters
The ID of the message to fetch contents of.
Returns
The content of a message.
The typename of the schema.
Content data specific to the channel type.
Timestamp when the message content was created.
The unique identifier for the message content.
List messages
Returns a paginated list of messages for the current environment.
Endpoint
Rate limit
Tier 4Query 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.
A list of messages.
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 categories associated with the message.
The key of the workflow that triggered the message.
The ID of the version of 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.
Pagination information for a list of resources.
The typename of the schema.
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page.
List events
Returns a paginated list of events for the specified message.
Endpoint
Rate limit
Tier 3Path 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.
A list of message events.
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.
Pagination information for a list of resources.
The typename of the schema.
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page.
List delivery logs
Returns a paginated list of delivery logs for the specified message.
Endpoint
Rate limit
Tier 3Path 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.
Returns a paginated list of delivery logs from the downstream provider for the specified message. For Knock in-app channels, the delivery logs will always be an empty list.
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.
The body content that was sent with the request.
The headers that were sent with the request.
The host to which the request was sent.
The HTTP method used for the request.
The path of the URL that was requested.
The query string of the URL that was requested.
A message delivery log response.
The body content that was received with the response.
The headers that were received with the response.
The HTTP status code of the response.
The name of the service that processed the delivery.
Pagination information for a list of resources.
The typename of the schema.
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page.
List activities
Returns a paginated list of activities for the specified message.
Endpoint
Rate limit
Tier 4Path 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.
A list of activities.
The typename of the schema.
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.
Pagination information for a list of resources.
The typename of the schema.
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page.
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
Rate limit
Tier 2Path parameters
The unique identifier for the message.
Returns
Represents a single message that was generated by a workflow for a given channel.
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 categories associated with the message.
The key of the workflow that triggered the message.
The ID of the version of 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.
Mark message as unseen
Marks a message as unseen. This reverses the seen state. Read more about message engagement statuses here.
Endpoint
Rate limit
Tier 2Path parameters
The unique identifier for the message.
Returns
Represents a single message that was generated by a workflow for a given channel.
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 categories associated with the message.
The key of the workflow that triggered the message.
The ID of the version of 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.
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
Rate limit
Tier 2Path parameters
The unique identifier for the message.
Returns
Represents a single message that was generated by a workflow for a given channel.
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 categories associated with the message.
The key of the workflow that triggered the message.
The ID of the version of 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.
Mark message as unread
Marks a message as unread. This reverses the read state. Read more about message engagement statuses here.
Endpoint
Rate limit
Tier 2Path parameters
The unique identifier for the message.
Returns
Represents a single message that was generated by a workflow for a given channel.
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 categories associated with the message.
The key of the workflow that triggered the message.
The ID of the version of 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.
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
Rate limit
Tier 2Path 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.
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 categories associated with the message.
The key of the workflow that triggered the message.
The ID of the version of 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.
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
Rate limit
Tier 2Path parameters
The unique identifier for the message.
Returns
Represents a single message that was generated by a workflow for a given channel.
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 categories associated with the message.
The key of the workflow that triggered the message.
The ID of the version of 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.
Unarchive message
Removes a message from the archived state, making it visible in the default message list in the feed again.
Endpoint
Rate limit
Tier 2Path parameters
The unique identifier for the message.
Returns
Represents a single message that was generated by a workflow for a given channel.
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 categories associated with the message.
The key of the workflow that triggered the message.
The ID of the version of 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.
Batch operations
Operations that can be performed on a batch of messages.
Batch get message contents
Get the contents of multiple messages in a single request.
Endpoint
Rate limit
Tier 4Query parameters
The IDs of the messages to fetch contents of.
Returns
A list of MessageContents
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
Rate limit
Tier 3Request 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
Rate limit
Tier 3Request body
The message IDs to update the status of.
Returns
The list of messages that were updated.
Mark messages as read
Mark messages as unread
Marks the given messages as unread. This reverses the read state. Read more about message engagement statuses here.
Endpoint
Rate limit
Tier 3Request 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
Rate limit
Tier 3Request 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
Rate limit
Tier 3Request 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
Rate limit
Tier 3Request 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
Rate limit
Tier 4Path 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.
A list of activities.
The typename of the schema.
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.
Pagination information for a list of resources.
The typename of the schema.
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page.
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 categories associated with the message.
The key of the workflow that triggered the message.
The ID of the version of 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 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.
The body content that was sent with the request.
The headers that were sent with the request.
The host to which the request was sent.
The HTTP method used for the request.
The path of the URL that was requested.
The query string of the URL that was requested.
A message delivery log response.
The body content that was received with the response.
The headers that were received with the response.
The HTTP status code of the 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
Rate limit
Tier 2Path 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.
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 collection this object belongs to.
Unique identifier for the object.
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.
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
Rate limit
Tier 4Path parameters
The ID of the user to retrieve.
Returns
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 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.
List users
Retrieve a paginated list of users in the environment. Defaults to 50 users per page.
Endpoint
Rate limit
Tier 4Query 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.
A list of users.
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.
Pagination information for a list of resources.
The typename of the schema.
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page.
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
Rate limit
Tier 3Path 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).
The timezone of the user. Must be a valid tz database time zone string. Used for recurring schedules.
Any additional custom properties.
Returns
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 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.
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
Rate limit
Tier 2Path parameters
The id of the user to merge into.
Request body
The user ID to merge from.
Returns
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 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.
Delete user
Permanently delete a user and all associated data.
Endpoint
Rate limit
Tier 2Path parameters
The ID of the user to delete.
Returns
A 204 No Content response.
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
Rate limit
Tier 4Path 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.
A list of messages.
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 categories associated with the message.
The key of the workflow that triggered the message.
The ID of the version of 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.
Pagination information for a list of resources.
The typename of the schema.
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page.
List user schedules
Returns a paginated list of schedules for a specific user, in descending order.
Endpoint
Rate limit
Tier 4Path 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.
A list of schedules.
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 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.
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.
Pagination information for a list of resources.
The typename of the schema.
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page.
List user subscriptions
Retrieves a paginated list of subscriptions for a specific user, in descending order.
Endpoint
Rate limit
Tier 4Path 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.
A list of subscriptions.
The typename of the schema.
Timestamp when the resource was created.
A custom Object entity which belongs to a collection.
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.
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.
Pagination information for a list of resources.
The typename of the schema.
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page.
List user preference sets
Retrieves a list of all preference sets for a specific user.
Endpoint
Rate limit
Tier 4Path parameters
The ID for the user that you set when identifying them in Knock.
Returns
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
Rate limit
Tier 4Path 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.
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.
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
Rate limit
Tier 3Path 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.
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.
Get channel data
Retrieves the channel data for a specific user and channel ID.
Endpoint
Rate limit
Tier 4Path 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.
The typename of the schema.
The unique identifier for the channel.
Channel data for a given channel type.
The type of provider.
Set channel data
Updates or creates channel data for a specific user and channel ID.
Endpoint
Rate limit
Tier 3Path 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.
The typename of the schema.
The unique identifier for the channel.
Channel data for a given channel type.
The type of provider.
Unset channel data
Deletes channel data for a specific user and channel ID.
Endpoint
Rate limit
Tier 3Path 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
Rate limit
Tier 2Path 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.
The list of feed items in the user's feed.
The typename of the schema.
List of activities associated with this feed item.
The typename of the schema.
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.
Timestamp when the feed item was archived.
Content blocks that make up the feed item.
Timestamp when the feed item was clicked.
Additional data associated with the feed item.
Unique identifier for the feed.
Timestamp when the resource was created.
Timestamp when the feed item was interacted with.
Timestamp when a link within the feed item was clicked.
Timestamp when the feed item was marked as read.
Timestamp when the feed item was marked as seen.
Source information for the feed item.
The typename of the schema.
Categories this workflow belongs to.
The key of the workflow.
The workflow version ID.
Tenant ID that the feed item belongs to.
Total number of activities related to this feed item.
Total number of actors related to this feed item.
The timestamp when the resource was last updated.
The metadata for the user's feed.
The typename of the schema.
The total number of feed items in the user's feed.
The number of unread feed items in the user's feed.
The number of unseen feed items in the user's feed.
Pagination information for a list of resources.
The typename of the schema.
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page.
Additional variables for the feed item.
Get feed settings
Returns the feed settings for a user.
Endpoint
Rate limit
Tier 4Path parameters
The ID for the user that you set when identifying them in Knock.
The unique identifier for the channel.
Returns
The response for the user's feed settings.
Features configuration for the user's feed.
Whether branding is required for the user's feed.
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
Rate limit
Tier 2Path 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.
A list of guides.
The content of the guide.
The unique identifier for the guide.
The metadata of the guide.
The title of the guide.
The recipient of the guide.
Mark guide as seen
Records that a guide has been seen by a user, triggering any associated seen events.
Endpoint
Rate limit
Tier 2Path 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.
The status of a guide's action.
Mark guide as interacted
Records that a user has interacted with a guide, triggering any associated interacted events.
Endpoint
Rate limit
Tier 2Path 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.
The status of a guide's action.
Mark guide as archived
Records that a guide has been archived by a user, triggering any associated archived events.
Endpoint
Rate limit
Tier 2Path 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.
The status of a guide's 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
Rate limit
Tier 1Request body
A list of users.
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 ID for the user that you set when identifying them in Knock.
Display name of the user.
The timezone of the user. Must be a valid tz database time zone string. Used for recurring schedules.
Returns
A bulk operation entity.
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 collection this object belongs to.
Unique identifier for the object.
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.
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
Rate limit
Tier 1Request body
A request to set a preference set for a recipient.
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.
A list of user IDs.
Returns
A bulk operation entity.
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 collection this object belongs to.
Unique identifier for the object.
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.
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
Rate limit
Tier 1Request body
A list of user IDs.
Returns
A bulk operation entity.
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 collection this object belongs to.
Unique identifier for the object.
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.
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).
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 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 timezone of the user. Must be a valid tz database time zone string. Used for recurring schedules.
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
Rate limit
Tier 3Path 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
A custom Object entity which belongs to a collection.
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.
Get an object
Retrieves a specific object by its ID from the specified collection. Returns the object with all its properties.
Endpoint
Rate limit
Tier 4Path parameters
The collection this object belongs to.
Unique identifier for the object.
Returns
A custom Object entity which belongs to a collection.
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.
List objects in a collection
Returns a paginated list of objects from the specified collection. Optionally includes preference data for the objects.
Endpoint
Rate limit
Tier 4Path 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.
A list of objects.
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.
Pagination information for a list of resources.
The typename of the schema.
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page.
Delete an object
Permanently removes an object from the specified collection. This operation cannot be undone.
Endpoint
Rate limit
Tier 3Path parameters
The collection this object belongs to.
Unique identifier for the object.
Returns
A 204 No Content response.
List preference sets
Returns a paginated list of preference sets for the specified object.
Endpoint
Rate limit
Tier 4Path 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
Rate limit
Tier 4Path 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.
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.
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
Rate limit
Tier 3Path 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.
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.
List object schedules
Returns a paginated list of schedules for an object.
Endpoint
Rate limit
Tier 4Path 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.
A list of schedules.
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 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.
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.
Pagination information for a list of resources.
The typename of the schema.
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page.
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
Rate limit
Tier 4Path 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.
A list of messages.
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 categories associated with the message.
The key of the workflow that triggered the message.
The ID of the version of 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.
Pagination information for a list of resources.
The typename of the schema.
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page.
Get channel data
Returns the channel data for the specified object and channel.
Endpoint
Rate limit
Tier 4Path 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.
The typename of the schema.
The unique identifier for the channel.
Channel data for a given channel type.
The type of provider.
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
Rate limit
Tier 3Path 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.
The typename of the schema.
The unique identifier for the channel.
Channel data for a given channel type.
The type of provider.
Unset channel data
Unsets the channel data for the specified object and channel.
Endpoint
Rate limit
Tier 3Path 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
Rate limit
Tier 4Path 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.
Objects to filter by (only used if mode is recipient).
The collection the recipient object belongs to.
An identifier for the recipient object.
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.
A list of subscriptions.
The typename of the schema.
Timestamp when the resource was created.
A custom Object entity which belongs to a collection.
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.
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.
Pagination information for a list of resources.
The typename of the schema.
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page.
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
Rate limit
Tier 3Path 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
Rate limit
Tier 3Path 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
Rate limit
Tier 1Path parameters
The collection this object belongs to.
Request body
A list of objects.
The collection this object belongs to.
Timestamp when the resource was created.
Unique identifier for the object.
Returns
A bulk operation entity.
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 collection this object belongs to.
Unique identifier for the object.
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.
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
Rate limit
Tier 1Path parameters
The collection this object belongs to.
Request body
A list of subscriptions.
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 bulk operation entity.
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 collection this object belongs to.
Unique identifier for the object.
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.
Bulk delete objects
Bulk deletes objects from the specified collection.
Endpoint
Rate limit
Tier 1Path parameters
The collection this object belongs to.
Request body
List of object IDs to delete.
Returns
A bulk operation entity.
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 collection this object belongs to.
Unique identifier for the object.
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.
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
The collection this object belongs to.
Timestamp when the resource was created.
Unique identifier 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
Delete a tenant and all associated data. This operation cannot be undone.
Endpoint
Rate limit
Tier 2Path parameters
The unique identifier for the tenant.
Returns
A 204 No Content response.
Get a tenant
Get a tenant by ID.
Endpoint
Rate limit
Tier 4Path parameters
The unique identifier for the tenant.
Returns
A tenant entity.
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.
The branding for the tenant.
The icon URL for the tenant. Must point to a valid image with an image MIME type.
The logo URL for the tenant. Must point to a valid image with an image MIME type.
The primary color for the tenant, provided as a hex value.
The primary color contrast for the tenant, provided as a hex value.
The preference set for the tenant. Used to override the default preference set.
Any additional custom properties.
Set a tenant
Sets a tenant within an environment, performing an upsert operation. Any existing properties will be merged with the incoming properties.
Endpoint
Rate limit
Tier 3Path parameters
The unique identifier for the tenant.
Request body
The settings for the tenant. Includes branding and preference set.
The branding for the tenant.
The icon URL for the tenant. Must point to a valid image with an image MIME type.
The logo URL for the tenant. Must point to a valid image with an image MIME type.
The primary color for the tenant, provided as a hex value.
The primary color contrast for the tenant, provided as a hex value.
The preference set for the tenant. Used to override the default preference set.
Any additional custom properties.
Returns
The response from setting a tenant.
List tenants
List tenants for the current environment.
Endpoint
Rate limit
Tier 4Query 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.
A list of tenants.
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.
The branding for the tenant.
The icon URL for the tenant. Must point to a valid image with an image MIME type.
The logo URL for the tenant. Must point to a valid image with an image MIME type.
The primary color for the tenant, provided as a hex value.
The primary color contrast for the tenant, provided as a hex value.
The preference set for the tenant. Used to override the default preference set.
Pagination information for a list of resources.
The typename of the schema.
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page.
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
Rate limit
Tier 1Query parameters
The IDs of the tenants to delete.
Returns
A bulk operation entity.
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 collection this object belongs to.
Unique identifier for the object.
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.
Bulk set tenants
Set or update up to 1,000 tenants in a single operation.
Endpoint
Rate limit
Tier 1Request body
Returns
A bulk operation entity.
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 collection this object belongs to.
Unique identifier for the object.
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.
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.
The branding for the tenant.
The icon URL for the tenant. Must point to a valid image with an image MIME type.
The logo URL for the tenant. Must point to a valid image with an image MIME type.
The primary color for the tenant, provided as a hex value.
The primary color contrast for the tenant, provided as a hex value.
The preference set for the tenant. Used to override the default 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 unique identifier for the tenant.
The settings for the tenant. Includes branding and preference set.
The branding for the tenant.
The icon URL for the tenant. Must point to a valid image with an image MIME type.
The logo URL for the tenant. Must point to a valid image with an image MIME type.
The primary color for the tenant, provided as a hex value.
The primary color contrast for the tenant, provided as a hex value.
The preference set for the tenant. Used to override the default 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 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.
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.
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.
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.
A Slack access 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
Rate limit
Tier 3Request 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 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.
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
Rate limit
Tier 4Query 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.
A list of schedules.
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 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.
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.
Pagination information for a list of resources.
The typename of the schema.
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page.
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
Rate limit
Tier 3Request 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.
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.
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
Permanently deletes one or more schedules identified by the provided schedule IDs. This operation cannot be undone.
Endpoint
Rate limit
Tier 3Request body
A list of schedule IDs.
Returns
A list of 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
Rate limit
Tier 1Request body
A list of schedules.
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.
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.
The repeat rule for the schedule.
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.
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 bulk operation entity.
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 collection this object belongs to.
Unique identifier for the object.
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.
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 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.
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
Adds one or more members to the specified audience.
Endpoint
Rate limit
Tier 3Path parameters
The key of the audience.
Request body
A list of audience members to add.
The unique identifier for the tenant.
An object containing the user's ID.
The ID for the user that you set when identifying them in Knock.
Returns
A 204 No Content response.
List members
Returns a paginated list of members for the specified audience.
Endpoint
Rate limit
Tier 4Path parameters
The key of the audience.
Returns
A paginated list of audience members.
A list of audience members.
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 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.
The ID for the user that you set when identifying them in Knock.
Pagination information for a list of resources.
The typename of the schema.
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page.
Remove members
Removes one or more members from the specified audience.
Endpoint
Rate limit
Tier 3Path parameters
The key of the audience.
Request body
A list of audience members to remove.
The unique identifier for the tenant.
An object containing the user's ID.
The ID for the user that you set when identifying them in Knock.
Returns
A 204 No Content response.
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 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.
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
Rate limit
Tier 4Path parameters
The ID of the bulk operation to retrieve.
Returns
A bulk operation entity.
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 collection this object belongs to.
Unique identifier for the object.
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.
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 collection this object belongs to.
Unique identifier for the object.
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
Rate limit
Tier 2Path 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.
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.
List of Slack channels.
The team ID that the Slack channel belongs to.
A Slack channel ID from the Slack provider.
Whether the Slack channel is an IM channel.
Whether the Slack channel is private.
Slack channel name.
Check auth
Check if a Slack channel is authenticated.
Endpoint
Rate limit
Tier 2Path 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.
A Slack connection object.
Whether the Slack connection is valid.
The reason for the Slack connection if it is not valid.
Revoke access
Revoke access for a Slack channel.
Endpoint
Rate limit
Tier 2Path 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.
OK response.
Authentication error response
The error code.
The error message.
The HTTP status code.
The error type.
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
Rate limit
Tier 2Path 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 of Microsoft Teams channels.
Microsoft Teams channel created date and time.
Microsoft Teams channel description.
Microsoft Teams channel name.
Microsoft Teams channel ID.
Whether the Microsoft Teams channel is archived.
Microsoft Teams channel membership type.
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
Rate limit
Tier 2Path 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.
List of Microsoft Teams teams.
Microsoft Teams team description.
Microsoft Teams team display name.
Microsoft Teams team ID.
OData param passed to the Microsoft Graph API to retrieve the next page of results.
Check auth
Check if a connection to Microsoft Teams has been authorized for a given Microsoft Teams tenant object.
Endpoint
Rate limit
Tier 2Path 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.
A Microsoft Teams connection object.
Whether the Microsoft Teams connection is valid.
The reason for the Microsoft Teams connection if it is not valid.
Revoke access
Remove a Microsoft Entra tenant ID from a Microsoft Teams tenant object.
Endpoint
Rate limit
Tier 2Path 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.
OK response.
Authentication error response
The error code.
The error message.
The HTTP status code.
The error type.
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.