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 following header:

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 400 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.
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_inactiveThe workflow you attempted to invoke is marked as inactive. To resolve this error, activate the workflow on its page in the dashboard.
workflow_missingThe workflow you attemped 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.

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
*key-value pairsAny custom properties
Endpoints
PUT/users/:user_id
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

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
*key-value pairsAny custom properties

Returns

A User.

Get a user

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

Endpoint

GET/users/:user_id

Path parameters

idstringUnique identifier of the user

Returns

A User.

User messages

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

Endpoint

GET/users/:id/messages

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`, `undelivered`, `not_sent`. Limits results to items in the given status(es)
channel_idstring (optional)Limits the results to only items that belong to the channel

Returns

A paginated list of Message records

Delete a user

Deletes a user by the id given.

Endpoint

DELETE/users/:user_id

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

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 100 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

Body parameters

usersUser[]A list of users to upsert (up to 100)

Returns

A BulkOperation.

Bulk delete users

Deletes up to 100 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

Body parameters

user_idsstring[]Unique identifiers of the users to delete

Returns

A BulkOperation.

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

Triggering a workflow

A trigger calls a workflow created via the Knock dashboard.

Endpoint

POST/workflows/:key/trigger

Path parameters

keystringThe key of the workflow to call

Body parameters

recipientsRecipientIdentifier[]A list of user ids or object references to notify for this workflow
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
datadictionaryA set of key value pairs to pass to the notify

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 full 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 notify call, Knock will persist it as part of processing the workflow. This is comparable to direct calls to the identify user or set object APIs.

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

Endpoint

POST/workflows/:key/trigger

Path parameters

keystringThe key of the workflow to call

Body parameters

recipientsRecipient[]A list of maps of properties describing a user or an object to identify in Knock and notify for this workflow
actorRecipient (optional)A map of properties describing a user or an object to identify in Knock and mark as who or what performed the notify 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
datadictionaryA set of key value pairs to pass to the notify 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

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.

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.

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/objects/:collection/:id/preferences
GET/users/:user_id/preferences/:id
GET/objects/:collection/:id/preferences/:id
PUT/users/:user_id/preferences/:id
PUT/objects/:collection/:id/preferences/:id
POST/users/bulk/preferences

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

Path parameters

user_idstringUnique identifier for the user
idstringUnique identifier for the preference set

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.

The preference set id can be either default or a tenant.id. Learn more about per-tenant preference sets in our preferences guide.

Endpoint

PUT/users/:user_id/preferences/:id

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.

Bulk set preferences

Sets the preferences for the users indicated via an asynchronous BulkOperation. This is a destructive operation and will replace any existing users' preferences with the preferences sent.

Endpoint

POST/users/bulk/preferences

Body parameters

user_idsstring[]A list of user ids to set preferences for (up to 100)
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.

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

Path parameters

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

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.

The preference set id can be either default or a tenant.id. Learn more about per-tenant preference sets in our preferences guide.

Endpoint

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

Path parameters

object_idstringThe id of the object to lookup
collectionstringThe parent collection 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.

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.

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/object/:collection/:object_id/channel_data/:channel_id
PUT/object/:collection/:object_id/channel_data/:channel_id
DELETE/object/:collection/:object_id/channel_data/:channel_id

Getting user channel data

Retrieves the channel data for the provided user (or object) on the channel specified.

Endpoint

GET/users/:user_id/channel_data/:channel_id

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.

Endpoint

PUT/users/:user_id/channel_data/:channel_id

Path parameters

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

Body parameters

dataobjectThe data to set for this channel, shape of the payload varies depending on the channel

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

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 user (or object) on the channel specified.

Endpoint

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

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.

Endpoint

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

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

dataobjectThe data to set for this channel, shape of the payload varies depending on the channel

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

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

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 feed for user

Retrieves a feed of items for a given user_id on the given feed_id.

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

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)
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 feed to only items of the source workflow
tenantstring (optional)Limits the feed to only display items with the corresponding tenant, or where the tenant is empty
has_tenantboolean (optional)Scope the feed to display items with or without any tenancy
statusstring (optional)One of `unread`,`read`, `unseen`,`seen`, `all`
archivedstring (optional)One of `include`, `exclude`, `only` (defaults to `exclude`)

Returns

A feed response.

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
recipientstring or RecipientIdentifierThe 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
workflowstringThe key of the workflow that this message was generated from
tenantstringThe ID of the tenant that this message belongs to
statusstringOne of `queued`, `sent`, `delivered`, `undelivered`, `seen`, `unseen`
read_atstring (optional)When the message was last read
seen_atstring (optional)When the message was last seen
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/activities
GET/messages/:id/events
GET/messages/:id/content
PUT/messages/:id/:status
DELETE/messages/:id/:status
POST/messages/batch/:status
POST/channels/:id/messages/bulk/:status

Listing messages

Returns a paginated list of messages.

Endpoint

GET/messages

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`, `undelivered`, `not_sent`. Limits results to items in the given status(es)
channel_idstring (optional)Limits the results to only items that belong to the channel

Returns

A paginated list of Message records

Fetching a message

Retrieve a message by the id.

Endpoint

GET/messages/:id

Path parameters

idstringThe ID of the message

Returns

A Message

Events

Returns a paginated list of events for a message.

Endpoint

GET/messages/:id/events

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

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

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 Activity records

Content

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

Endpoint

GET/messages/:id/content

Path parameters

idstringThe ID of the message

Returns

A MessageContent.

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

Updating a message status

Marks the given message as the status, recording an event in the process.

Endpoint

PUT/messages/:id/:status

Path parameters

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

Returns

A Message.

Undoing a message status change

Un-marks the given message as the status, recording an event in the process.

Endpoint

DELETE/messages/:id/:status

Path parameters

idstringThe ID of the message
statusenumOne of `seen`, `read`, `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

Path parameters

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

Body parameters

message_idsstring[]A list of one or more message IDs

Returns

A list of Messages that were mutated during the call.

Bulk changing message statuses in a channel

The bulk change endpoint allows you to modify all, or a subset of messages for a given channel via an asynchronous job. The messages to be modified can be filtered using the properties listed below, and this operation will always return a BulkOperation which allows you to track the status of the job.

Endpoint

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

Path parameters

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

Body parameters

user_idsstring[]Scope the bulk update to one or more users (optional)
older_thanstringAn ISO-8601 timestamp to find messages created before (optional)
newer_thanstringAn ISO-8601 timestamp to find messages created after (optional)
delivery_statusenumLimit messages to one of `queued`, `sent`, `delivered`, `undelivered` (optional)
engagement_statusenumLimit messages to one of `seen`, `unseen`, `read`, `unread`, `archived`, `unarchived` (optional)

Returns

A BulkOperation

Bulk operations

A bulk operation represents a set of changes that are to be performed across 0 or more records. The bulk operation resource 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. If you wish to pin this job to a specific point in time, you can initiate it with a date filter (like older_than).

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 mutated in this operation
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

Path parameters

idstringThe ID of a bulk operation to retrieve

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.
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/:id
GET/objects/:collection/:id/messages
PUT/objects/:collection/:id
DELETE/objects/:collection/:id
POST/objects/:collection/bulk/set
POST/objects/:collection/bulk/delete

Get an object

Retrieve an object in a collection by the id.

Endpoint

GET/objects/:collection/:id

Path parameters

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

Response

Returns an Object.

Object messages

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

Endpoint

GET/objects/:collection/:id/messages

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`, `undelivered`, `not_sent`. Limits results to items in the given status(es)
channel_idstring (optional)Limits the results to only items that belong to the channel

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

Path parameters

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

Body parameters

*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

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 100 objects at a time within a collection, returning an asynchronous BulkOperation that can be used to monitor the progress of the operation.

Endpoint

POST/objects/:collection/bulk/set

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 100 objects at a time within a collection, returning an asynchronous BulkOperation that can be used to monitor the progress of the operation.

Endpoint

POST/objects/:collection/bulk/delete

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.

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 settings only contain a branding key which points to the following configurable values: primary_color, primary_color_contrast, icon_url, and logo_url.
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

Response

Returns a list of Tenant objects.

Get a tenant

Retrieve a tenant by its id.

Endpoint

GET/tenants/:id

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

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. See example for possible key-value pairs.

Response

Returns a Tenant.

Delete a tenant

Deletes a tenant by the id provided.

Endpoint

DELETE/tenants/:id

Path parameters

idstringA unique identifier for the tenant within the collection.

Response

No response.