Search documentation...



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


To find the region code, use the table provided below to find the region of your REST / SDK endpoints.


You can also navigate to the Braze documentation to view any additional Regions they may add. In their table, they refer to this region as "REST ENDPOINT", you would just need to remove the prefix starting with https://rest.

To find the API key, navigate to Developer Console > API Settings and create a API key.

Syncing Objects

Hightouch supports syncing to the following Braze objects:

  • Users
  • Events
  • Subscription Statuses
  • User Identification

Sync Modes

This integration supports both the Upsert and Update mode.

In the Upsert mode, new users will be inserted into Braze and all attributes will be kept up-to-date within Braze.

In the Update mode, Hightouch will update attributes on users that already exist in Braze.

Record Matching

Records can be matched from your source to your Braze workspace by your Braze External User ID in the Upsert mode. In the Update mode, Hightouch also allows you to match records based on Braze ID or a user alias object.

Field Mapping

You can sync columns from your source to Braze's default and custom fields. If a custom field is sent that does not exist, it will be added and its type will be automatically detected.

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

Column-based Diffing

Braze pricing is based on data points, which will count the number of updates you (and Hightouch) make to user properties. With this in mind:

  • For records that enter the query results, Hightouch will update all the mapped properties with the value from your query results.
  • For records that are already in the query results, but are changed, Hightouch will first get the user properties from Braze, calculate which columns actually changed, then only send the changes for those columns.

Nested Objects and Object Arrays

Braze supports user attributes containing JSON objects or object arrays. This is commonly used to support "entities" related to each user (devices, medications, pets, etc.), especially when marketing communication needs to directly include metadata about these related entities.

Hightouch is a great tool to sync to these types of attributes, as you can simply leverage your data warehouse to manage these associations. All you'll need to do is build the full JSON object into a single column within your Hightouch data model. Modeling these attributes into JSON could be done directly in your warehouse (with something like dbt), or you could use SQL functions (appropriate for your DWH technology) and build these objects within the SQL statement in Hightouch that builds the model.


Let's say you want a nested object array of a customer's pets to be an attribute 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 looks 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:

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

Just schedule your sync and you'll have relevant pet data on each user in Braze!

Syncing Events

Hightouch supports syncing events to Braze and assigning them to a user.

Event Types

There are two types of events that can be sent 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

Creating Users with Events

Hightouch allows you to choose whether to create users that don't exist. For example, if you are tracking an event associated to user A, if user A does not exist in Braze, we can either choose to create the user, or ignore the event.

Track Configuration

Hightouch allows you to choose the event name, user ID and event timestamp for a track event. Tracking purchases does not require an event name. 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.

Hightouch accepts a normal date time format for the timestamp, and automatically convert it to the format that Braze requires.

Field Mappings

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

Event Property Configuration

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

Braze Subscription Group Status

Hightouch supports syncing users to Braze subscription groups.

Braze has a designated set of fields to manage subscription group opt-ins (totally independent of user attributes).

Subscription Group Types

Hightouch supports syncing to both Email and SMS subscription groups.

Selecting a Subscription Group

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.

For information on how to create a subscription group, read Braze's docs on creating new subscription groups.

Record Matching

Records can be matched from your source to your Braze subscription groups by Braze External User ID, Phone Number, or Email.

Braze User Identification

Hightouch supports merging alias-only "anonymous" users with fully created "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/phone, without forcing the user to create an account. This results in users where all you may have is PII. When they later create an account, you need to use this endpoint to “identify” these users with a new login id.

Any data recorded in an alias-only user will be deleted during the process of merging, so ensure any data you want to save is backed up.

Merging Users

Records can be matched and merged using Braze user external IDs.

Field Mappings

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


Permissions required

The user that is authenticated into Braze will need these permissions set in the Braze UI in order to interact with the API within Hightouch. These two attributes are:

  1. users.track
  2. users.export.ids

    Need help?

    Our team is relentlessly focused on your success. We're ready to jump on a call to help unblock you.

    • Connection issues with your data warehouse?
    • Confusing API responses from destination systems?
    • Unsupported destination objects or modes?
    • Help with complex SQL queries?

    Feature Requests?

    If you see something that's missing from our app, let us know and we'll work with you to build it!

    We want to hear your suggestions for new sources, destinations, and other features that would help you activate your data.

On this page

SetupSyncing ObjectsSync ModesRecord MatchingField MappingColumn-based DiffingNested Objects and Object ArraysSyncing EventsEvent TypesCreating Users with EventsTrack ConfigurationField MappingsEvent Property ConfigurationBraze Subscription Group StatusSubscription Group TypesSelecting a Subscription GroupRecord MatchingBraze User IdentificationMerging UsersField MappingsTroubleshootingPermissions required

Was this page helpful?