Integrating SmartSurvey with Braze

The Braze integration connects SmartSurvey with your Braze
workspace, so you can act on feedback as soon as it arrives.

Before you start

You will need 2 things from Braze: a REST API key and your REST endpoint. A Braze administrator can create the API key for you.

In Braze, go to Settings > APIs and Identifiers > API Keys and select Create API key.
Give the key a name, such as SmartSurvey.
Under Permissions, select users.track and users.export.ids, then save the key.
Copy the key. You will paste it into SmartSurvey in the next step.

Your REST endpoint depends on which Braze instance your account is on. It looks like https://rest.iad-01.braze.com and matches the number in your Braze dashboard address. For example, if you log in at dashboard-01.braze.com, your REST endpoint is https://rest.iad-01.braze.com. See the Braze article API overview for the full list of endpoints.

Making the connection

To start, choose Automate from the survey options after the Build stage. You will then see the list of available integrations.

To connect to Braze, select the Configure button next to the Braze icon. You can use the Braze Sandbox first to prove your connection and integration. You will need to recreate completely to connect to a production account.

If this is the first time your SmartSurvey account is connecting to Braze, you will be prompted to create a connection.

This lets you name the connection, which is useful if you need to connect to more than one Braze workspace. Add your chosen name and select Create new connection.

You will now be prompted to link your Braze account with SmartSurvey. Enter:

API key: the REST API key you created in Braze
REST endpoint: the REST endpoint for your Braze instance, such as https://rest.iad-03.braze.com

If you already have one or more Braze connections set up, they will be listed above the Add new connection box. Select Use next to the one you want.

Basic configuration

You can set up the following actions with Braze:

Push actions	Pull actions
Create Record	Get Record by ID
Update Record	Get Contact by Email

Name

Integration Name: add a name for the integration

Integration type

Push: send data from SmartSurvey to Braze
Pull: retrieve data from Braze

Push actions

Create Record: adds a new record to the target object, or updates the user if they already exist in Braze
Update Record: changes the data in an existing user profile in Braze

Pull actions

Get Record by ID: finds a Braze user by their ID and reads their data
Get Contact by Email: finds a Braze user by their email address and reads their data

If Get Record by ID or Update Record is selected, an extra Record ID field appears. The integration needs this to know which Braze user it is reading or changing each time it runs. See Getting a Record ID into a Survey.

Triggers

There are 3 options for triggering the integration:

Completed: the respondent completes the response in the usual way
Disqualified: the respondent completes the response by triggering a skip logic rule that disqualifies them
Updated: the respondent, or the survey editor, completes the response after opening it with an edit link

You can select these in any combination. Completed is selected by default.

Objects

Use the drop-down to choose the Braze object the integration targets:

Users: Braze user profiles, such as name, email and custom attributes
Events: custom events logged against a user, such as survey_completed
Purchases: purchases logged against a user

Events and Purchases are available with Create Record only. You can use custom events sent from SmartSurvey to trigger Braze campaigns or Canvases set up with action-based delivery.

Record ID

For Get Record by ID and Update Record, you need to tell the integration where to find the user's ID. The field is headed Users ID.

Braze identifies users by their external ID, which is the user ID your own systems give each customer. Get Record by ID also accepts a user's Braze ID. For Get Contact by Email, supply the respondent's email address instead.

Use the Select merge code drop-down to choose from survey data or variable data. For more details on passing this data into SmartSurvey, see Getting a Record ID into a Survey – Custom Variable Method.

Note for advanced SmartSurvey users: the merge codes used by this function look similar to SmartSurvey piping codes, but they are not the same. Use the Select merge code and Insert functions instead of copying a piping code from elsewhere.

Field mapping (push actions only)

The Field Mapping page appears once you select Next step on the main integration configuration page for a push action.

For a Braze integration, the Field Mapping page lists all the fields in the targeted object down the left, with boxes on the right for your mapping settings for each field.

When you create records in the Users object, always map External ID. Braze uses it to decide whether to create a new user or update an existing one. When you send custom attributes, use the attribute name exactly as it appears in Braze, as names are case-sensitive.

[Screenshot: Braze Field Mapping page]

Select Add field for additional fields

Select Custom Attributes. Enter custom attributes field and the exact name

To map a field, select its box to see the mapping options. There are 2 main options, Variables and Formulas, shown as tabs on the mapping pop-up. Each tab has several options to choose from.

Variables

The Variables tab lets you map specific variables directly to the object field.

Questions: the answers to the questions on the survey
Respondent Details: information about the respondent, such as response time, IP address (if the survey is not anonymous) and selected language
Survey Details: details about the survey, such as its name or nickname
Custom Variables: any custom variables associated with the survey
Contact Info: information from the contact list

Formulas

The Formulas tab lets you choose or create functions that change variables before they are sent to Braze. Most of the list are ready-made functions for common changes, such as extracting a first or last name, getting the domain from an email address, or combining text. You can stack formulas, so a field can use the output of one formula as the input to another.

Work your way through the listed fields and map them in turn. Your progress is saved every time you make a change, so there is no Save changes button. Once you have mapped everything you need, close the field mapping screen by selecting the X icon in the upper-right corner.

Pull integrations

Pull integrations retrieve data from Braze to use in the survey, rather than sending data to Braze once the response is complete. You can show the retrieved data in piping tags as part of the survey content, or use it as default answers.

Finding the data

First, tell the integration which Braze user to retrieve. You do this in the integration configuration described above, using the user's ID for Get Record by ID or their email address for Get Contact by Email. The pull integration retrieves the data each time the survey displays an integration piping tag.

If more than one Braze user has the same email address, Get Contact by Email returns the user who has an external ID.

Displaying the data

To show the data in your survey, or as a Default Answer, use a piping tag in this format:

[integration(fields.field_name)]

Replace field_name with the internal name of the Braze field. This is not the label you see in the Braze dashboard, but the name Braze uses in its API. It is all lowercase, with underscores instead of spaces.

Braze field	Piping tag
First name	[integration(fields.first_name)]
Last name	[integration(fields.last_name)]
Email	[integration(fields.email)]
Phone	[integration(fields.phone)]
Country	[integration(fields.country)]
Language	[integration(fields.language)]
City	[integration(fields.home_city)]
External ID	[integration(fields.external_id)]

So, to show the respondent's first name from Braze, add the tag:

[integration(fields.first_name)]

You will need to type pull integration tags manually, as the piping tag menu cannot list them.

Troubleshooting

Connection fails: check the API key was copied in full and the REST endpoint matches your Braze instance
Permission error: check the API key has the users.track and users.export.ids permissions in Braze
No data returned: check the user exists in Braze with that external ID or email address, as Braze only returns fields that have a value