Account and opportunity objects

Learn how to use account and opportunity objects to build segments of users based on what account they belong to and what opportunities are available, then send personalized messages using Liquid tags.

important:

Account objects are currently in beta. Contact your Braze account manager if you’re interested in participating in this beta.

How it works

note:

Currently, only account objects are supported—but, opportunity objects are coming soon!

Account and opportunity objects are custom data structures that represent a user’s company (account) and any associated deals or offers (opportunities). These objects connect to user profiles, allowing you to build B2B-style segments and personalize messages using information such as company name, industry, role, or deal status—all powered through Braze catalogs, segmentation filters, and Liquid tags.

For example, you can target users who work in healthcare and send personalized messages to physicians and hospital administrators. Then, you can combine what you know about the user with details from a sales opportunity—such as a new tool or service tailored for healthcare organizations—to make your message even more relevant.

Prerequisites

Before you can use this feature, you must have users in Braze already.

Importing data to Braze

To use account objects within your messages, you’ll first need to import your data to Braze.

Step 1: Import user data

First, import your user data to Braze as a CSV file with the following fields. This helps Braze associate users with the correct accounts.

Field name Field type Required Description

account_id String Yes The account the user belongs to. This is the same as the id field from the account object (CRM ID).

external_id String Yes The user’s external ID in Braze.

user_alias_name String No* The user’s alias name in Braze.

user_alias_label String No* The user’s alias label in Braze.

email String No* The user’s email address.

phone String No* The users’s phone number.

user_role String No The role the user has at the account, such as “directory” or “employee.”

^{*One of external_id, email, phone, or user_alias is required to identify a user.}

Next, upload your CSV with user and account associations to Braze:

Go to Data Settings > Accounts.
Select Update data.
Under CSV upload, select Users, then upload your file to Braze.

The "Upload data" dropdown on the "Accounts" page in Braze.

Step 2: Import account data

Accounts are companies that your users belong to. Import your account data to Braze as a CSV file with the following fields. Keep in mind, each account must be assigned an ID and a name.

Field name Field type Required Description

id String Yes The account’s ID in your Customer Relationship Management (CRM) platform.

name String Yes The name of the account.

type String No The type of account, such as a customer, partner, or reseller

annual_revenue String No Annual revenue of the account.

industry String No Industry in which the account operates.

number_of_employees String No Number of employees, supports for ranges.

address String No Street address of the account.

city String No City where the account is located.

state String No State where the account is located.

postal_code String No Postal code for the account’s address.

country String No Country where the account is located.

notes String No Additional notes about the account.

website String No Website URL for the account.

main_phone String No Main phone number for the account.

created_date Time No Date when the account was created.

account_owner_email_address String No An internal account owner (such as “Tom from Company A sales owns Company B”).

parent_account_id String No ID of the parent account, if applicable (such as linking to a parent company’s ID).

sic_code String No Standard industry classification code.

Custom fields N/A No Custom fields that are defined and managed by you.

note:

While some fields are optional, we still recommend including them as they are reserved field names, which helps keep your data organized.

Next, import your account data to Braze by uploading a CSV file or using the Braze REST API. This data can be accessed and viewed in Data Settings—however, edits to the data can’t be made using the in-browser editor.

using a csv file
using the braze api

To import your data through CSV:

Go to Data Settings > Accounts.
Select Update data.
Under CSV upload, select Account Data, then upload your file to Braze.

The "Upload data" dropdown on the "Accounts" page in Braze.

You can use the Braze /business/accounts API endpoint to create or delete accounts using PUT or DELETE HTTP methods.

To create multiple accounts, send a PUT request to /business/accounts. If an account doesn’t exist, a new item will be added in the Accounts page. Each request can support up to 50 catalog items. Note that this operation is asynchronous.

Your request should be similar to the following:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
curl -X PUT https://YOUR_REST_API_URL/business/accounts \
  -H "Authorization: Bearer YOUR-REST-API-KEY" \
  -H "Content-Type: application/json" \
  -d '{
          "accounts": [
              {
                  "id": "ACC001",
                  "name": "Acme Corporation",
                  "type": "Customer",
                  "annual_revenue": "$5,000,000",
                  "industry": "Manufacturing",
                  "number_of_employees": "150",
                  "address": "123 Industrial Way",
                  "city": "Metropolis",
                  "state": "NY",
                  "postal_code": "10001",
                  "country": "USA",
                  "notes": "Key client in the manufacturing sector",
                  "website": "http://www.acme.com",
                  "main_phone": "+1-212-555-1234",
                  "created_date": "2023-01-15T09:30:00Z",
                  "account_owner_email_address": "[email protected]",
                  "parent_account_id": "",
                  "sic_code": "2011"
              },
              {
                  "id": "ACC002",
                  "name": "Global Solutions",
                  "type": "Partner",
                  "annual_revenue": "$10,000,000",
                  "industry": "Technology",
                  "number_of_employees": "500",
                  "address": "456 Tech Park",
                  "city": "Silicon Valley",
                  "state": "CA",
                  "postal_code": "94043",
                  "country": "USA",
                  "notes": "Important partner for software solutions",
                  "website": "http://www.globalsolutions.com",
                  "main_phone": "+1-650-555-5678",
                  "created_date": "2023-02-20T14:45:00Z",
                  "account_owner_email_address": "[email protected]",
                  "parent_account_id": "ACC001",
                  "sic_code": "7372"
              },
              {
                  "id": "ACC003",
                  "name": "Oceanic Ventures",
                  "type": "Customer",
                  "annual_revenue": "$3,200,000",
                  "industry": "Retail",
                  "number_of_employees": "75",
                  "address": "789 Ocean Blvd",
                  "city": "Miami",
                  "state": "FL",
                  "postal_code": "33101",
                  "country": "USA",
                  "notes": "Expanding presence in retail markets",
                  "website": "http://www.oceanicventures.com",
                  "main_phone": "+1-305-555-6789",
                  "created_date": "2023-03-05T08:15:00Z",
                  "account_owner_email_address": "[email protected]",
                  "parent_account_id": "",
                  "sic_code": "5941"
              }
          ]
      }'

To create one account, send a PUT request to /business/accounts/:account_id. If the account doesn’t exist, a new item will be added to your catalog. Note that this operation is synchronous.

Your request should be similar to the following:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
curl -X PUT https://YOUR_REST_API_URL/business/accounts/ACC001 \
  -H "Authorization: Bearer YOUR-REST-API-KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "accounts": [
            {
                "name": "Braze",
                "type": "Customer",
                "annual_revenue": "$5,000,000",
                "industry": "Manufacturing",
                "number_of_employees": "150",
                "address": "123 Industrial Way",
                "city": "Metropolis",
                "state": "NY",
                "postal_code": "10001",
                "country": "USA",
                "notes": "Key client in the manufacturing sector",
                "website": "http://www.acme.com",
                "main_phone": "+1-212-555-1234",
                "created_date": "2023-01-15T09:30:00Z",
                "account_owner_email_address": "[email protected]",
                "parent_account_id": "",
                "sic_code": "2011"
            }
        ]
      }'

To delete multiple accounts, send a DELETE request to /business/accounts with a body containing a list of account IDs. Note that this operation is asynchronous.

Your request should be similar to the following:

curl -X DELETE https://YOUR_REST_API_URL/business/accounts \
  -H "Authorization: Bearer YOUR-REST-API-KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accounts": [
      { "id": "ACC001" },
      { "id": "ACC002" },
      { "id": "ACC003" }
    ]
  }'

To delete a single account, send a DELETE request to /business/accounts/:account_id. Note that this operation is synchronous.

Your request should be similar to the following:

curl -X DELETE https://YOUR_REST_API_URL/business/accounts/ACC001 \
  -H "Authorization: Bearer YOUR-REST-API-KEY"

Using objects in messages

note:

Currently, only account objects are supported—but, opportunity objects are coming soon!

After you’ve imported your data to Braze, you can use account and opportunity objects to build a segment and send personalized messages to users using Liquid.

Step 1: Build a segment

Next, build a segment that combines user data along with account and opportunity data. For this example, we’ll target directors at healthcare companies to increase registration for a new webinar at our health promotion company.

Go to Audience > Segments, then select Create Segment.
Give your segment a name.
In the Segment Builder, select the Business filter and set up the following segmentation filters. When you’re finished, select Save.

Filter Description

Role is exactly director Targets users whose role is specifically Director

Accounts industry matches regex healthcare Matches users in accounts with industries related to healthcare

important:

Currently, to use multiple account filters, select Add Criteria instead of using the OR/AND dropdown.

Segmentation filters set up to create a segment for users who are directors at healthcare companies.

note:

Segmentation will only work on the first 1,000 account and opportunity records that match the criteria. Additionally, you can have up to one business filter per segment, and all criteria must be contained within one filter.

Step 2: Use Liquid to personalize

Now you can personalize your message to send users information about their opportunities. In this example, let’s draft a message to our directors and link them to the webinar. We’ll even use a Braze catalog to pull out industry specific imagery to personalize the message.

Step 2.1: Personalize with account information

Select Business as the personalization type, then select Name to personalize the message with the user’s company name.

The following will be copied to your clipboard.

{% business %}
{{ accounts[0].name }}

Braze will generate the {% business %} tag, which sets an array named accounts that contains the account information for the account the user is associated with.

Let’s adjust the auto-generated output to create our message.

In the example below, we moved the call to the {% business %} tag to the top of the message and we personalize with the user’s first name. We use the account’s name to personalize the message. You can see that the Liquid output from before is the same but we just moved it around to different parts of the message.

{% business %}

Hi {{${first_name}}},

We would love to invite you and your peers at {{ accounts[0].name }} to join our latest webinar named "Creating Optimal Health Outcomes for Patients".  Click the link below to register.

The output is similar to the following:

Hi John,

We would love to invite you and your peers at Sunshine Health to join our latest webinar named "Creating Optimal Health Outcomes for Patients". Click the link below to register.

Step 2.2: Connect with catalogs

Next, let’s further personalize our message by leveraging Braze catalogs to add and store an image that corresponds to the healthcare company.

For this example, we’re assuming we have the following:

A catalog set up called industry_assets
The ID for each catalog entry is the name of an industry that corresponds to industries that we would see in our accounts
The image URL links for a primary and a secondary image.

The following is an example of the Liquid used for this personalization.

//Make a call to the business tag.  This sets the accounts array and prepares us to pull account data out.
{% business %}

//Assign the user's accounts industry to a variable called industry.  This step isn't required but it makes everything easier to read.
{% assign industry = {{accounts[0].industry}} %}

//Make a catalog_items call to the industry_assets catalog and ask for the industry item (in this case, it will ask for "healthcare")
{% catalog_items industry_assets industry %}

// Get the hero image for the "healthcare" industry
{{items[0].hero_image}}

Frequently Asked Questions (FAQ)

Can I add custom fields?

Yes. You can add custom fields to accounts and opportunities. If you have your own lead scoring method, you can also use a custom field on your account and opportunity object to track this.

Can a user be associated with more than one account?

No. Currently, each user can only have one account association.

Can one user profile contain multiple emails?

No. A user profile cannot have more than one email, such as a personal and work email.