Search documentation...



Build better campaigns on Braze with up-to-date customer data from your data warehouse

It's important to be aware of Braze's data point consumption model when setting up Hightouch syncs. Refer to the section on syncing and data point consumption to understand how Hightouch syncs affect your Braze data point consumption.


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.

Supported syncing

Object TypeDescriptionSupported Sync Modes
UsersSync records to Braze usersUpsert, Update
EventsSend track events and track purchase type events to BrazeInsert
Subscription statusUpdate subscription groups with data from your sourceUpdate
User identificationMerge your alias-only users with an identified profile and remove the alias-only profileInsert
Catalog itemsSync records to relevant catalogsUpsert, Update
Campaign triggersTrigger campaign with context from your recordsInsert

Getting started

Connecting Braze to Hightouch requires an API Key and Region.

API key

To find the API key, navigate to Developer Console > API Settings in Braze and create an API key.

Finding an API key in the Braze dashboard

Required permissions

The permissions the API key needs depend on what you plan on syncing.

Object TypeRequired permissions
Usersusers.track, users.export.ids, users.delete (optional if you want to rely on Hightouch for user deletions)
Subscription statussubscription.status.set
User identificationusers.identify
Catalog itemscatalogs.add_items, catalogs.update_items, catalogs.get_item, catalogs.create, catalogs.get
Campaign triggerscampaigns.trigger.send, campaigns.list, campaigns.details

Braze region

To find the your Braze region, use the table below.


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.

Sync users

Hightouch supports syncing source rows 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.

Record matching

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.

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.

Selecting a source column to use as the Braze external ID in the Hightouch UI

Field mapping

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.

Mapping source columns to fields in Braze

You can manage your custom fields in Manage App Group > Custom Attributes in Braze.

Nested objects and object arrays

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.

Nested object array example

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:

    "id": 0,
    "type": "dog",
    "breed": "Mutt",
    "name": "Rae"
    "id": 1,
    "type": "cat",
    "breed": "Tabby",
    "name": "Garfield"

This full object array would need to be the value of a column in your Hightouch data model:

Value of an example "Pets" field shown in the Hightouch UI

Then you would map this column to the pets custom attribute in Braze in your Hightouch sync configuration:

Mapping the "Pets" field in the Hightouch UI

After scheduling your sync, you'd have relevant pet data on each user in Braze.

Pet data appearing in the Braze UI

Syncing and data point consumption

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 new records to 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 to records 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.

Sync events

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, use a hash function for the event model's primary key . The hash should combine all columns, including member ID, timestamp, etc. See the event sync 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.

Event configuration in the Hightouch UI

Record matching

Hightouch matches events to users based on user ID. If you are creating users that don't exist, you can only match based on external ID. Otherwise you can match based on Braze ID and user alias object.

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.

Record matching for events in the Hightouch UI

Field mapping

Hightouch lets you pass data to the event properties of a Braze event.

Field mapping for events in the Hightouch UI

Event property configuration

Hightouch lets you send all your custom properties as a single object column or as multiple columns from your model.

Event property configuration in the Hightouch UI

Sync subscription status

Hightouch supports syncing users to both Email and SMS subscription groups.

Subscription status configuration in the Hightouch UI

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.

Subscription group configuration in the Hightouch UI

Read Braze's docs for information on creating a subscription group.

Record matching

You can match records from your source to your Braze subscription groups by Braze External User ID, Phone Number, or Email.

Field mapping

You can map any source fields to user fields in Braze, for example name, email, etc.

Delete behavior

When a sync removes a subscription group, Hightouch makes an API request to set the subscription group's subscription_state to unsubscribed.

Merge anonymous and known users

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:

  1. 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.
  2. 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.
  3. 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.”
  4. All subsequent updates to the user should be done in Hightouch using the external user ID, not the user alias.

The merge process deletes any user attributes recorded in an alias-only user, so make sure you back up any data you want to save or have synced it to the relevant users using external IDs.

Record matching

You can match and merge records using Braze user external IDs.

Selecting a source column to use as the Braze external ID in the Hightouch UI

Field mapping

Hightouch lets you map your Braze aliases to known users using the alias label and value.

Field mapping for users in the Hightouch UI

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.

"user_aliases": [
      "alias_label": "label",
      "alias_name": "name_1"

"user_aliases": [
      "user_alias" : {
        "alias_name" : "label",
        "alias_label" : "name_1"

Sync catalog items

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.

Hightouch UI showing option to create new catalogs

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.

Record matching

In Upsert and Update modes, you can match records from your source to your Braze workspace using the catalog item ID.

Field mapping

You can map data from your source to any existing field in your catalog.

If automatically creating a catalog, you can't add new fields or change data types after the initial sync.


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.

Trigger campaigns

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.


Before you can set up a Hightouch sync to trigger a campaign, you need set up an API-triggered campaign in Braze. See how to create an email campaign in Braze for more information.

Hightouch can only trigger campaigns that are API-triggered. These are different from API campaigns.

Record matching

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.

Field mapping

This destination allows you to customize your messages via API trigger properties. Hightouch automatically lists trigger properties you can map values with. See using the templated content included with an API request for more information.


Hightouch recommends that you test with your email before running an actual sync for your users.

You can test by following these steps:

  1. 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.
    Screenshot of Google Sheet with test information
  2. Use the Google Sheet as a source to add yourself to Braze as a user.
    Syncing information from Google Sheet to Braze using Hightouch

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.

  1. 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.
  2. Set up your campaign trigger sync and run it on Hightouch.
  3. 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.

Tips and troubleshooting

Required permissions

If your syncs are failing, check that the REST API key you use to connect Braze to Hightouch has the correct permissions for your sync type or types.

Slow initial sync

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.

Batch size limitation

Hightouch limits the update batch size to 35 attributes per API request rather than the 75 allowed by Braze. This is because of a Braze limitation when updating nested objects in an array.

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 in one API request:

  • 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

Hightouch processes 35 users at once in case each user in the update requires two update actions.

Live debugger

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.

Sync alerts

Hightouch can alert you of sync issues via Slack, PagerDuty, SMS, or email. For details, please visit our article on alerting.

Ready to get started?

Jump right in or a book a demo. Your first destination is always free.

Book a demoSign upBook a demo

Need help?

Our team is relentlessly focused on your success. Don't hesitate to reach out!

Feature requests?

We'd love to hear your suggestions for integrations and other features.

On this page

OverviewSupported syncingGetting startedAPI keyBraze regionSync usersRecord matchingField mappingNested objects and object arraysSyncing and data point consumptionSync eventsRecord matchingField mappingEvent property configurationSync subscription statusRecord matchingField mappingDelete behaviorMerge anonymous and known usersRecord matchingField mappingSync catalog itemsRecord matchingField mappingTestingTrigger campaignsPrerequisitesRecord matchingField mappingTestingTips and troubleshootingRequired permissionsSlow initial syncBatch size limitationLive debuggerSync alerts

Was this page helpful?