This page describes how to use Census with Braze.
In this guide, we will show you how to connect Braze to Census and create your first sync.
- Have your Braze account ready, with create access for Braze API keys.
Braze lets you create a number of API keys, each with their own set of permissions. You'll almost certainly want to create a new API key for Census rather than reusing an existing one.
Within Braze's left navigation bar, scroll down to the very bottom. Under App Settings and click Developer Console.
Then, inside the API Settings tab, under Rest API Keys, click + Create New API Key.
Provide a name you'll recognize ("Census" is a good choice) and select the following permissions:
- All User Data permissions, except for
- This permission set may change as we add support for more Braze objects so you may want to grant more permissions now or plan to update these permissions in the future.
Scroll down and click Save API Key.
Finally, copy the long code you see under Identifier. We'll use that in a minute.
Braze requires that we use a slightly different URL to access your account depending on where it's been set up. See the full list of all Braze API Endpoints. In general, you just need the number from the URL you see in your browser when you're signed into Braze. For example, if your Braze URL is https://dashboard-03.braze.com/, then your API Endpoint should be https://rest.iad-03.braze.com.
When syncing to Braze Cohorts you need to provide your Data Import key. To find this key login to your instance in Braze and navigate to Technology Partners under Integrations and then select Census. You will find your Data Import Key and your Rest Endpoint here. Paste those values into the respective credential fields when setting up the connection.
Census Technology Partner page in Braze
Great! Now let's pull it all together.
- 2.You can provide whatever name you like for the connection
- 3.Provide the appropriate Braze Endpoint URL
- 4.Copy and paste your new Braze API key
After the Connection Test is Green, you're all set and ready to get syncing! 🎉
Census currently supports syncing to the following Braze objects.
Census offers a way to manage your Braze Subscription Groups via your data hub. The current behavior is that you are to "Mirror" the subscribed users from your user base. It is required that you have, within the source:
- The Subscription Group Id in Braze
- Braze User External Id
This source model should be all of your Subscribed users for their Subscription groups. If a previously-synced subscription group / user pair no longer appears in your data source, Census will unsubscribe that user from that subscription group.
Only the Braze User External Id and the Subscription Group Id should be mapped fields. This is a special unsubscribing mirror for user/group pairs that no longer appear in the data source.
Braze Cohorts allow users of Census to define and sync user cohorts between Census and Braze. To get started make sure your data import key is set on the connection. Then when creating a new sync to Braze select User & Cohort as destination object.
Braze Sync Configuration for User & Cohort
Select the source column for identifying users that you want to add to a Cohort. Right now we can only identify Braze users for Cohorts by External User ID. Then select what Cohort you would like to sync to. You can select an existing Cohort from the dropdown list, define a new Cohort, or select a source column to dynamically get the Cohort name value.
If you want a user to be removed from the Cohort if they are removed from the source dataset then select remove matching record from cohort from the dropdown.
Cohort Sync Editor Configuration Panel
Finally, add any User fields to the mapper. During a sync any fields that you map will first be synced to the User object to update what already exists in Braze and then the updated User will be added to the specified Cohort. Now you can run your sync!
Once you have synced to a Braze Cohort you can take advantage of it in Braze by navigating to Engagement > Segments and then either create a new segment or select an existing one. In the Braze Segment builder you can then add a new filter and select Census Cohorts from the dropdown. The cohorts that you've created in Census will be available here and any Users in those segments will automatically have the correct filtering logic applied.
Census Cohorts custom filter in Braze
Census Cohort custom filter in Braze
Braze's Mirror behavior optionally supports a choice of two actions when a record is removed from the source. This can be configured when setting up the sync initially. The first time the sync is performed, the records will be used as a basis for mirroring behaviour in future syncs:
- Delete record - This is the typical behavior for most mirror syncs. When a record is removed from the source, the corresponding record will be deleted from Braze.
- Null out fields - This is a new behavior for mirror syncs in Braze. In this case, when a record is removed from the source, the currently mapped fields of the synced will be removed from the destination record (by setting them to Null). The identifier will not be removed from the destination record.
Regardless of which option is selected, mirror syncs identify deletions of each type by comparing against the data they have already sent -- not the data that might or might not already exist in Braze. This means that the first sync will be an upsert for all records, and the second and following syncs will account for deletions from the source data.
In order to minimize your API usage with Braze to ensure that your organization is only updating the data points that have actually changed, Census exports the mapped fields from Braze and scans the data in your data source (including on Full Syncs). If there is a difference, Census will send that data point over from the source. If there is not, Census will not send that data point write over.
With Census, you know have the ability to specify which Data Type your syncs are referring to. When you change the data type, the next Census sync will be a full sync. If the Census destination field data types match up with the Braze data types, Census will perform the Braze export and comparison with your data.