Docs

Integrations

Sources

Census

How to integrate Census with Knock

Learn how to power your Knock product notifications using synced data from your data warehouse using Census.

Getting started

Knock can be integrated as a downstream destination in Census to sync customer and event data from your data warehouse.

Use cases

You can use our Census integration to:

Sync customer data into Knock from your data warehouse (identify recipients).
Trigger workflows from records added, changed, or removed in your data warehouse.
Populate audiences with data from your data warehouse. Audiences can be used to trigger workflows or power conditional logic during workflow execution.

Configure Knock as a destination in Census

Before you can sync data into Knock from Census, you need to configure Knock as a destination.

Prerequisites

Determine which Knock environment you want to sync your Census data to. You most likely want to sync in the Production environment, unless you’re configuring a test sync.
Have your Knock environment’s secret API key ready. Each environment has its own unique set of API keys; you can find your secret API key in your dashboard under Platform > API keys. Be sure that the correct environment is selected in the switcher at the top of the page.
Choose your destination type. Your options are:

Custom destination - Our recommended destination type for syncing audiences into Knock from Census. Setup is simpler and includes automatic support for removing a user from an audience during your syncs without additional configuration.
HTTP Request destination - This destination type is required if you need to sync users and their properties to Knock or if you need to include tenant data in your Knock audience.

Configuration instructions

Add destination

Navigate to the Destinations tab in Census and click "Add a Destination."

Select destination type

Select "Custom Destination API."

Configure the destination

a. Input a destination name. We recommend something like Knock Production that correlates to the Knock environment that you're syncing to.

b. Copy and paste the following into the API URL field:

c. Click the "+ Add Header" button to add an Authorization header. Be sure to toggle the "Secret" setting for the value:

Header	Value
`Authorization`	`Bearer <your Knock secret API key>`

d. Leave “1” selected as the API Version, then click "Connect" to complete the configuration.

Census will now test connectivity with Knock. This process may take a few moments to complete.

Add destination

Navigate to the Destinations tab in Census and click "Add a Destination."

Select destination type

Select "HTTP Request."

Configure the destination

a. Input a destination name. We recommend something like Knock Production HTTP API that correlates to the Knock environment that you're syncing to.

b. Leave the Authorization Type set to "Manual."

c. Copy and paste the following into the Base URL field:

d. Click the "+ Add Header" button to add an Authorization header. Be sure to toggle the "Secret" setting for the value:

Header	Value
`Authorization`	`Bearer <your Knock secret API key>`

e. Click "Connect" to complete the configuration.

Syncing audiences into Knock from Census

Census Sources and Datasets can be synced to Knock audiences by configuring Knock as a custom destination or using an HTTP request destination connected to Knock’s audiences API.

Prerequisites

Complete the steps to configure Knock as a destination in Census.
Create, save, and commit a static audience in Knock that will serve as the target for your sync. Be sure that you create your audience in the same environment that you used to configure your Knock destination.
Ensure that any Knock workflows that should be triggered by a user's audience entry are configured, committed, and promoted to your Knock environment before finalizing your Census sync.

Add an audience sync to your Knock destination

Follow the steps below to add an audience sync to your configured Knock destination in Census.

Create a new sync

Navigate to the Syncs tab in Census and click "Create a sync."

Select your source data

You'll be prompted to select a dataset for your source data. Select the dataset that you want to sync to Knock.

Select a destination

Next, you'll select the Knock custom destination that you created above. The "Audiences" object should be selected by default.

Select a sync behavior

Select the sync behavior that you want to use.

Create only: New rows added to your model will be synced to Knock. Removing rows from your model will have no effect on your Knock audience.
Mirror: New rows added to your model will be added to your audience and removed rows in your model will be deleted from your audience.

Select a sync key

Select a sync key from your source to map to the Knock audience User ID field. This field's value must be unique; if Census detects multiple rows with the same sync key value, it marks them as duplicates and does not sync them.

Add the audience key

Under "Set Up Custom Destination API Field Mappings," you'll add the key of the Knock audience that you want to sync to.

a. Click the "Source value..." dropdown.

Select the source value input for your audience key

b. Click "Constant Value" on the left-hand side, then enter the key of your Knock audience in the input field.

c. Click "Save."

Test your sync (optional)

We recommend clicking "Run test" to test your sync. If successful, this will sync one row of data to your Knock audience, which you can confirm in the Knock dashboard. Any errors with your source data or field mappings will be displayed in the test results.

Finalize your sync

Click "Next." You'll be prompted to provide an optional label and select the trigger type for your sync.

Click "Create" to complete the sync creation process.

Create a new sync for adding users to an audience

Navigate to the Syncs tab in Census and click "Create a sync."

Select your source data

You'll be prompted to select a dataset for your source data. Select the dataset that you want to sync to Knock.

Select a destination

Next, you'll select the Knock HTTP request destination that you created above.

Enter the following into the request endpoint input, replacing <audience-key> with the key of your destination audience. For example, if your audience key is new-signups, you’d enter /audiences/new-signups/members.

Select the request trigger type

Select "Records added" as the trigger type.

Set the request trigger type to 'Records added'

Specify the number of records in each request

Select "Multiple records per request" to sync audience members in batches. Set the number of rows per batch to 500.

Select a sync key

Choose a request method and payload type

Select POST as the request method.

Then, select "JSON" as the payload type and "Template editor" as the customization option.

Select the JSON payload type with template editor option

Configure the request body template

Modify the following template, replacing source_user_id and source_tenant_id with the names of columns from your data source that map to the Knock user ID and the Knock tenant ID. Then paste it into the JSON payload form.

Note that column names are case-sensitive.

Configure a rate limit for the sync

The rate limit for “Add member” API requests to Knock is 60 requests per second. We recommend choosing a lower number (such as 10 requests per second) to allow for multiple syncs to run at once.

Choose whether to backfill existing records

Select "Backfill All Records" to sync all existing records in your source data to your Knock audience, or "Skip Current Records" to only sync new records going forward.

Test your sync (optional)

Finalize your sync

Click "Next." You'll be prompted to provide an optional label and select the trigger type for your sync.

Click "Create" to complete the sync creation process.

If you want your audience sync to run in “insert only” mode, you’re all set! If you’d like to also remove audience members when rows are deleted from your data source, proceed to the next step.

Create an optional sync for removing audience members

Repeat steps 1. and 2. above, using the same source data and your Knock HTTP request destination.

When you get to step 3., paste the following into the request endpoint, with replacements:

audience_key should be the same audience key used in the previous section.
source_user_id should be the name of the column that stores Knock user IDs.
source_tenant_id should be the name of the column that stores Knock tenant IDs.

Configure the request

a. Select "Records removed" as the trigger type.

b. Select "One record per request" to remove audience members one at a time.

c. Select the same sync key as the one that you used in your "Add member" sync.

d. Select DELETE as the request method. The payload type will be "empty" for this request method.

e. Configure a rate limit for the sync. The same 60 requests per second rate limit as your "add member" sync applies to this endpoint, and we recommend a similar setting to allow for multiple syncs to run at once.

Test and finalize your sync

As above, we recommend clicking "Run test" to test your sync. If successful, this will remove one row of data from your Knock audience, which you can confirm in the Knock dashboard. Any errors with your source data or field mappings will be displayed in the test results.

Click "Next." You'll be prompted to provide an optional label and select the trigger type for your sync.

Click "Create" to complete the sync creation process. Your setup is now complete!

Syncing customer data into Knock from Census

Census user records can be synced to Knock by configuring an HTTP request destination connected to Knock’s users API.

Prerequisites

Complete the steps to configure Knock as a destination in Census. You'll need to configure an HTTP Request destination.

Add a user sync to your Knock destination

Follow the steps below to add a user data sync to your configured Knock HTTP request destination in Census. These instructions leverage our bulk identify endpoint to optimize migrating large numbers of user records to Knock, but you can adapt this approach to use our identify endpoint for ongoing syncs of individual user records.

Create a new sync

Navigate to the Syncs tab in Census and click "Create a sync."

Select your source data

You'll be prompted to select a dataset for your source data. Select the dataset that you want to sync to Knock.

Select a destination

Next, you'll select the Knock HTTP request destination that you created above.

Enter the following into the request endpoint input:

Select the request trigger type

Select either "Records added" or "Records added or changed" as the trigger type. If you only plan to run a one-time sync to migrate your user data to Knock, your selection doesn’t matter. Ongoing syncs should use "Records added or changed" to ensure that updated user records are synced to Knock.

Specify the number of records in each request

Select "Multiple records per request" to sync audience members in batches. Set the number of rows per batch to 1000.

Select a sync key

Choose a request method and payload type

Select POST as the request method.

Then, select "JSON" as the payload type and "Template editor" as the customization option.

Configure the request body template

Define a template for your request body. The only required Knock field is id. To reference source columns, use the {{ record['source_column_name'] }} syntax. Note that column names are case-sensitive.

Here is an example template that identifies id, name, email, and favorite_color attributes in Knock using the columns from your source data:

Configure a rate limit for the sync

The rate limit for bulk identify API requests to Knock is 1 request per second.

Choose whether to backfill existing records

Select "Backfill All Records" to sync all existing user records in your source data to Knock, or "Skip Current Records" to only sync new user records going forward.

Test your sync (optional)

We recommend clicking "Run test" to test your sync. If successful, this will sync one user to your Knock environment, which you can confirm in the Knock dashboard. Any errors with your source data or field mappings will be displayed in the test results.

Finalize your sync

Click "Next." You'll be prompted to provide an optional label and select the trigger type for your sync.

Click "Create" to complete the sync creation process.