Identifying recipients

To send notifications to a recipient (or to reference a recipient as an actor in a notification), Knock needs the recipient's data to be stored in Knock. This process is known as identifying and works across user and object recipients.

There are three different methods to identify recipients:

• Individual identification
• Bulk identification
• Inline identification

In this guide we discuss each of these methods.

You can use the individual identification API to upsert a single recipient's data into Knock. The individual identify API is useful to ensure that user data is updated on an ongoing basis, like when a user updates their profile information inside of your product and you need to ensure it's reflected within Knock.

API reference ->

While identifying individual recipients is useful, you may also need to identify multiple recipients at once. This can be useful when you're importing data into Knock to get started.

API reference ->

It's also possible to inline identify recipients while issuing calls to certain resources within Knock. Inline identifying will always upsert the recipients being passed in before executing the remainder of the request. This can be useful for ensuring that your recipients exist within Knock before executing calls that reference those recipients.

You can also inline identify actors in the same way.

Inline identification works with any endpoint that accepts a list of recipients:

• Workflow triggers
• Subscriptions
• Schedules

API reference ->

When passing a set of recipients to be inline identified, Knock will guarantee that the recipients are identified before any other action is executed. That makes it possible to lazily create recipients within Knock using inline identification, only creating them when needed.

When identifying recipients you pass a set of properties for the recipient that are persisted. No properties on the recipient are required except for id. Generally, the best practice here is to use your internal identifier for your users as the id.

There are some reserved property names for recipients that have special meaning:

• name: The given name of the recipient
• email: A valid email address to deliver email notifications to
• locale: A locale code for the recipient, used for internationalizing content
• phone_number: A E.164 compliant phone number field used when sending SMS messages
• created_at: An ISO-8601 datetime of when the recipient was created

A recipient also accepts any number of custom properties, which are key-value pairs that you define. It's useful to store custom properties on your recipients so that you can reference these attributes when sending notifications, or for use in message templates.

It's also possible to set preferences and channel data for a recipient during the identification process.

Preferences are passed as a dictionary under the preferences key, where the key represents the preference set id:

Channel data is passed as a dictionary under the channel_data key, where the key represents the channel id:

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.

Below we discuss some common scenarios to consider.

When you're first getting started with Knock, you'll likely have a number of existing recipients that you want to migrate into Knock. If you're looking to get started with Knock quickly, you can use inline identification to start calling your workflows without any prerequisite calls to the Knock API.

If you first want to get all your recipients into Knock, the easiest path forward would be via our bulk identification flow.

Once you've migrated your current recipients into Knock, you'll want to continue to update this data in Knock for two key cases:

1. When new recipients sign up for your product.
2. When Knock-relevant data about a user changes, like a name or an email address.

One common approach is to make subsequent calls to the Knock's user identify API following such events. For example, you could do this via a deferred job in your 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.