API Reference

The Knock API enables you to add a complete notification engine to your product. This API provides programmatic access to integrating Knock via a REST-ful API.

Client libraries

Knock offers native SDKs in several popular programming languages:

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.

💡
Rate limit tiers are assigned per-endpoint. Knock does not have separate rate limit tiers for different accounts or pricing plans. Each endpoint in this reference has a rate limit tier label that indicates the scale of requests you can make to that endpoint.

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.

ScaleLimit
Tier 11 request / second
Tier 25 requests / second
Tier 360 requests / second
Tier 4200 requests / second
Tier 51,000 requests / second

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.

ScaleLimit
Batch Tier 11 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.

💡
The default idempotency window for the Knock API is 24 hours. If you're interested in configuring a different idempotency window for your account, please contact us at support@knock.app.
Supported endpoints
POST/workflows/:key/trigger

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

afterstringThe pagination cursor to fetch items after. Usually derived from the after cursor in `PageInfo`.
beforestringThe pagination cursor to fetch items before. Usually derived from the before cursor in `PageInfo`.
page_sizenumber (optional)A number between 1 and 50 that represents the number of items to return in the response. Defaults to 50.

Response format

entriesobject[]A list of items contained in this response
page_infoPageInfoMetadata about the page of data returned

PageInfo response details

afterstringThe cursor to use to fetch items after the last item in the list. May be null when there are no other items to retrieve.
beforestringThe cursor to use to fetch items before the first item in the list. May be null when there are no other items to retrieve.
page_sizenumberThe maximum number of items requested in the page
total_countnumberThe total number of items in this resource (up-to 10,000)

Errors

Knock uses standard HTTP response codes to indicate the success or failure of your API requests.

  • 2xx success status codes confirm that your request worked as expected.

  • 4xx error status codes indicate an error caused by incorrect or missing request information (e.g. providing an incorrect API key).

  • 5xx error status codes indicate a Knock server error.

Error codes

Here's a list of common

4xx

 error codes you may encounter while working with the Knock API. We also provide additional context on how to resolve them.
actor_missingYou called a workflow with an actor that has not yet been identified in Knock. To resolve, identify the actor prior to passing their ID in a workflow trigger.
api_key_expiredYour API key has expired. You can regenerate one on the developers page of the Knock dashboard.
api_key_missingThe API key you provided is invalid.
authentication_requiredThis endpoint requires authentication. Check the Authentication section of this API reference for more information.
channel_invalidThe channel you supplied in this request is invalid. A common cause of this error is that the channel you're referencing has not yet been configured in the current environment.
incorrect_token_typeYou cannot call this endpoint with this token.
invalid_paramsThe parameters supplied in your request were invalid. Check the payload you're sending to Knock to make sure it's valid.
invalid_user_tokenThe user token supplied is invalid.
missing_jwt_signing_key

Your request needs a JWT signing key. You can learn more about JWT signing keys in our client authentication docs.

missing_user_token

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.

workflow_inactive

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.

workflow_missingThe workflow you attempted to invoke could not be found. To resolve this error, confirm that you're calling the correct environment and that your workflow has been committed to it.

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, digest—you want applied to the messages prior to delivery. A workflow is triggered by a trigger call, usually when something occurs in your product that you want your users to know about (e.g. a new comment.)

Endpoints
POST/workflows/:key/trigger
POST/workflows/:key/cancel

Idempotent
Triggering a workflow

Invokes the workflow with the given key for the given set of recipients. Each recipient will have a workflow run triggered for them against the latest committed version of the workflow in the environment.

Read more about triggering a workflow.

This endpoint will return errors in the following cases:

  • The workflow does not exist, or has not been committed to the environment
  • The workflow's status is set to inactive
  • The trigger data does not match the schema defined for the workflow (learn more)

Endpoint

POST/workflows/:key/trigger

Rate limit

Tier 5

Payload size limit

The workflow trigger endpoint enforces the following payload size limits:

  • The data payload must be no more than 10MB
  • The recipients list must not exceed 1000 entries

Path parameters

keystringThe key of the workflow to call

Body parameters

recipientsRecipientIdentifier[] (required)A list of user identifiers, object references, or inline recipient definitions to run this workflow for
actorRecipientIdentifier (optional)An identifier of who or what performed this action
cancellation_keystring (optional)The key to use for canceling the workflow
tenantstring (optional)The id of the tenant that this workflow run should be associated with
dataobject (optional)A set of key-value pairs to pass to the workflow trigger

Returns

workflow_run_idstringA unique UUID of this workflow run

Triggering a workflow with inline identifications

In the recipients and actor fields in a trigger call, you can optionally include maps of properties describing a user or an object. These can be properties describing a brand new user/object, or properties describing an update to an existing one. When this data is present in a workflow trigger, Knock will persist it as part of processing the workflow. This is comparable to direct calls to the identify user or set object APIs.

Each recipient and actor must have an id field set in addition to other properties (e.g. email, name, or phone number).

See our guides on inline identification for users and for objects for more details on this use case.

Endpoint

POST/workflows/:key/trigger

Rate limit

Tier 5

Payload size limit

The workflow trigger endpoint enforces the following payload size limits:

  • The data payload must be no more than 10MB
  • The recipients list must not exceed 1000 entries

Path parameters

keystringThe key of the workflow to call

Body parameters

recipientsRecipient[] (required)A list of maps of properties describing a user or an object to identify in Knock and trigger this workflow for
actorRecipient (optional)A map of properties describing a user or an object to identify in Knock and mark as who or what performed the action
cancellation_keystring (optional)The key to use for canceling the workflow
tenantstring (optional)The id of the tenant that this workflow run should be associated with
dataobject (optional)A set of key-value pairs to pass to the trigger call

Returns

workflow_run_idstringA unique UUID of this workflow run

Canceling workflows

Cancel a delayed workflow for one or more recipients.

Read more about canceling workflows.

Endpoint

POST/workflows/:key/cancel

Rate limit

Tier 5

Payload size limit

The workflow cancellation endpoint enforces the following payload size limits:

  • The recipients list must not exceed 1000 entries

Path parameters

keystringThe key of the workflow

Body parameters

cancellation_keystringThe cancellation key unique to the trigger call
recipientsRecipientIdentifier[]An optional list of user ids or object references to cancel the workflow for

Returns

204, with empty content.

Messages

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

Attributes

idstringThe unique ID of this message
channel_idstringThe ID of the channel through which this message was delivered
recipientRecipientIdentifierThe ID of the user who received the message. If the recipient is an object, the result will be an object containing its id and collection
actorsRecipientIdentifier[]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.
workflowstringThe key of the workflow that this message was generated from
tenantstringThe ID of the tenant that this message belongs to
statusstringThe delivery status for the message. One of `queued`, `sent`, `delivered`, `delivery_attempted`, `undelivered`, `not_sent`, `bounced`.
engagement_statusesstring[]One or more engagement statuses for the message. Each engagement status can be one of `seen`, `read`, `interacted`, `link_clicked`, or `archived`.
seen_atstring (optional)When the message was last seen
read_atstring (optional)When the message was last read
interacted_atstring (optional)When the message was last interacted with
link_clicked_atstring (optional)When a message link was last clicked
archived_atstring (optional)When the message was archived
inserted_atstringWhen the message was created
updated_atstringWhen the message was last updated
sourceobjectThe workflow which is the message source
dataobjectData from the activities linked to the message
Endpoints
GET/messages
GET/messages/:id
GET/messages/:id/events
GET/messages/:id/activities
GET/messages/:id/content
GET/messages/batch/content
GET/messages/:id/delivery_logs
PUT/messages/:id/:status
DELETE/messages/:id/:status
POST/messages/batch/:status
POST/channels/:id/messages/bulk/:status

Retention policy applied
Listing messages

Returns a paginated list of messages.

Endpoint

GET/messages

Rate limit

Tier 4

Data retention rule

Messages outside the account's retention window will not be included in the results.

Query parameters

page_sizenumberThe total number to retrieve per page (defaults to 50)
afterstringThe cursor to retrieve items after (hint: use the `__cursor` field)
beforestringThe cursor to retrieve items before (hint: use the `__cursor` field)
sourcestring (optional)Limits the results to only items of the source workflow
tenantstring (optional)Limits the results to items with the corresponding tenant, or where the tenant is empty
statusstring[] (optional)One or more of `queued`, `sent`, `delivered`, `delivery_attempted`, `undelivered`, `bounced`, `not_sent`. Limits results to messages with the given delivery status(es).
engagement_statusstring[] (optional)One or more of `read`, `unread`, `seen`, `unseen`, `archived`, `unarchived`, `interacted`, `link_clicked`. Limits results to messages with the given engagement status(es).
channel_idstring (optional)Limits the results to only items that belong to the channel
message_ids[]string[] (optional)Limits the results to only the message ids given (max 50). Note: when using this option, the results will be subject to any other filters applied to the query.
workflow_categoriesstring[] (optional)Limits the results to only items related to any of the provided categories
workflow_run_idstring (optional)Limits the results to messages triggered by the top-level workflow run ID
workflow_recipient_run_idstring (optional)Limits the results to messages for a specific recipient's workflow run
trigger_dataJSON string (optional)Limits the results to only items that were generated with the given data
inserted_at.gtdatetime (optional)Retrieves messages inserted after the given date
inserted_at.gtedatetime (optional)Retrieves messages inserted after or equal to the given date
inserted_at.ltdatetime (optional)Retrieves messages inserted before the given date
inserted_at.ltedatetime (optional)Retrieves messages inserted before or equal to the given date

Returns

A paginated list of Message records

Retention policy applied
Fetching a message

Retrieve a message by the id.

Endpoint

GET/messages/:id

Rate limit

Tier 4

Data retention rule

Returns a 404 Not Found error for a message outside the account's retention window.

Path parameters

idstringThe ID of the message

Returns

A Message

Retention policy applied
Events

Returns a paginated list of events for a message.

Endpoint

GET/messages/:id/events

Rate limit

Tier 3

Data retention rule

Returns a 404 Not Found error for a message outside the account's retention window.

Path parameters

idstringThe ID of the message

Query parameters

page_sizenumberThe total number to retrieve per page (defaults to 50)
afterstringThe cursor to retrieve items after (hint: use the `__cursor` field)
beforestringThe cursor to retrieve items before (hint: use the `__cursor` field)

Returns

A paginated list of MessageEvent records

Retention policy applied
Activities

Returns a paginated list of activities associated with the message. Note: for non batched messages this will always return a single activity. For messages produced after a batch step, this will contain one or more activities.

Endpoint

GET/messages/:id/activities

Rate limit

Tier 4

Data retention rule

Returns a 404 Not Found error for a message outside the account's retention window.

Path parameters

idstringThe ID of the message

Query parameters

page_sizenumberThe total number to retrieve per page (defaults to 50)
afterstringThe cursor to retrieve items after (hint: use the `__cursor` field)
beforestringThe cursor to retrieve items before (hint: use the `__cursor` field)
trigger_dataJSON string (optional)Limits the results to only items that were generated with the given data

Returns

A paginated list of Activity records

Retention policy applied
Message content

Retrieves the contents of a message, as generated and sent to the end provider.

Endpoint

GET/messages/:id/content

Rate limit

Tier 3

Data retention rule

Returns a 404 Not Found error for a message outside the account's retention window.

Path parameters

idstringThe ID of the message

Returns

A MessageContent object.

Note: the data attribute of the MessageContent payload will vary based on the type of message being sent (email, chat, in-app feed, sms, and push).

Retention policy applied
Batch message content

Retrieves the contents of a list of messages, as generated and sent to the end provider.

Endpoint

GET/messages/batch/content

Rate limit

Tier 4

Data retention rule

Returns a 404 Not Found error for a message outside the account's retention window.

Query parameters

message_ids[]string[]The IDs of the messages (max 25)

Returns

A list of MessageContent objects for the provided message IDs.

Note: the data attribute of the MessageContent payload will vary based on the type of message being sent (email, chat, in-app feed, sms, and push).

Retention policy applied
Delivery logs

Retrieves the delivery logs of a message, generated while sending and checking the delivery status of the message sent to an end provider. Note: for in-app channels, the delivery logs will always be an empty list.

Endpoint

GET/messages/:id/delivery_logs

Rate limit

Tier 3

Data retention rule

Returns a 404 Not Found error for a message outside the account's retention window.

Path parameters

idstringThe ID of the message

Query parameters

page_sizenumberThe total number to retrieve per page (defaults to 50)
afterstringThe cursor to retrieve items after
beforestringThe cursor to retrieve items before

Returns

A paginated list of MessageDeliveryLog.

Note: the request and response attributes of the MessageDeliveryLog payload will vary depending on the provider.

Updating a message status

Marks the given message with the provided status, recording an event in the process. Note that message engagement statuses are mutually inclusive; a message can have zero, one, or multiple statuses.

Endpoint

PUT/messages/:id/:status

Rate limit

Tier 2

Path parameters

idstringThe ID of the message
statusenumOne of `seen`, `read`, `interacted`, `archived`
metadataobjectAdditional metadata to be set. Only applicable for `interacted` status updates. Cannot include more than 5 key-value pairs, must not contain nested data.

Returns

A Message.

Undoing a message status change

Un-marks the given status on a message, recording an event in the process. Note that message engagement statuses are mutually inclusive; a message can have zero, one, or multiple statuses.

Endpoint

DELETE/messages/:id/:status

Rate limit

Tier 2

Path parameters

idstringThe ID of the message
statusenumOne of `seen`, `read`, `interacted`, `archived`

Returns

A Message.

Batch changing message statuses

Multiple messages can be changed at once using the batch API, where all message ids given in will have their statuses changed.

Endpoint

POST/messages/batch/:status

Rate limit

Tier 3

Batch rate limit

Batch Tier 1
⚠️
Knock scopes this batch rate limit by message_ids and status. This allows for 1 update per second per message per status.

Path parameters

statusenumOne of `seen`, `read`, `interacted`, `archived` or `unseen`, `unread`, `unarchived`

Body parameters

message_idsstring[]A list of one or more message IDs
metadataobjectAdditional metadata to be set for all messages in the batch. Only applicable for `interacted` status updates. Cannot include more than 5 key-value pairs, must not contain nested data.

Returns

A list of Messages that were mutated during the call.

Retention policy applied
Bulk changing message statuses in a channel

Apply the given status to a set of messages for the given channel. Will modify all valid messages, or a subset based on the filters provided.

Returns a BulkOperation that executes the job asynchronously. Progress can be tracked via the BulkOperation API.

Endpoint

POST/channels/:id/messages/bulk/:status

Rate limit

Tier 2

Data retention rule

For in-app channels, messages can be updated indefinitely via this operation. For all other channel types, messages outside the account's retention window will not be updated as part of this operation.

Path parameters

idstringThe ID of a channel that you wish to modify messages under
statusenumOne of `seen`, `read`, `interacted`, `archived` or `unseen`, `unread`, `unarchived`

Body parameters

user_idsstring[] (optional)Scope the bulk update to one or more users
tenantsstring[] (optional)A list of one or more tenants to match
has_tenantboolean (optional)When set to false, will only return messages that do not have a tenant associated
workflowsstring[] (optional)A list of one or more workflow keys to match
older_thanstring (optional)An ISO-8601 timestamp to find messages created before
newer_thanstring (optional)An ISO-8601 timestamp to find messages created after
delivery_statusenum (optional)Limit messages to one of `queued`, `sent`, `delivered`, `delivery_attempted`, `undelivered`, `bounced`, `not_sent`
engagement_statusenum (optional)Limit messages to one of `seen`, `unseen`, `read`, `unread`, `archived`, `unarchived`, `interacted`, `link_clicked`

Returns

A BulkOperation

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

Attributes

entriesFeedItem[]An ordered list of feed items (most recent first)
page_infoPageInfoPagination information for the items returned
varsobjectEnvironment specific account variables
metaFeedMetadataInformation about the total unread and unseen items
Endpoints
GET/users/:user_id/feeds/:feed_id

Get a feed for user

Retrieves a feed of items in reverse chronological order for a given user_id on the given feed_id. In the case where the user has not yet been identified within Knock, this endpoint will return an empty feed.

You can customize the response for this endpoint by using response filters to exclude or only include certain properties on your resources.

Note: if you're making this call from a client-side environment you should be using your publishable key along with a user token to make this request

Endpoint

GET/users/:user_id/feeds/:feed_id

Rate limit

Tier 2
⚠️
This endpoint's rate limit is always scoped per-user and per-environment. This is true even for requests made without a signed user token.

Path parameters

user_idstringThe ID of the user
feed_idstringThe ID of the feed (the channel ID)

Query parameters

page_sizenumberThe total number to retrieve per page. Defaults to 50 and the max limit is 200.
afterstringThe cursor to retrieve items after (hint: use the `__cursor` field)
beforestringThe cursor to retrieve items before (hint: use the `__cursor` field)
sourcestringLimits the feed to only items of the source workflow
tenantstringLimits the feed to only display items with the corresponding tenant, or where the tenant is empty
has_tenantbooleanScope the feed to display items with or without any tenancy
statusstringOne of `unread`,`read`, `unseen`,`seen`, `all`
workflow_categoriesstring[]Limits the feed to only display items related to any of the provided categories
archivedstringOne of `include`, `exclude`, `only` (defaults to `exclude`)
trigger_dataJSON stringLimits the results to only items that were generated with the given data
inserted_at.gtdatetime (optional)Filter feed items created after the specified ISO-8601 timestamp (exclusive)
inserted_at.gtedatetime (optional)Filter feed items created at or after the specified ISO-8601 timestamp (inclusive)
inserted_at.ltdatetime (optional)Filter feed items created before the specified ISO-8601 timestamp (exclusive)
inserted_at.ltedatetime (optional)Filter feed items created at or before the specified ISO-8601 timestamp (inclusive)

Returns

A feed response.

Users

A user represents an individual who may need to receive a notification from Knock. They are always referenced by your internal identifier.

Attributes

idstringUnique identifier for the user
namestring (optional)The full name of the user
emailstring (optional)The email of the user
avatarstring (optional)A URL for the avatar of the user
phone_numberstring (optional)The phone number of the user to use with SMS channels
localestring (optional)The locale of the user. Used for message localization.
timezonestring (optional)The timezone of the user. Must be a valid tz database time zone string. Used for recurring schedules and send windows.
*key-value pairsAny custom properties
Endpoints
PUT/users/:user_id
GET/users
GET/users/:user_id
GET/users/:user_id/messages
DELETE/users/:user_id
POST/users/:user_id/merge
POST/users/bulk/identify
POST/users/bulk/delete

Identify a user

Identifying a user will create or update a user in Knock, merging the properties given with what we currently have set on the user (if any).

Endpoint

PUT/users/:user_id

Rate limit

Tier 3

Path parameters

idstringUnique identifier of the user

Body parameters

namestring (optional)The name of the user
emailstring (optional)The email of the user
avatarstring (optional)A URL for the avatar of the user
phone_numberstring (optional)The phone number of the user to use with SMS channels
localestring (optional)The locale of the user. Used for message localization.
timezonestring (optional)The timezone of the user. Must be a valid tz database time zone string. Used for recurring schedules.
preferencesobject<string, PreferenceSet> (optional)A set of preferences that determines whether a recipient should receive a particular type of notification.
channel_dataobject<string, ChannelData> (optional)Channel-specific information that's needed to deliver a notification to an end provider.
*key-value pairsAny custom properties

Returns

A User.

List users

Lists all non-deleted users for the environment. You can optionally request all preferences associated with a user while listing by passing include[]=preferences.

Endpoint

GET/users

Rate limit

Tier 4

Query parameters

page_sizenumberThe total number to retrieve per page (defaults to 50)
afterstringThe cursor to retrieve items after (hint: use the `__cursor` field)
beforestringThe cursor to retrieve items before (hint: use the `__cursor` field)
includestring[]A list of entities to side load as part of the response. Currently only supports `preferences`.

Returns

A paginated list of User records.

Get a user

Retrieve a user by their ID, including all properties previously set.

Endpoint

GET/users/:user_id

Rate limit

Tier 4

Path parameters

idstringUnique identifier of the user

Returns

A User.

Retention policy applied
User messages

Retrieve a paginated list of messages for a user. Will return most recent messages first.

Endpoint

GET/users/:id/messages

Rate limit

Tier 4

Data retention rule

Messages outside the account's retention window will not be included in the results.

Path parameters

idstringThe ID of the user

Query parameters

page_sizenumberThe total number to retrieve per page (defaults to 50)
afterstringThe cursor to retrieve items after (hint: use the `__cursor` field)
beforestringThe cursor to retrieve items before (hint: use the `__cursor` field)
sourcestring (optional)Limits the results to only items of the source workflow
tenantstring (optional)Limits the results to items with the corresponding tenant, or where the tenant is empty
statusstring[] (optional)One or more of `queued`, `sent`, `delivered`, `delivery_attempted`, `undelivered`, `bounced`, `not_sent`. Limits results to messages with the given delivery status(es).
engagement_statusstring[] (optional)One or more of `read`, `unread`, `seen`, `unseen`, `archived`, `unarchived`, `interacted`, `link_clicked`. Limits results to messages with the given engagement status(es).
channel_idstring (optional)Limits the results to only items that belong to the channel
message_ids[]string[] (optional)Limits the results to only the message ids given (max 50). Note: when using this option, the results will be subject to any other filters applied to the query.
workflow_categoriesstring[] (optional)Limits the results to only items related to any of the provided categories
trigger_dataJSON string (optional)Limits the results to only items that were generated with the given data
inserted_at.gtdatetime (optional)Retrieves messages inserted after the given date
inserted_at.gtedatetime (optional)Retrieves messages inserted after or equal to the given date
inserted_at.ltdatetime (optional)Retrieves messages inserted before the given date
inserted_at.ltedatetime (optional)Retrieves messages inserted before or equal to the given date

Returns

A paginated list of Message records

Delete a user

Deletes a user by the id given.

Endpoint

DELETE/users/:user_id

Rate limit

Tier 2

Path parameters

idstringUnique identifier of the user

Returns

No response.

Merge users

Merges the two users together, merging the user specified in the from_user_id into the user_id.

Read more on how merging works →

Endpoint

POST/users/:user_id/merge

Rate limit

Tier 2

Path parameters

idstringUnique identifier of the user to merge into

Body parameters

from_user_idstringUnique identifier of the user to merge from

Returns

The merged User.

Bulk identify users

Identifies up to 1000 users at a time. Returns a BulkOperation that executes the job asynchronously. Progress can be tracked via the BulkOperation API.

Endpoint

POST/users/bulk/identify

Rate limit

Tier 1

Body parameters

usersUser[]A list of users to upsert

Returns

A BulkOperation.

Bulk delete users

Deletes up to 1000 users at a time. Returns a BulkOperation that executes the job asynchronously. Progress can be tracked via the BulkOperation API.

Endpoint

POST/users/bulk/delete

Rate limit

Tier 1

Body parameters

user_idsstring[]Unique identifiers of the users to delete

Returns

A BulkOperation.

Objects

An Object represents a resource in your system that you've stored in Knock.

The most common use case for objects is as a store for non-user channel data when sending Slack notifications.

Attributes

collectionstringThe type of object you are storing in Knock.
idstringA unique identifier for the object within the collection.
localestring (optional)The locale of the object. Used for message localization.
timezonestring (optional)The timezone of the object. Must be a valid tz database time zone string. Used for recurring schedules and send windows.
propertiesobjectAn object of key-value pairs for attributes you want to associate with the object. Each collection has its own schema in Knock as defined by these properties.
Endpoints
GET/objects/:collection
GET/objects/:collection/:id
GET/objects/:collection/:id/messages
PUT/objects/:collection/:id
DELETE/objects/:collection/:id
POST/objects/:collection/bulk/set
POST/objects/:collection/bulk/delete

List objects

Lists all objects under a collection. Note: does not validate that the collection exists and contains objects. You can optionally request all preferences associated with an object while listing by passing include[]=preferences.

Endpoint

GET/objects/:collection

Rate limit

Tier 4

Path parameters

collectionstringThe type of object you are storing in Knock.

Query parameters

page_sizenumberThe total number to retrieve per page (defaults to 50)
afterstringThe cursor to retrieve items after (hint: use the `__cursor` field)
beforestringThe cursor to retrieve items before (hint: use the `__cursor` field)
includestring[]A list of entities to side load as part of the response. Currently only supports `preferences`.

Response

Returns a paginated list of Object records.

Get an object

Retrieve an object in a collection by the id.

Endpoint

GET/objects/:collection/:id

Rate limit

Tier 4

Path parameters

collectionstringThe type of object you are storing in Knock.
idstringA unique identifier for the object within the collection.

Response

Returns an Object.

Retention policy applied
Object messages

Returns a paginated list of messages for an object. Will return newest messages first.

Endpoint

GET/objects/:collection/:id/messages

Rate limit

Tier 4

Data retention rule

Messages outside the account's retention window will not be included in the results.

Path parameters

collectionstringThe collection of the object
idstringThe ID of the object

Query parameters

page_sizenumberThe total number to retrieve per page (defaults to 50)
afterstringThe cursor to retrieve items after (hint: use the `__cursor` field)
beforestringThe cursor to retrieve items before (hint: use the `__cursor` field)
sourcestring (optional)Limits the results to only items of the source workflow
tenantstring (optional)Limits the results to items with the corresponding tenant, or where the tenant is empty
statusstring[] (optional)One or more of `queued`, `sent`, `delivered`, `delivery_attempted`, `undelivered`, `bounced`, `not_sent`. Limits results to messages with the given delivery status(es).
engagement_statusstring[] (optional)One or more of `read`, `unread`, `seen`, `unseen`, `archived`, `unarchived`, `interacted`, `link_clicked`. Limits results to messages with the given engagement status(es).
channel_idstring (optional)Limits the results to only items that belong to the channel
message_ids[]string[] (optional)Limits the results to only the message ids given (max 50). Note: when using this option, the results will be subject to any other filters applied to the query.
workflow_categoriesstring[] (optional)Limits the results to only items related to any of the provided categories
trigger_dataJSON string (optional)Limits the results to only items that were generated with the given data
inserted_at.gtdatetime (optional)Retrieves messages inserted after the given date
inserted_at.gtedatetime (optional)Retrieves messages inserted after or equal to the given date
inserted_at.ltdatetime (optional)Retrieves messages inserted before the given date
inserted_at.ltedatetime (optional)Retrieves messages inserted before or equal to the given date

Returns

A paginated list of Message records

Set an object

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

Endpoint

PUT/objects/:collection/:id

Rate limit

Tier 3

Path parameters

collectionstringThe type of object you are storing in Knock.
idstringA unique identifier for the object within the collection.

Body parameters

localestring (optional)The locale of the object. Used for message localization.
timezonestring (optional)The timezone of the object. Must be a valid tz database time zone string. Used for recurring schedules and send windows.
preferencesobject<string, PreferenceSet> (optional)A set of preferences that determines whether a recipient should receive a particular type of notification.
channel_dataobject<string, ChannelData> (optional)Channel-specific information that's needed to deliver a notification to an end provider.
*anyA collection of key value pairs to set as properties for this object.

Response

Returns an Object.

Delete an object

Deletes an object from a collection by the id provided.

Endpoint

DELETE/objects/:collection/:id

Rate limit

Tier 2

Path parameters

collectionstringThe type of object you are storing in Knock.
idstringA unique identifier for the object within the collection.

Response

No response.

Bulk set objects in a collection

Bulk sets up to 1000 objects at a time within a collection. Returns a BulkOperation that executes the job asynchronously. Progress can be tracked via the BulkOperation API.

Endpoint

POST/objects/:collection/bulk/set

Rate limit

Tier 1

Path parameters

collectionstringThe type of object you are storing in Knock.

Body parameters

objects[].idstringThe id of the object to set.
objects[].*anyKey value pairs to set as properties on this object.

Response

Returns a BulkOperation.

Bulk delete objects in a collection

Bulk deletes up to 1000 objects at a time within a collection. Returns a BulkOperation that executes the job asynchronously. Progress can be tracked via the BulkOperation API.

Endpoint

POST/objects/:collection/bulk/delete

Rate limit

Tier 1

Path parameters

collectionstringThe type of object you are storing in Knock.

Body parameters

object_idsstring[]The ids of the objects to delete within the collection

Response

Returns a BulkOperation.

Subscriptions

A subscription represents the relationship between a recipient (the subscriber) and an object.

Attributes

propertiesobjectAn object of key-value pairs for attributes you want to associate with the subscription.
recipientobjectA user or an object associated with this subscription
Endpoints
GET/objects/:collection/:id/subscriptions
GET/users/:id/subscriptions
POST/objects/:collection/:id/subscriptions
POST/objects/:collection/bulk/subscriptions/add
DELETE/objects/:collection/:id/subscriptions

List subscriptions

Lists all subscriptions to an object (the subscribers) or all of the current subscriptions for which the specified object is a recipient, depending on the mode given. Defaults to returning subscriber information.

Will return the underlying recipient attached. Note: the object must exist.

Endpoint

GET/objects/:collection/:id/subscriptions

Rate limit

Tier 4

Path parameters

collectionstringA collection that the object belongs to
idstringThe unique identifier of the object in the collection

Query parameters

page_sizenumberThe total number to retrieve per page (defaults to 50)
afterstringThe cursor to retrieve items after
beforestringThe cursor to retrieve items before
modestringWhen set to "recipient" will return all of the active subscriptions for which the specified object is a recipient (as a subscriber to other objects), rather than the subscribers of the specified object.
objectsobject<string, ObjectRef>A collection of ObjectRefs, containing the object collection and id, to filter subscriptions. Filtering by objects will only be enabled when mode is set to "recipient."
recipientsstring[] | object<string, RecipientRef>A collection of recipient identifiers (user_ids and/or ObjectRefs) to filter subscribers of the object. Filtering by recipients will only be enabled when mode is not set.

Response

A paginated list response

User subscriptions

Returns a paginated list of subscriptions for a single user, in descending order.

Endpoint

GET/users/:id/subscriptions

Rate limit

Tier 4

Path parameters

idstringThe unique identifier of the User

Query parameters

page_sizenumberThe total number to retrieve per page (defaults to 50)
afterstringThe cursor to retrieve items after (hint: use the `__cursor` field)
beforestringThe cursor to retrieve items before (hint: use the `__cursor` field)
objectsobject<string, ObjectRef>A collection of ObjectRefs, containing the object collection and id, to filter subscriptions.

Response

A paginated response containing a list of Subscription entities.

Add subscriptions

Adds one or more recipients as subscribers to the object by creating subscriptions.

Endpoint

POST/objects/:collection/:id/subscriptions

Rate limit

Tier 3

Path parameters

collectionstringA collection that the object belongs to
idstringThe unique identifier of the object in the collection

Body parameters

recipientsRecipientIdentifier[]A list of recipient identifiers. You can subscribe up to 100 recipients to an object at a time.
propertiesmap (optional)An optional set of key-value pairs to associate with the subscriptions

Response

A list of created ObjectSubscription

Bulk add subscriptions

Creates subscriptions for one or more recipients to one or more objects within the specified collection. You can create up to 50 recipient subscriptions per object at a time and you can modify up to 100 objects per request, totaling up to 5,000 operations per request.

Returns a BulkOperation that executes the job asynchronously. Progress can be tracked via the BulkOperation API.

Endpoint

POST/objects/:collection/bulk/subscriptions/add

Rate limit

Tier 1

Path parameters

collectionstringThe type of object you are storing in Knock.

Body parameters

subscriptionsAddSubscriptionsOp[]A list of subscriptions to create. Each entry represents a set of Recipients to subscribe to an Object.

Response

A BulkOperation.

Delete subscriptions

Removes one or more recipients as subscribers to the object.

Endpoint

DELETE/objects/:collection/:id/subscriptions

Rate limit

Tier 3

Path parameters

collectionstringA collection that the object belongs to
idstringThe unique identifier of the object in the collection

Body parameters

recipientsRecipientIdentifier[]A list of recipient identifiers

Response

A list of deleted ObjectSubscription

Preferences

A preference determines 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.

Read more about Preferences.

Attributes

idstringUnique identifier for the preference set
workflowsobjectA set of preferences for workflows, each can resolve to a boolean, to a set of channel types, or to a set of conditions
channel_typesobjectA set of preferences for channel types
categoriesobjectA set of preferences for workflow categories, each can resolve to a boolean, to a set of channel types, or to a set of conditions
Endpoints
GET/users/:user_id/preferences
GET/users/:user_id/preferences/:id
PUT/users/:user_id/preferences/:id
GET/objects/:collection/:object_id/preferences
GET/objects/:collection/:object_id/preferences/:id
PUT/objects/:collection/:object_id/preferences/:id
POST/users/bulk/preferences

Listing user preferences

Retrieve all preference sets for a user. This endpoint returns a list of preference sets associated with the user.

Endpoint

GET/users/:user_id/preferences

Rate limit

Tier 4

Path parameters

user_idstringUnique identifier for the user

Response

Returns a list of PreferenceSet objects.

Getting user preferences

Retrieve a user's preference set. Will always return an empty preference set object, even if it does not currently exist for the user.

Endpoint

GET/users/:user_id/preferences/:id

Rate limit

Tier 4

Path parameters

user_idstringUnique identifier for the user
idstringUnique identifier for the preference set

Query parameters

tenantstringAn optional tenant identifier to supply to return the user's preferences with any tenant defaults applied

Response

Returns a PreferenceSet.

Setting user preferences

Sets preferences within the given preference set. This is a destructive operation and will replace any existing preferences with the preferences given.

If no user exists in the current environment for the given :user_id, Knock will create the user entry as part of this request.

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

Endpoint

PUT/users/:user_id/preferences/:id

Rate limit

Tier 3

Path parameters

user_idstringUnique identifier for the user
idstringUnique identifier for the preference set

Body parameters

channel_typesobjectA set of channel type preferences
workflowsobjectA set of workflow preferences, can be a boolean, an object containing channel type preferences, or a set of conditions
categoriesobjectA set of category preferences, can be a boolean, an object containing channel type preferences, or a set of conditions

Response

Returns a PreferenceSet.

Listing object preferences

Retrieve all preference sets for an object. This endpoint returns a list of preference sets associated with the object.

Endpoint

GET/objects/:collection/:object_id/preferences

Rate limit

Tier 4

Path parameters

collectionstringThe parent collection of the object to lookup
object_idstringThe id of the object to lookup

Response

Returns a list of PreferenceSet objects.

Getting object preferences

Retrieve an object's preference set. Will always return an empty preference set object, even if it does not currently exist for the object.

Endpoint

GET/objects/:collection/:object_id/preferences/:id

Rate limit

Tier 4

Path parameters

collectionstringThe parent collection of the object to lookup
object_idstringThe id of the object to lookup
idstringUnique identifier for the preference set

Query parameters

tenantstringAn optional tenant identifier to supply to return the user's preferences with any tenant defaults applied

Response

Returns a PreferenceSet.

Setting object preferences

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

PUT/objects/:collection/:object_id/preferences/:id

Rate limit

Tier 3

Path parameters

collectionstringThe parent collection of the object to lookup
object_idstringThe id of the object to lookup
idstringUnique identifier for the preference set

Body parameters

channel_typesobjectA set of channel type preferences
workflowsobjectA set of workflow preferences, can be a boolean, an object containing channel type preferences, or a set of conditions
categoriesobjectA set of category preferences, can be a boolean, an object containing channel type preferences, or a set of conditions

Response

Returns a PreferenceSet.

Bulk set user preferences

Bulk sets the preferences for up to 1,000 users at a time. Returns a BulkOperation that executes the job asynchronously. Progress can be tracked via the BulkOperation API.

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

Please note: This is a destructive operation and will replace any existing users' preferences with the preferences sent.

Endpoint

POST/users/bulk/preferences

Rate limit

Tier 1

Body parameters

user_idsstring[]A list of user ids to set preferences for
preferences.idstringThe id of the preference set
preferences.channel_typesobjectA set of channel type preferences to set
preferences.workflowsobjectA set of workflow preferences, can be a boolean or an object containing channel type preferences
preferences.categoriesobjectA set of categories preferences, can be a boolean or an object containing channel type preferences

Response

Returns a BulkOperation.

Tenants

A Tenant represents 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.

Attributes

idstringA unique identifier for the tenant.
propertiesobjectAn object of key-value pairs for attributes you want to associate with the tenant. Currently only name is accepted as an attribute for tenants.
settingsobjectAn object of key-value pairs for configurable settings on a tenant. Currently contains a preference_set key for tenant-specific default preferences, as well as a branding key which points to the following configurable values: primary_color, primary_color_contrast, icon_url, and logo_url. The icon_url and logo_url settings must be a valid image URL with an image MIME type.
Endpoints
GET/tenants
GET/tenants/:id
PUT/tenants/:id
DELETE/tenants/:id

List tenants for environment

Lists tenants for the environment of the API key

Endpoint

GET/tenants

Rate limit

Tier 4

Response

Returns a list of Tenant objects.

Get a tenant

Retrieve a tenant by its id.

Endpoint

GET/tenants/:id

Rate limit

Tier 4

Path parameters

idstringA unique identifier for the tenant.

Response

Returns a Tenant.

Set a tenant

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

Endpoint

PUT/tenants/:id

Rate limit

Tier 3

Path parameters

idstringA unique identifier for the tenant.

Body parameters

namestringThe name to set on the tenant's name property.
settingsobjectAn object of key-value pairs for configurable settings on a tenant. Currently contains a preference_set key for tenant-specific default preferences, as well as a branding key which points to the following configurable values: primary_color, primary_color_contrast, icon_url, and logo_url. The icon_url and logo_url settings must be a valid image URL with an image MIME type.

Response

Returns a Tenant.

Delete a tenant

Deletes a tenant by the id provided.

Endpoint

DELETE/tenants/:id

Rate limit

Tier 2

Path parameters

idstringA unique identifier for the tenant within the collection.

Response

No response.

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.

Learn more about schedules

Attributes

idstringA unique, Knock generated identifier for the schedule.
actorRecipient | nullThe actor to be referenced on the workflow trigger.
recipientRecipientThe recipient of the scheduled workflow.
dataobject | nullStatic data to be passed to the workflow trigger.
workflowstringThe key of the workflow that will be triggered in this schedule.
tenantstring | nullThe tenant to be passed to the workflow trigger.
repeatsScheduleRepeat[] | nullA list of one or more repeat definitions that determine when this schedule should run.
last_occurrence_at | nulldatetime (optional)A datetime string in UTC that indicates when the last run for the schedule happened.
next_occurrence_at | nulldatetime (optional)A datetime string in the recipient's timezone that indicates when the schedule will next run, generated from the repeat rules.
Endpoints
GET/schedules
GET/users/:id/schedules
GET/objects/:collection/:id/schedules
POST/schedules
PUT/schedules
DELETE/schedules
POST/schedules/bulk/create

List schedules

Returns a paginated list of schedules in descending order.

Endpoint

GET/schedules

Rate limit

Tier 4

Query parameters

page_sizenumberThe total number to retrieve per page (defaults to 50)
afterstringThe cursor to retrieve items after (hint: use the `__cursor` field)
beforestringThe cursor to retrieve items before (hint: use the `__cursor` field)
workflowstring (required)The workflow key to filter schedules for.
recipientsstring[] | object<string, RecipientRef>A collection of recipient identifiers (user_ids and/or ObjectRefs) to filter schedules for.
tenantstringA tenant identifier to filter schedules for.

Response

A paginated response containing a list of Schedule entities.

User schedules

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

Endpoint

GET/users/:id/schedules

Rate limit

Tier 4

Query parameters

page_sizenumberThe total number to retrieve per page (defaults to 50)
afterstringThe cursor to retrieve items after (hint: use the `__cursor` field)
beforestringThe cursor to retrieve items before (hint: use the `__cursor` field)
workflowstring (required)The workflow key to filter schedules for.
tenantstringA tenant identifier to filter schedules for.

Response

A paginated response containing a list of Schedule entities.

Object schedules

Returns a paginated list of schedules for a single object, in descending order.

Endpoint

GET/objects/:collection/:id/schedules

Rate limit

Tier 4

Query parameters

page_sizenumberThe total number to retrieve per page (defaults to 50)
afterstringThe cursor to retrieve items after (hint: use the `__cursor` field)
beforestringThe cursor to retrieve items before (hint: use the `__cursor` field)
workflowstring (required)The workflow key to filter schedules for.
tenantstringA tenant identifier to filter schedules for.

Response

A paginated response containing a list of Schedule entities.

Create schedules

Creates new schedules for the recipients provided. Up to 100 recipients may be specified in a single schedule creation call. Recipients may be inline-identified during this call.

Endpoint

POST/schedules

Rate limit

Tier 3

Body parameters

recipientsRecipientIdentifier[]A list of recipient identifiers
actorRecipient | nullThe actor to be referenced on the workflow trigger for this schedule.
dataobject | nullStatic data to be passed to the workflow trigger or this schedule.
workflowstringThe key of the workflow that will be triggered in this schedule.
tenantstring | nullThe tenant to be passed to the workflow trigger for this schedule.
repeatsScheduleRepeat[] | nullA list of one or more repeat definitions that determine when this schedule should run.
scheduled_atstringA UTC datetime in ISO-8601 format representing the start moment for the recurring schedule, or the exact and only execution moment for the non-recurring schedule.

Response

The list of created Schedule entities.

Update schedules

Updates the schedules for the schedule_ids given. Can update up to 100 schedules at a time.

Endpoint

PUT/schedules

Rate limit

Tier 3

Body parameters

schedule_idsstring[]A list of schedule ids of the schedules to mutate.
actorRecipient | nullThe actor to be referenced on the workflow trigger for this schedule.
dataobject | nullStatic data to be passed to the workflow trigger or this schedule.
tenantstring | nullThe tenant to be passed to the workflow trigger for this schedule.
repeatsScheduleRepeat[] | nullA list of one or more repeat definitions that determine when this schedule should run.
scheduled_atstringA UTC datetime in ISO-8601 format representing the start moment for the recurring schedule, or the exact and only execution moment for the non-recurring schedule.

Response

The list of updated Schedule entities.

Delete schedules

Deletes the schedules for the schedule_ids given. Can delete up to 100 schedules at a time. Deleting a schedule will cancel its next occurrence immediately. Any running scheduled workflows will not be affected.

Endpoint

DELETE/schedules

Rate limit

Tier 3

Body parameters

schedule_idsstring[]A list of schedule ids of the schedules to mutate.

Response

The list of deleted Schedule entities.

Bulk create schedules

Bulk creates up to 1,000 schedules at a time. Returns a BulkOperation that executes the job asynchronously. Progress can be tracked via the BulkOperation API.

Each schedule provided in the schedules list must have a single recipient. The recipients do not have to be unique across schedules.

This endpoint also handles inline identifications for the actor, recipient, and tenant fields.

Endpoint

POST/schedules/bulk/create

Rate limit

Tier 1

Body parameters

schedulesSchedule[]A list of schedules to create. Each schedule must have a single recipient. The recipients do not have to be unique.

Response

Returns a BulkOperation.

Channel data

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

Attributes

channel_idstringThe UUID of the channel this data belongs to
dataobjectThe provider specific channel data
Endpoints
GET/users/:user_id/channel_data/:channel_id
PUT/users/:user_id/channel_data/:channel_id
DELETE/users/:user_id/channel_data/:channel_id
GET/objects/:collection/:object_id/channel_data/:channel_id
PUT/objects/:collection/:object_id/channel_data/:channel_id
DELETE/objects/:collection/:object_id/channel_data/:channel_id

Getting user channel data

Retrieves the channel data for the provided user on the channel specified.

Endpoint

GET/users/:user_id/channel_data/:channel_id

Rate limit

Tier 4

Path parameters

user_idstringThe id of the user to lookup
channel_idstringThe id of the Knock channel to lookup

Returns

  • 200 with a ChannelData object (when found)
  • 404 when not found

Setting user channel data

Sets channel data for the user and the channel specified.

If no user exists in the current environment for the given :user_id, Knock will create the user entry as part of this request.

Endpoint

PUT/users/:user_id/channel_data/:channel_id

Rate limit

Tier 3

Path parameters

user_idstringThe id of the user to lookup
channel_idstringThe id of the Knock channel to lookup

Body parameters

dataobject

The data to set for the specified channel_id. The shape of the payload varies depending on the channel. You can learn more about channel data schemas here.

Returns

  • 200 with a ChannelData object (when set)
  • 404 when the channel specified cannot be found
  • 422 with errors when the data is incorrectly shaped

Unsetting user channel data

Unsets (removes) channel data for the user and the channel specified.

Endpoint

DELETE/users/:user_id/channel_data/:channel_id

Rate limit

Tier 3

Path parameters

user_idstringThe id of the user to lookup
channel_idstringThe id of the Knock channel to lookup

Returns

  • 204 no content
  • 404 when the channel specified cannot be found

Getting object channel data

Retrieves the channel data for the provided object on the channel specified.

Endpoint

GET/objects/:collection/:object_id/channel_data/:channel_id

Rate limit

Tier 4

Path parameters

object_idstringThe id of the object to lookup
collectionstringThe parent collection of the object to lookup
channel_idstringThe id of the Knock channel to lookup

Returns

  • 200 with a ChannelData (when found)
  • 404 when not found

Setting object channel data

Sets channel data for the object and the channel specified.

If no object exists in the current environment for the given :collection and :object_id, Knock will create the object as part of this request.

Endpoint

PUT/objects/:collection/:object_id/channel_data/:channel_id

Rate limit

Tier 3

Path parameters

object_idstringThe id of the object to lookup
collectionstringThe parent collection of the object to lookup
channel_idstringThe id of the Knock channel to lookup

Body parameters

dataobject

The data to set for the specified channel_id. The shape of the payload varies depending on the channel. You can learn more about channel data schemas here.

Returns

  • 200 with a ChannelData object (when set)
  • 404 when the channel specified cannot be found
  • 422 with errors when the data is incorrectly shaped

Unsetting object channel data

Unsets (removes) channel data for the object and the channel specified.

Endpoint

DELETE/objects/:collection/:object_id/channel_data/:channel_id

Rate limit

Tier 3

Path parameters

object_idstringThe id of the object to lookup
collectionstringThe parent collection of the object to lookup
channel_idstringThe id of the Knock channel to lookup

Returns

  • 204 no content
  • 404 when the channel specified cannot be found

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.

Attributes

idstringThe unique ID of this bulk operation
namestringThe type of operation being performed
estimated_total_rowsintegerAn approximation of the number of rows that will be mutated in this operation
processed_rowsintegerThe number of the rows that have been handled in this operation, either successfully or in error
success_countintegerThe number of the rows that have been modified successfully in this operation
error_countintegerThe number of the rows that errored in this operation
error_itemsobject[]A list of items that errored in this operation, if available
statusenumOne of `queued`, `processing`, `completed`, `failed`
started_atstringAn ISO-8601 datetime string for when the operation started processing
completed_atstringAn ISO-8601 datetime string for when the operation completed processing
failed_atstringAn ISO-8601 datetime string for when the operation failed processing
Endpoints
GET/bulk_operations/:id

Retrieve a bulk operation

Retrieve the bulk operation, revealing the current status and the number of rows processed. You can poll this endpoint to understand when a bulk operation has finished executing (either completed, or failed).

Endpoint

GET/bulk_operations/:id

Rate limit

Tier 4

Path parameters

idstringThe ID of a bulk operation to retrieve

Returns

A BulkOperation

Slack

These endpoints handle communication with the Slack API to streamline authentication and data gathering. They are used by SlackKit components and hooks.

Endpoints
GET/providers/slack/:channel_id/auth_check
GET/providers/slack/:channel_id/channels
PUT/providers/slack/:channel_id/revoke_access

Slack auth check

Get the status of Slack authentication.

Endpoint

GET/providers/slack/:channel_id/auth_check

Rate limit

Tier 2

Path parameters

channel_idstringThe Knock Slack channel ID

Query parameters

access_token_object[object_id]stringID of the Object or Tenant.
access_token_object[collection]stringCollection of the Object or Tenant. If Tenant, should be `$tenants`.

Returns

  • 200 Connection data from the Slack API.
  • 403 When no access token is set for the given object.

Slack channels

Get a list of the Slack channels for the access token stored in the given access token object.

Endpoint

GET/providers/slack/:channel_id/channels

Rate limit

Tier 2

Path parameters

channel_idstringThe Knock Slack channel ID

Query parameters

access_token_object[object_id]stringID of the Object or Tenant.
access_token_object[collection]stringCollection of the Object or Tenant. If Tenant, should be `$tenants`.
query_options[:option]stringAn optional query option passed to Slack. One of `cursor`, `exclude_archived`, `limit`, `team_id`, `types`. See Slack documentation for more information: https://api.slack.com/methods/conversations.list#arg_cursor

Returns

  • 200 List of partial data about the Slack channels requested.
  • 403 When no access token is set for the given object.

Slack revoke access

Revoke an access token from Slack and remove it from the access token object.

Endpoint

PUT/providers/slack/:channel_id/revoke_access

Rate limit

Tier 2

Path parameters

channel_idstringThe Knock Slack channel ID

Query parameters

access_token_object[object_id]stringID of the Object or Tenant.
access_token_object[collection]stringCollection of the Object or Tenant. If Tenant, should be `$tenants`.

Returns

  • 200 Success response
  • 403 When no access token is set for the given object.

Microsoft Teams

These endpoints handle communication with the Microsoft Graph API to streamline authentication and data gathering. They are used by TeamsKit components and hooks.

Endpoints
GET/providers/ms-teams/:channel_id/auth_check
GET/providers/ms-teams/:channel_id/teams
GET/providers/ms-teams/:channel_id/channels
PUT/providers/ms-teams/:channel_id/revoke_access

Microsoft Teams auth check

Get the status of Microsoft Teams authentication.

Endpoint

GET/providers/ms-teams/:channel_id/auth_check

Rate limit

Tier 2

Path parameters

channel_idstringThe Knock Microsoft Teams channel ID

Query parameters

ms_teams_tenant_object[object_id]stringID of the Object or Tenant.
ms_teams_tenant_object[collection]stringCollection of the Object or Tenant. If Tenant, should be `$tenants`.

Returns

  • 200 Success response
  • 403 When no Microsoft Entra tenant ID is set for the given object.

Microsoft Teams teams

Get a list of teams belonging to the Microsoft Entra tenant.

Endpoint

GET/providers/ms-teams/:channel_id/teams

Rate limit

Tier 2

Path parameters

channel_idstringThe Knock Microsoft Teams channel ID

Query parameters

ms_teams_tenant_object[object_id]stringID of the Object or Tenant.
ms_teams_tenant_object[collection]stringCollection of the Object or Tenant. If Tenant, should be `$tenants`.
query_options[:option]stringAn optional query option passed to the Microsoft Graph API. One of $filter, $select, $top, $skiptoken. See the Microsoft Graph API documentation for more information.

Returns

  • 200 List of teams in the Microsoft Entra tenant.
  • 403 When no Microsoft Entra tenant ID is set for the given object.

Microsoft Teams channels

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

Endpoint

GET/providers/ms-teams/:channel_id/channels

Rate limit

Tier 2

Path parameters

channel_idstringThe Knock Microsoft Teams channel ID

Query parameters

ms_teams_tenant_object[object_id]stringID of the Object or Tenant.
ms_teams_tenant_object[collection]stringCollection of the Object or Tenant. If Tenant, should be `$tenants`.
team_idstringThe ID of the Microsoft Teams team to list channels from.
query_options[:option]stringAn optional query option passed to the Microsoft Graph API. One of $filter, $select. See the Microsoft Graph API documentation for more information.

Returns

  • 200 List of Microsoft Teams channels in the specified team.
  • 403 When no Microsoft Entra tenant ID is set for the given object.

Microsoft Teams revoke access

Removes a Microsoft Entra tenant ID from the Microsoft Teams tenant object.

Endpoint

PUT/providers/ms-teams/:channel_id/revoke_access

Rate limit

Tier 2

Path parameters

channel_idstringThe Knock Microsoft Teams channel ID

Query parameters

ms_teams_tenant_object[object_id]stringID of the Object or Tenant.
ms_teams_tenant_object[collection]stringCollection of the Object or Tenant. If Tenant, should be `$tenants`.

Returns

  • 200 Success response
  • 403 When no Microsoft Entra tenant ID is set for the given object.

Audiences

🚧
Audiences are currently in beta. If you'd like early access, or this is blocking your adoption of Knock, please get in touch.

An Audience represents a user segment.

Use the Audiences API to sync user segments from your data warehouse to Knock. Audiences can be used to target messages or orchestrate workflows via branch and step conditions.

Endpoints
GET/audiences/:audience_key/members
POST/audiences/:audience_key/members
DELETE/audiences/:audience_key/members

List audience members

🚧
Audiences are currently in beta. If you'd like early access, or this is blocking your adoption of Knock, please get in touch.

List audience members.

Endpoint

GET/audiences/:audience_key/members

Rate limit

Tier 4

Path parameters

audience_keystringThe key of the audience to add the user to
page_sizenumberThe total number to retrieve per page (defaults to 25)
afterstringThe cursor to retrieve items after (hint: use the `page_info.after` field)
beforestringThe cursor to retrieve items before (hint: use the `page_info.before` field)

Returns

A paginated list of audience members records. The value of the user field is a User object. If no user is found for a given user ID, the value of the user field will be null.

Add audience members

🚧
Audiences are currently in beta. If you'd like early access, or this is blocking your adoption of Knock, please get in touch.

Adds members to an audience. The same user can be added to the audience multiple times with distinct tenant IDs.

Endpoint

POST/audiences/:audience_key/members

Rate limit

Tier 3

Path parameters

audience_keystringThe key of the audience to add members to

Body parameters

membersobject[]Members to add to the audience. The `tenant` field is optional. Max length is 1000.

Returns

  • 204 no content
  • 404 if the audience cannot be found

Remove audience members

🚧
Audiences are currently in beta. If you'd like early access, or this is blocking your adoption of Knock, please get in touch.

Removes members from an audience. If a member was added with a tenant ID, that tenant ID must also be provided for the member in the deletion request.

Endpoint

DELETE/audiences/:audience_key/members

Rate limit

Tier 3

Path parameters

audience_keystringThe key of the audience to remove members from

Body parameters

membersobject[]Members to remove from the audience. The `tenant` field is optional. Max length is 1000.

Returns

  • 204 no content
  • 404 if the audience cannot be found