Identifying recipients

Docs

Platform

Managing recipients

Learn more about how to identify your user and object recipients to power your notifications.

To send notifications to a recipient or reference them as an actor in a notification, their data must be stored in Knock. This process is called identifying and works across user and object recipients.

Recipient properties enable Knock to deliver personalized notifications. Properties like email and phone_number are essential for message delivery, while name and custom properties power personalization in your notification content and workflow logic. Properties like timezone and locale enable you to design mindful notifications for users around the world via send windows and translations. Knock also tracks delivery and engagement analytics for each identified recipient, giving you insights into notification performance and user behavior.

There are three ways to identify recipients:

Direct identification. Make a single server-side API request (PUT /v1/users/{user_id}) to upsert one recipient.
Inline identification. Upsert recipients by including recipient data in other server-side API requests (e.g., POST /v1/workflows/{workflow_key}/trigger) or when initializing the KnockProvider client-side.
Bulk identification. Make a single server-side API request (POST /v1/users/bulk/identify) to upsert many recipients at once.

Direct identification

Make a server-side API request to upsert a single recipient in Knock. This is useful to ensure that recipient data is updated on an ongoing basis, like reflecting updates to user information or changes to object properties in your system.

API reference ->

Inline identification

You can also identify recipients during other operations, eliminating the need for separate identification API calls.

When using inline identification, Knock guarantees that recipients are identified before executing any other action. This enables lazy recipient creation within Knock and ensures that your recipients exist within Knock before executing calls that reference them. Inline identification is available server-side for both users and objects, and client-side for users only.

Inline identification requires a list of recipient objects where each object must include an id, but may include other properties to be upserted.

Server-side, inline identification works with any endpoint that accepts a list of recipients:

API reference ->

Client-side identification is handled automatically when you initialize the KnockProvider with user data provided. When mounted, the provider will identify the user in Knock by upserting the provided user information.

This approach is particularly useful for in-app UI components like feeds and guides, where user data is immediately required in your frontend application. Note that client-side identification is currently only available for users.

Bulk identification

The bulk identification endpoint enables you to upsert many recipients in a single server-side request. This is ideal for initial data imports or large-scale updates.

API reference ->

Setting recipient properties

When identifying recipients, you pass a set of properties that are persisted. We recommend using your internal user identifier for the id value, which is the only required property. Although additional properties aren't required for identification, some properties such as email or phone_number are required for certain channel steps.

Reserved properties

Recipients have some reserved property names:

Property	Description
`name`	The name of the recipient.
`email`	A valid email address to deliver email notifications to.
`avatar`	A URL for the avatar of the recipient.
`locale`	A locale code for the recipient, used for internationalizing content.
`phone_number`	An E.164 compliant phone number field used when sending SMS messages.
`timezone`	A valid tz database time zone string used for send windows and schedules.
`created_at`	An ISO-8601 datetime indicating when the recipient was created. Note: This is an optional property that you must explicitly set from your system - Knock does not handle this implicitly and it will be `null` unless provided.

Custom properties

Recipients also accept any number of custom properties as key-value pairs that you define. Custom properties enable you to reference recipient attributes when sending notifications.

When to identify

Knock provides a flexible set of APIs for you to manage your user data as you scale with us. Ultimately, it's up to you to decide upon the best approach for how you manage your user data with Knock.

Initial setup

When getting started with Knock, you'll likely have existing recipients to migrate into Knock:

Quick start. Use inline identification to start calling your workflows without any prerequisite calls to the Knock API.
Data import. Use our bulk identification to import all recipient data into Knock first.

Ongoing updates

After identifying your current recipients in Knock, you'll want to continue to update this data when:

New recipients sign up for your product.
Knock-relevant data (e.g., name or email) about a user changes.

A common approach is making subsequent calls to Knock's user identify API following such events. Many customers do this via a deferred job in their backend systems.

Another option is to offload these updates to your workflow trigger calls via inline identification. If you always send Knock the full set of data for your recipients via workflow trigger calls, you can keep your user data up to date in Knock without any additional handling on your end.

Frequently asked questions

A common mistake when implementing inline identification is accidentally passing a list of user ID strings instead of user objects. Inline identification requires user objects (even if they only contain an id property), not ID strings.

Yes, preferences can be set during identification, but it's important to understand the implications. Unlike our preferences endpoints, setting preferences during identification will perform a deep merge of the provided preferences into any existing preferences (just like any other properties stored on the recipient). Unless you intend to leverage this behavior for a specific use case, we generally recommend updating preferences directly via the preferences endpoints.

To set preferences during identification, provide a dictionary under the preferences key with each key representing a preference set ID. Unlike the preferences endpoints, setting preferences during identification requires explicitly providing the default preference set key when updating default preferences.

For workflow triggers with inline identify, one or more preference sets (including per-tenant preferences) can be upserted by passing a dictionary of PreferenceSets.

API reference ->

Yes, channel data can be set during identification by passing a dictionary under the channel_data key, where each key represents the channel ID and the value contains the channel-specific data.

This is particularly useful for setting push notification tokens, device information, or other channel-specific configuration data when identifying users.