Providing relevant and timely customer interactions relies on fresh and accurate data in your Braze account. By automatically syncing customer data from your data warehouse into Braze, you don't need to worry about data consistency or staleness. Instead, you can focus on building world-class customer experiences.
The permissions the API key needs depend on what you plan on syncing.
Sync Type
Required permissions
Users
users.track, users.export.ids, users.delete (optional if you want to rely on Hightouch for user deletions), users.alias.update (if you are updating existing users)
To find the your Braze region, use the table below.
URL
Region
https://dashboard-01.braze.com
iad-01.braze.com
https://dashboard-02.braze.com
iad-02.braze.com
https://dashboard-03.braze.com
iad-03.braze.com
https://dashboard-04.braze.com
iad-04.braze.com
https://dashboard-05.braze.com
iad-05.braze.com
https://dashboard-06.braze.com
iad-06.braze.com
https://dashboard-07.braze.com
iad-07.braze.com
https://dashboard-08.braze.com
iad-08.braze.com
https://dashboard-01.braze.eu
fra-01.braze.eu
https://dashboard-02.braze.eu
fra-02.braze.eu
Refer to the Braze endpoint
documentation
to view additional regions. To derive the region, remove the prefix
"https://rest" from the respective value in the REST ENDPOINT column.
Once you've set up your Braze destination and have a model to pull data from, you can set up your sync configuration to begin syncing data. Go to the Syncs overview page and click the Add sync button to begin. Then, select the relevant model and the Braze destination you want to sync to.
Hightouch supports syncing rows from your model to Braze users. This integration supports both Upsert and Update modes. In Upsert mode, Hightouch inserts new users into Braze, with all attributes kept up-to-date. In Update mode, Hightouch updates attributes on users that already exist in Braze.
Hightouch automatically normalizes some user data fields to meet Braze's specifications.
In Upsert mode, you can match records from your source to your Braze workspace using the Braze External User ID. In Update mode, you can also match records based on Braze ID or a user alias object.
If you match records with a column other than the primary key of your
model, changes in the model column used for record matching will not be
reflected in Braze. This is to ensure duplicate records are not created in
Braze.
When syncing a large amount of rows, make sure to match the records using
Braze External User ID instead of Braze ID. Using the Braze ID requires more
requests which often results in slower sync speeds. See the slow initial sync
section for more details.
You can sync columns from your source to Braze's default and custom fields. If you send data for a custom field that doesn't exist, Hightouch adds the field and automatically detects its type.
You can manage your custom fields in Manage App Group > Custom Attributes in Braze.
You can also map your model columns to user aliases in Braze.
This configuration only appears if you select Braze External ID for record matching.
Braze supports user attributes containing JSON objects or object arrays. These objects and object arrays are commonly used to support "entities" related to each user—for example, devices, medications, pets, etc.—especially when marketing communication needs to include metadata about these related entities.
Hightouch is a great tool to sync to these types of attributes because you can leverage your data warehouse to manage these associations. To do so, you must build the full JSON object into a single column within your Hightouch data model.
Modeling nested attributes into JSON can be done directly in your warehouse with something like dbt, or you can use SQL functions appropriate for your data warehouse and build these objects within the SQL Editor in Hightouch.
Let's say you want an array of a customer's pets to be an attribute named pets in Braze. You would need a data model with a column named pets and would then build the full JSON pets object array to populate that column. This array might look something like this:
Hightouch supports syncing events to Braze and assigning them to a user. You can send two event types to the Braze destination:
Track Event: Sends events of a particular name when a record is added
Track Purchase: Track when a customer makes a purchase
To ensure syncs send each event, your event model must use a truly unique primary key. See the events syncs documentation for more information.
Hightouch lets you choose whether to create users that don't exist. For example, if you are tracking an event associated with user A and user A doesn't exist in Braze, you can either create the user or ignore the event.
Hightouch can match events to users on different Braze fields. If you are creating users that don't exist, you can only match on Braze External ID or User Alias Object. Otherwise you can match on Braze External ID, User Alias Object, or Braze ID.
For track event type events you can alse send the event name and event timestamp. Track purchases don't require an event name.
Hightouch accepts a standard date time format for the timestamp and
automatically converts it to the format Braze requires.
Hightouch supports syncing users to both Email and SMS subscription groups.
Braze has a designated set of fields to manage subscription group opt-ins independent of user attributes.
Hightouch supports syncing to existing subscription groups within Braze. You can enter a static subscription group ID or select a column from your model containing the subscription group ID.
Read Braze's
docs
for information on creating a subscription group.
Hightouch supports merging alias-only "anonymous" users with "known" Braze users with an external ID.
It's common to have “soft-signup” workflows where all you collect from a user is an email or phone without forcing the user to create an account. This workflow results in users where all you may have is PII. When they create an account, you need to use this endpoint to “identify” these users with a new login ID.
For example, your workflow might look like this:
A user visits your website or app. The user doesn't have a Braze ID to start with—they only enter an email address, phone number, or some other PII. You create a user in you customer database, and an alias-only user profile in Braze via the Braze SDK. Hightouch isn't involved at this point.
You can use Hightouch to send user attributes or user-related events to Braze via Hightouch by matching on a user alias object, since there isn't an external ID yet. You must use Update mode.
Once you have a unique user ID in your customer database, you can use Hightouch to call Braze's Identify endpoint to "identify" the alias-only user using your unique user ID as the external ID in Braze. This merges the alias-only user in Braze with a known Braze user. If an external ID doesn't exist when using the Identify endpoint, Braze creates the external ID and the alias-only user is considered “identified.”
All subsequent updates to the user should be done in Hightouch using the external user ID, not the user alias.
Hightouch lets you map your Braze aliases to known users using the alias label and value.
If you're adding a JSON object directly to your model, each user_alias object should consist of alias_label and alias_name as top-level attributes, rather than nested in another object.
Hightouch supports syncing rows from your models to your existing catalog through the Braze Catalogs API.
Braze's Catalog endpoint is in early access. Contact your Braze account
manager if you are interested in participating.
You can choose to create a new Braze catalog the first time the
sync runs or use an existing catalog. If creating a new catalog, you can name the catalog from Hightouch. If you leave this field blank, the name defaults to the
model name.
With the Create a new catalog option enabled, Hightouch only creates a
catalog the first time the sync runs. Hightouch doesn't modify the catalog
name after the first run. If you want to change the name or fields, you have
to create a new catalog using a new sync.
Syncing to catalog items allows either Upsert and Update modes. In Upsert mode, Hightouch inserts new catalog items into the Braze. In Update mode, Hightouch updates fields on catalog items that already exist in Braze.
If you are using an existing catalog, you can test your sync by syncing a single row. You can verify that a row was successfully synced by going to your Catalog and finding the synced row by its catalog item ID. If you are automatically creating a catalog, it's not possible to test by row.
Hightouch lets you use records from your models to trigger campaigns through the Braze Campaign API.
Once configured, your Hightouch sync triggers your campaign once rows appear in your model. Hightouch triggers your campaign for every row in your model the first time you run the sync, whenever you do a full resync, and for every new row added to your query results in subsequent syncs.
This destination lets you trigger a campaign for your Braze users based on their external user ID.
This destination doesn't check for duplicates. Hightouch recommends that you
set delivery
controls
in Braze to prevent duplicated campaign messages in case your source has
duplicates.
This destination allows you to create or update users when you trigger a campaign. To create new users, just uncheck the setting in the sync and map the user properties.
Note: Mapping user propterties when using this setting is required
Hightouch recommends that you test with your email before running an actual sync for your users.
You can test by following these steps:
Create a Google Sheet with a valid external_id and your email. You will use this to sync yourself as user in Braze. See Braze's user ID convention if you are unfamiliar with external_id.
You can use the same sync to remove yourself from Braze once your testing
is complete. Set the sync configuration's delete mode to "Delete
destination record associated with source record," remove yourself from the
source sheet and rerun the sync.
Build your campaign in Braze. See Braze's guide on how to build a campaign for more information. When setting up your campaign schedule, make sure to select API-triggered Delivery.
Set up your campaign trigger sync and run it on Hightouch.
Verify that you are able to receive your campaign message. If you need to make corrections and thus want to re-run the sync, click Resync full query next to the Run button. Also note that your re-eligibility settings in Braze campaign must be loosely set for you to re-trigger the sync and actually receive the email.
Hightouch lets you use records from your models to trigger Canvases through the Braze Canvas API.
Once configured, your Hightouch sync triggers your Canvases once rows appear in your model. Hightouch triggers your Canvases for every row in your model the first time you run the sync, whenever you do a full resync, and for every new row added to your query results in subsequent syncs.
Before you can set up a Hightouch sync to trigger a Canvas, you need set up an API-triggered Canvas in Braze. See Braze Ideas & Strategies for more information and best practices.
Hightouch can only trigger Canvases that are
API-triggered.
Only non-archived, active canvases are available in sync configuration.
This destination allows you to customize your messages via Canvas entry properties. Hightouch automatically lists Canvas entry properties you can map values to.
See Braze's docs on using the templated content included with an API request for more information.
This destination allows you to create or update users when you trigger a Canvas. To create new users, just uncheck the setting in the sync and map the user properties.
Note: Mapping user properties when using this setting is required
Hightouch only syncs data that needs updating to minimize the number of API requests made to your destinations. Braze pricing is based on data points, which count the number of updates you (and Hightouch) make. These are some key points to understand how Hightouch syncs affect your Braze data point consumption:
When syncing arrays without nested objects, you consume one Braze data point per API call:
Creating an array consumes one data point.
Updating arrays consumes one data point per value updated.
When syncing arrays of objects, you may consume multiple data points with one API call:
Creating an array of objects consumes one data point per attribute added within each object. For example, creating two pet objects with four attributes each (id, type, color, and size) consumes eight data points.
Updating an array of objects consumes one data point per attribute changed.
Removals consume one data point per removal criteria. For example, removing objects where id = 4 removes one object and costs one data point. Removing objects where type = dog may remove many objects but still only consumes one data point.
When syncing records that don't exist in Braze, Hightouch updates all mapped attributes with the values from your query results. This means you consume one data point per attribute per created record.
When syncing new records in the model that already exist in Braze, Hightouch first gets the user attributes from Braze, calculates which columns actually changed, and then only sends the changes for those columns. Each updated attribute equals one data point consumed.
When syncing records that have been previously synced to Braze, Hightouch compares the new record's columns to the previously sent record's columns, calculates which columns actually changed, and then only sends the changes for those columns. Each updated attribute equals one data point consumed.
Hightouch sync strategy aims for the lowest Braze data point consumption
possible. Because we make a GET request to first see what user attributes
haven't changed since the last sync, sync speed is slower than other methods
which overwrite all data in Braze and consume more data points.
If you're using a Braze ID to match user records, your initial sync may be slow. When Hightouch updates Braze with new records or fields, we query users in Braze for change data capture.
Braze allows batch searches on external IDs, but only allows querying for one user at a time if using Braze IDs. That means Hightouch needs to make a separate request for each user if using Braze IDs.
It's best to match records on external ID rather than Braze ID. This speeds up the initial sync and limits the number of requests to make to Braze.
When updating an attribute's value in a nested object to null, Braze's API doesn't let you combine this change with other non-null updates. Therefore, when updating values to null, Hightouch sends the full nested object with the _merge_objects parameter set to false.
Setting _merge_objects to true deep merges your update with the existing object data. See the Braze API documentation for more details.
This means the same user may require two update actions:
Updates to nested objects with non-null values with _merge_objects:true
Updates setting one or more attributes in nested objects to null with _merge_objects:false
This error can happen if the phone numbers you're syncing to Braze are being marked as invalid because of provider errors or because they're deactivated. It might also happen if a number is on an opt-out list or if it's already taken by another user in Braze.
Hightouch provides complete visibility into the API calls made during each of your sync runs. We recommend reading our article on debugging tips and tricks to learn more.