Users
A [User](/concepts/users) represents an individual in your system who can receive notifications through Knock. Users are the most common recipients of notifications and are always referenced by your internal identifier.
Users
#A User represents an individual in your system who can receive notifications through Knock. Users are the most common recipients of notifications and are always referenced by your internal identifier.
Get user
#Retrieve a specific user by their ID.
Endpoint
Rate limit
Tier 4Path parameters
The ID of the user to retrieve.
Returns
A User represents an individual in your system who can receive notifications through Knock. Users are the most common recipients of notifications and are always referenced by your internal identifier.
The typename of the schema.
A URL for the avatar of the user.
The creation date of the user from your system.
The primary email address for the user.
The unique identifier of the user.
Display name of the user.
The E.164 phone number of the user (required for SMS channels).
The timezone of the user. Must be a valid tz database time zone string. Used for recurring schedules.
The timestamp when the resource was last updated.
Any additional custom properties.
List users
#Retrieve a paginated list of users in the environment. Defaults to 50 users per page.
Endpoint
Rate limit
Tier 4Query parameters
Associated resources to include in the response.
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page (defaults to 50).
Returns
A paginated list of users.
A list of users.
The typename of the schema.
A URL for the avatar of the user.
The creation date of the user from your system.
The primary email address for the user.
The unique identifier of the user.
Display name of the user.
The E.164 phone number of the user (required for SMS channels).
The timezone of the user. Must be a valid tz database time zone string. Used for recurring schedules.
The timestamp when the resource was last updated.
Pagination information for a list of resources.
The typename of the schema.
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page (defaults to 50).
Identify user
#Create or update a user with the provided identification data. When you identify an existing user, the system merges the properties you specific with what is currently set on the user, updating only the fields included in your requests.
Endpoint
Rate limit
Tier 3Path parameters
The unique identifier of the user.
Request body
A URL for the avatar of the user.
Channel-specific information that's needed to deliver a notification to an end provider.
The creation date of the user from your system.
The primary email address for the user.
The locale of the user. Used for message localization.
Display name of the user.
The E.164 phone number of the user (required for SMS channels).
The timezone of the user. Must be a valid tz database time zone string. Used for recurring schedules.
Any additional custom properties.
Returns
A User represents an individual in your system who can receive notifications through Knock. Users are the most common recipients of notifications and are always referenced by your internal identifier.
The typename of the schema.
A URL for the avatar of the user.
The creation date of the user from your system.
The primary email address for the user.
The unique identifier of the user.
Display name of the user.
The E.164 phone number of the user (required for SMS channels).
The timezone of the user. Must be a valid tz database time zone string. Used for recurring schedules.
The timestamp when the resource was last updated.
Any additional custom properties.
Merge users
#Merge two users together, where the user specified with the from_user_id param will be merged into the user specified by user_id.
Endpoint
Rate limit
Tier 2Path parameters
The id of the user to merge into.
Request body
The user ID to merge from.
Returns
A User represents an individual in your system who can receive notifications through Knock. Users are the most common recipients of notifications and are always referenced by your internal identifier.
The typename of the schema.
A URL for the avatar of the user.
The creation date of the user from your system.
The primary email address for the user.
The unique identifier of the user.
Display name of the user.
The E.164 phone number of the user (required for SMS channels).
The timezone of the user. Must be a valid tz database time zone string. Used for recurring schedules.
The timestamp when the resource was last updated.
Any additional custom properties.
Delete user
#Permanently delete a user and all associated data.
Endpoint
Rate limit
Tier 2Path parameters
The ID of the user to delete.
Returns
List user messages
#Returns a paginated list of messages for a specific user. Messages are sorted with the most recent ones appearing first. Messages outside the account's retention window will not be included in the results.
Endpoint
Rate limit
Tier 4Path parameters
The user ID to list messages for.
Query parameters
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page (defaults to 50).
Limits the results to items with the corresponding tenant.
Limits the results to items with the corresponding channel ID.
Limits the results to messages with the given delivery status.
Limits the results to messages with the given engagement status.
Limits the results to only the message IDs given (max 50). Note: when using this option, the results will be subject to any other filters applied to the query.
Limits the results to messages related to any of the provided categories.
Limits the results to messages triggered by the given workflow key.
Limits the results to messages associated with the top-level workflow run ID returned by the workflow trigger request.
Limits the results to messages for a specific recipient's workflow run.
Limits the results to only messages that were generated with the given data. See trigger data filtering for more information.
Limits the results to messages inserted after or on the given date.
Limits the results to messages inserted before or on the given date.
Limits the results to messages inserted after the given date.
Limits the results to messages inserted before the given date.
Returns
A paginated list of messages.
A list of messages.
The typename of the schema.
One or more actors that are associated with this message. Note: this is a list that can contain up to 10 actors if the message is produced from a batch.
Timestamp when the message was archived.
A configured channel, which is a way to route messages to a provider.
The timestamp of when the channel was created.
The unique identifier for the channel.
Unique identifier for the channel within a project (immutable once created).
The human-readable name of the channel.
The ID of the provider that this channel uses to deliver messages.
The type of channel, determining what kind of messages it can send.
The timestamp of when the channel was last updated.
Deprecated, use channel.id instead.
Timestamp when the message was clicked.
Data associated with the message’s workflow run. Includes the workflow trigger request’s data payload merged with any additional data returned by a fetch function. For messages produced after a batch step, includes the payload data from the most-recent trigger request (the final activity in the batch).
A list of engagement statuses.
The unique identifier for the message.
Timestamp when the resource was created.
Timestamp when the message was interacted with.
Timestamp when a link in the message was clicked.
The metadata associated with the message.
Timestamp when the message was read.
A reference to a recipient, either a user identifier (string) or an object reference (ID, collection).
Timestamp when the message was scheduled to be sent.
Timestamp when the message was seen.
The workflow or guide that triggered the message.
The categories associated with the message.
The key of the workflow or guide that triggered the message.
The step reference for the step in the workflow that generated the message.
Whether this message was generated from a workflow, broadcast, or guide.
The ID of the version of the workflow or guide that triggered the message.
The unique identifier for the workflow recipient run that generated this message. Only present for workflow/broadcast messages.
The unique identifier for the workflow run that generated this message. Only present for workflow/broadcast messages.
The message delivery status.
The ID of the tenant associated with the message. Only present when a tenant is provided on a workflow trigger request.
The timestamp when the resource was last updated.
The key of the workflow that generated the message.
Pagination information for a list of resources.
The typename of the schema.
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page (defaults to 50).
List user schedules
#Returns a paginated list of schedules for a specific user, in descending order.
Endpoint
Rate limit
Tier 4Path parameters
The user ID to list schedules for.
Query parameters
The workflow key to filter schedules for.
The tenant ID to filter schedules for.
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page (defaults to 50).
Returns
A response containing a list of schedules.
A list of schedules.
The typename of the schema.
A map of properties describing a user or an object to identify in Knock and mark as who or what performed the action.
An optional map of data to pass into the workflow execution. There is a 10MB limit on the size of the full data payload. Any individual string value greater than 1024 bytes in length will be truncated in your logs.
Unique identifier for the schedule.
Timestamp when the resource was created.
The last occurrence of the schedule.
The next occurrence of the schedule.
A recipient of a notification, which is either a user or an object.
The repeat rule for the schedule.
The typename of the schema.
The day of the month to repeat the schedule.
The days of the week to repeat the schedule.
The frequency of the schedule.
The hour of the day to repeat the schedule.
The interval of the schedule.
The minute of the hour to repeat the schedule.
The tenant to trigger the workflow for. Triggering with a tenant will use any tenant-level overrides associated with the tenant object, and all messages produced from workflow runs will be tagged with the tenant.
The timestamp when the resource was last updated.
The workflow the schedule is applied to.
Pagination information for a list of resources.
The typename of the schema.
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page (defaults to 50).
List user subscriptions
#Retrieves a paginated list of subscriptions for a specific user, in descending order.
Endpoint
Rate limit
Tier 4Path parameters
The user ID to list subscriptions for.
Query parameters
Associated resources to include in the response.
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page (defaults to 50).
Returns
A response containing a list of subscriptions.
A list of subscriptions.
The typename of the schema.
Timestamp when the resource was created.
A custom Object entity which belongs to a collection.
The typename of the schema.
The collection this object belongs to.
Timestamp when the resource was created.
Unique identifier for the object.
The custom properties associated with the object.
The timestamp when the resource was last updated.
The custom properties associated with the subscription relationship.
A recipient of a notification, which is either a user or an object.
The timestamp when the resource was last updated.
Pagination information for a list of resources.
The typename of the schema.
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page (defaults to 50).
List user preference sets
#Retrieves a list of all preference sets for a specific user.
Endpoint
Rate limit
Tier 4Path parameters
The unique identifier of the user.
Returns
A list of preference sets for the user.
Get user preference set
#Retrieves a specific preference set for a user identified by the preference set ID.
Endpoint
Rate limit
Tier 4Path parameters
The unique identifier of the user.
Unique identifier for the preference set.
Query parameters
The unique identifier for the tenant.
Returns
A preference set represents a specific set of notification preferences for a recipient. A recipient can have multiple preference sets.
An object where the key is the category and the values are the preference settings for that category.
An object where the key is the channel type and the values are the preference settings for that channel type.
An object where the key is the channel ID and the values are the preference settings for that channel ID.
Whether the recipient is subscribed to commercial communications. When false, the recipient will not receive commercial workflow notifications.
Unique identifier for the preference set.
An object where the key is the workflow key and the values are the preference settings for that workflow.
Update user preference set
#Updates a complete preference set for a user. By default, this is a destructive operation and will replace any existing preferences with the preferences given. Use 'persistence_strategy': 'merge' to merge with existing preferences instead.
Endpoint
Rate limit
Tier 3Path parameters
The unique identifier of the user.
Unique identifier for the preference set.
Request body
Controls how the preference set is persisted. 'replace' will completely replace the preference set, 'merge' will merge with existing preferences.
An object where the key is the category and the values are the preference settings for that category.
An object where the key is the channel type and the values are the preference settings for that channel type.
An object where the key is the channel ID and the values are the preference settings for that channel ID.
Whether the recipient is subscribed to commercial communications. When false, the recipient will not receive commercial workflow notifications.
An object where the key is the workflow key and the values are the preference settings for that workflow.
Returns
A preference set represents a specific set of notification preferences for a recipient. A recipient can have multiple preference sets.
An object where the key is the category and the values are the preference settings for that category.
An object where the key is the channel type and the values are the preference settings for that channel type.
An object where the key is the channel ID and the values are the preference settings for that channel ID.
Whether the recipient is subscribed to commercial communications. When false, the recipient will not receive commercial workflow notifications.
Unique identifier for the preference set.
An object where the key is the workflow key and the values are the preference settings for that workflow.
Get channel data
#Retrieves the channel data for a specific user and channel ID.
Endpoint
Rate limit
Tier 4Path parameters
The unique identifier of the user.
The unique identifier for the channel.
Returns
Channel data for a given channel type.
The typename of the schema.
The unique identifier for the channel.
Channel data for a given channel type.
The type of provider.
Set channel data
#Updates or creates channel data for a specific user and channel ID. 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
Rate limit
Tier 3Path parameters
The unique identifier of the user.
The unique identifier for the channel.
Request body
Channel data for a given channel type.
Returns
Channel data for a given channel type.
The typename of the schema.
The unique identifier for the channel.
Channel data for a given channel type.
The type of provider.
Unset channel data
#Deletes channel data for a specific user and channel ID.
Endpoint
Rate limit
Tier 3Path parameters
The unique identifier of the user.
The unique identifier for the channel.
Returns
Feeds
#A feed exposes the messages delivered to an in-app feed channel, formatted specially to be consumed in a notification feed.
A feed will always return a list of FeedItems, which are pointers to a message delivered and contain all of the information needed in order to render an item within a notification feed.
Note: Feeds are a specialized form of messages that are designed purely for in-app rendering, and as such return information that is required on the client to do so.
List feed items
#Returns a paginated list of feed items for a user in reverse chronological order, including metadata about the feed. If the user has not yet been identified within Knock, an empty feed will be returned.
You can customize the response using response filters to exclude or only include specific properties on your resources.
Notes:
- When making this call from a client-side environment, use your publishable key along with a user token.
- This endpoint’s rate limit is always scoped per-user and per-environment. This is true even for requests made without a signed user token.
- Any attachments present in trigger data are automatically excluded from both the
dataandactivitiesfields ofUserInAppFeedResponse.
Endpoint
Rate limit
Tier 2Path parameters
The unique identifier of the user.
The unique identifier for the channel.
Query parameters
The status of the feed items.
The workflow key associated with the message in the feed.
The tenant associated with the feed items.
Whether the feed items have a tenant.
The workflow categories of the feed items.
The archived status of the feed items.
The trigger data of the feed items (as a JSON string).
The locale to render the feed items in. Must be in the IETF 5646 format (e.g. en-US). When not provided, will default to the locale that the feed items were rendered in. Only available for enterprise plan customers using custom translations.
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page (defaults to 50).
Returns
A paginated list of feed items.
The list of feed items in the user's feed.
The typename of the schema.
List of activities associated with this feed item.
The typename of the schema.
The workflow trigger data payload associated with the activity.
Unique identifier for the activity.
Timestamp when the activity was created.
A recipient of a notification, which is either a user or an object.
Timestamp when the activity was last updated.
Timestamp when the feed item was archived.
Content blocks that make up the feed item.
Timestamp when the feed item was clicked.
Additional data associated with the feed item.
Unique identifier for the feed.
Timestamp when the resource was created.
Timestamp when the feed item was interacted with.
Timestamp when a link within the feed item was clicked.
Timestamp when the feed item was marked as read.
Timestamp when the feed item was marked as seen.
Source information for the feed item.
The typename of the schema.
Categories this workflow belongs to.
The key of the workflow.
The workflow version ID.
Tenant ID that the feed item belongs to.
Total number of activities related to this feed item.
Total number of actors related to this feed item.
The timestamp when the resource was last updated.
The metadata for the user's feed.
The typename of the schema.
The total number of feed items in the user's feed.
The number of unread feed items in the user's feed.
The number of unseen feed items in the user's feed.
Pagination information for a list of resources.
The typename of the schema.
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page (defaults to 50).
Additional variables for the feed item.
Get feed settings
#Returns the feed settings for a user.
Endpoint
Rate limit
Tier 4Path parameters
The unique identifier of the user.
The unique identifier for the channel.
Returns
The response for the user's feed settings.
Features configuration for the user's feed.
Whether branding is required for the user's feed.
Guides
#A Guide is a collection of steps that can be used to guide a user through a workflow.
List guides
#Returns a list of eligible in-app guides for a specific user and channel.
Endpoint
Rate limit
Tier 2Path parameters
The unique identifier of the user.
The unique identifier for the channel.
Query parameters
The tenant ID to use for targeting and rendering guides.
The data (JSON encoded object) to use for targeting and rendering guides.
The type of guides to filter by.
Returns
A response for a list of guides.
A list of guides.
The typename of the schema.
A list of URL Patterns to evaluate user's current location to activate the guide, if matched
The directive for the URL pattern ('allow' or 'block')
The pathname pattern to match (supports wildcards like /*)
A list of URL rules to evaluate user's current location to activate the guide, if matched
The value to compare against
The directive for the URL pattern ('allow' or 'block')
The comparison operator ('contains' or 'equal_to')
The variable to evaluate ('pathname')
Whether the guide is active.
The unique identifier for the guide.
The key of the guide.
The type of the guide.
A map of guide group keys to their last display timestamps.
A list of guide groups with their display sequences and intervals.
Markers for guides the user is not eligible to see.
The guide's key identifier
Human-readable explanation of ineligibility
Reason code for ineligibility
Mark guide as seen
#Records that a guide has been seen by a user, triggering any associated seen events.
Endpoint
Rate limit
Tier 2Path parameters
The unique identifier of the user.
Request body
The unique identifier for the channel.
The content of the guide.
The data of the guide.
The unique identifier for the guide.
The key of the guide.
The step reference of the guide.
Whether the guide is final.
The metadata of the guide.
The tenant ID of the guide.
Returns
A response for a guide action.
The status of a guide's action.
Mark guide as interacted
#Records that a user has interacted with a guide, triggering any associated interacted events.
Endpoint
Rate limit
Tier 2Path parameters
The unique identifier of the user.
Request body
The unique identifier for the channel.
The content of the guide.
The data of the guide.
The unique identifier for the guide.
The key of the guide.
The step reference of the guide.
Whether the guide is final.
The metadata of the guide.
The tenant ID of the guide.
Returns
A response for a guide action.
The status of a guide's action.
Mark guide as archived
#Records that a guide has been archived by a user, triggering any associated archived events.
Endpoint
Rate limit
Tier 2Path parameters
The unique identifier of the user.
Request body
The unique identifier for the channel.
The content of the guide.
The data of the guide.
The unique identifier for the guide.
The key of the guide.
The step reference of the guide.
Whether the guide is final.
The metadata of the guide.
The tenant ID of the guide.
Returns
A response for a guide action.
The status of a guide's action.
Bulk operations
#Bulk operations available for users. These endpoints return a BulkOperation that executes the job asynchronously. Progress can be tracked via the Bulk operations API.
Bulk identify users
#Identifies multiple users in a single operation. Allows creating or updating up to 1,000 users in a single batch with various properties, preferences, and channel data.
Endpoint
Rate limit
Tier 1Request body
A list of users.
A URL for the avatar of the user.
Channel-specific information that's needed to deliver a notification to an end provider.
The creation date of the user from your system.
The primary email address for the user.
The unique identifier of the user.
The locale of the user. Used for message localization.
Display name of the user.
The E.164 phone number of the user (required for SMS channels).
The timezone of the user. Must be a valid tz database time zone string. Used for recurring schedules.
Returns
A bulk operation entity.
The typename of the schema.
Timestamp when the bulk operation was completed.
The number of failed operations.
A list of items that failed to be processed.
The collection this object belongs to.
Unique identifier for the object.
The estimated total number of rows to process.
Timestamp when the bulk operation failed.
Unique identifier for the bulk operation.
Timestamp when the resource was created.
The name of the bulk operation.
The number of rows processed so far.
The URI to the bulk operation's progress.
Timestamp when the bulk operation was started.
The status of the bulk operation.
The number of successful operations.
The timestamp when the resource was last updated.
Bulk set preferences
#Bulk sets the preferences for up to 1,000 users at a time. The preference set :id can be either default or a tenant.id. Learn more about per-tenant preferences. Note that this is a destructive operation and will replace any existing users' preferences with the preferences sent.
Endpoint
Rate limit
Tier 1Request body
A request to set a preference set for a recipient.
Controls how the preference set is persisted. 'replace' will completely replace the preference set, 'merge' will merge with existing preferences.
An object where the key is the category and the values are the preference settings for that category.
An object where the key is the channel type and the values are the preference settings for that channel type.
An object where the key is the channel ID and the values are the preference settings for that channel ID.
Whether the recipient is subscribed to commercial communications. When false, the recipient will not receive commercial workflow notifications.
An object where the key is the workflow key and the values are the preference settings for that workflow.
A list of user IDs.
Returns
A bulk operation entity.
The typename of the schema.
Timestamp when the bulk operation was completed.
The number of failed operations.
A list of items that failed to be processed.
The collection this object belongs to.
Unique identifier for the object.
The estimated total number of rows to process.
Timestamp when the bulk operation failed.
Unique identifier for the bulk operation.
Timestamp when the resource was created.
The name of the bulk operation.
The number of rows processed so far.
The URI to the bulk operation's progress.
Timestamp when the bulk operation was started.
The status of the bulk operation.
The number of successful operations.
The timestamp when the resource was last updated.
Bulk delete users
#Permanently deletes up to 1,000 users at a time.
Endpoint
Rate limit
Tier 1Request body
A list of user IDs.
Returns
A bulk operation entity.
The typename of the schema.
Timestamp when the bulk operation was completed.
The number of failed operations.
A list of items that failed to be processed.
The collection this object belongs to.
Unique identifier for the object.
The estimated total number of rows to process.
Timestamp when the bulk operation failed.
Unique identifier for the bulk operation.
Timestamp when the resource was created.
The name of the bulk operation.
The number of rows processed so far.
The URI to the bulk operation's progress.
Timestamp when the bulk operation was started.
The status of the bulk operation.
The number of successful operations.
The timestamp when the resource was last updated.
User
#A User represents an individual in your system who can receive notifications through Knock. Users are the most common recipients of notifications and are always referenced by your internal identifier.
Attributes
The typename of the schema.
A URL for the avatar of the user.
The creation date of the user from your system.
The primary email address for the user.
The unique identifier of the user.
Display name of the user.
The E.164 phone number of the user (required for SMS channels).
The timezone of the user. Must be a valid tz database time zone string. Used for recurring schedules.
The timestamp when the resource was last updated.
Any additional custom properties.
IdentifyUserRequest
#A set of parameters to identify a user with. Does not include the user ID, as that's specified elsewhere in the request. You can supply any additional properties you'd like to upsert for the user.
Attributes
A URL for the avatar of the user.
Channel-specific information that's needed to deliver a notification to an end provider.
The creation date of the user from your system.
The primary email address for the user.
The locale of the user. Used for message localization.
Display name of the user.
The E.164 phone number of the user (required for SMS channels).
The timezone of the user. Must be a valid tz database time zone string. Used for recurring schedules.
Any additional custom properties.
InlineIdentifyUserRequest
#A set of parameters to inline-identify a user with. Inline identifying the user will ensure that the user is available before the request is executed in Knock. It will perform an upsert for the user you're supplying, replacing any properties specified.
Attributes
A URL for the avatar of the user.
Channel-specific information that's needed to deliver a notification to an end provider.
The creation date of the user from your system.
The primary email address for the user.
The unique identifier of the user.
The locale of the user. Used for message localization.
Display name of the user.
The E.164 phone number of the user (required for SMS channels).
The timezone of the user. Must be a valid tz database time zone string. Used for recurring schedules.
Any additional custom properties.