Mapping Salesforce data to destinations

When you send data from Salesforce to Customer.io, you’ll convert it to people, events, or custom objects. But why? And what kind of data type should you choose?

 Is Customer.io your destination? Do you want to send messages?

Check out our Salesforce with Journeys page for help connecting your Salesforce data to Customer.io, so you can send messages. This page is meant to help you set up Salesforce with other, non-Customer.io destinations.

How it works

Unlike most platforms, Salesforce doesn’t have generic concepts like People and Groups—or things that map easily to those terms. Instead, Salesforce has highly structured data: your leads, contacts, opportunities, accounts, and other things are all separate.

When you set up a Salesforce source in Customer.io, you’ll need to decide how you want to represent these entities downstream—whether they’re people, events, custom objects, or relationships. You’ll also pick the fields you want to capture from Salesforce for each type of incoming data.

How you represent Salesforce data downstream depends on the destinations you send your Salesforce data to and what you want to do with your data: you may model data differently when you connect your data to Customer.io Journeys, as opposed to an analytics platform like Mixpanel.

People, events, and custom objects

People, events, and objects correspond to Customer.io’s identify, track, and group methods respectively. Relationships also correspond to group calls, but they’re a little different, so we’ll discuss them below. It can help to think of your data in the following terms:

  • Is it an individual person? Do you want to send it messages? Map to people.
  • Is it something a person does? Map to events.
  • Is it a group of people or some kind of non-person thing? Map to custom objects.

People, created and updated by identify calls, represent individual users, customers, contacts, so on. In Customer.io, people are who you’ll send messages to, track events for, etc.

Events, created by track calls, are things that people do, like visiting pages on your website, adding items to shopping carts, or beginning online courses. Objects can’t perform events. When Salesforce converts data to an event, it’ll be associated with a person, not an object (or “group”).

Custom Objects, created and updated by group calls, are entities that you want to track like people, but aren’t people. They’re things like accounts, companies, or opportunities. People are often related to custom objects, like a person who works for a company or a person who manages an account.

flowchart LR a{Is it a contact?} a----->|yes|b(Person) a-.->|no|c{Is it associated
with >1 people?} c--->|yes|d(Custom
Object) c-.->|no|e{Does it have an
email or phone?} e-->|yes|b e-.->|no|f{Is it something people do?
Will it trigger messages?} f-->|yes|g(Event) f-.->|no|d

Relationships: matching people to objects

Salesforce treats people, custom objects, and the relationships between the two as discrete pieces of information. So, for example, when you sync accounts and contacts to Customer.io, you’ll also sync Account Contact Relationship information to capture relationships between your contacts and accounts. Whenever you need to capture a relationship between people and a group—like opportunities, companies, etc—you’ll need to set up a relationship sync to maintain those relationships.

Where people need a userId, and custom objects need a groupId, relationships need both. When you sync relationships, we associate the userId with the groupId. And, like people and custom objects, relationships also contain traitsA key-value pair that you associate with a person or an object—like a person’s name, the date they were created in your workspace, or a company’s billing date etc. Use attributes to target people and personalize messages. Attributes are analogous to traits in Data Pipelines. describing the relationship—like whether someone is directly related to an account, a primary contact, and so on. These attributes help you find the right person by association with an object, like when you need to find an account’s primary contact, or all active participants in an opportunity.

What about other Salesforce data types?

You can create custom data types in Salesforce to represent things meaningful to your business. With the Salesforce source, you can send your custom data to destinations just like any other data type.

When you go to create a sync, we’ll show you the most popular data types at the top of the list, and then we’ll show all of your other data types.

It’s up to you to decide how you want to represent your custom data downstream! The same principles above apply to both Salesforce’s most popular data types (like contacts) and any custom data types you’ve created in Salesforce.

when you create a sync, you'll select the type of salesforce data you want to import, starting with popular data types and moving on to other data types
when you create a sync, you'll select the type of salesforce data you want to import, starting with popular data types and moving on to other data types

Mapping identifiers and fields

When you setup your sync, you’ll tell people which fields represent your people and custom objects; you’ll also tell us which fields you want to pass to your destinations.

choose the identifiers and fields you want to use in destinations
choose the identifiers and fields you want to use in destinations

Unique Identifiers tells us which values represent people or objects—like a Contact ID or Account ID. Even when you send data representing an event, we either associate the event with a person! Objects and relationships have a Related Record ID. For relationships, this tells us how to relate people to objects. For custom objects, you can probably ignore this field.

set unique identifiers for your salesforce data
set unique identifiers for your salesforce data

The Fields to sync are the traits you want to pass to your destinations. You can toggle fields on and off when you set up or edit a sync.

determine which salesforce fields you want to keep in your destination
determine which salesforce fields you want to keep in your destination

 Some Salesforce data maps to reserved traits

We map some capitalized Salesforce data, like FirstName, to the snake-cased Data Pipelines format, firstName. We don’t otherwise change the data. Learn more about the fields we reserve.

In most cases, you can ignore the Related Record ID when you sync custom objects.

For each object in Salesforce, like an account, Salesforce typically keeps a canonical contact, user, or some kind of ID. For an account, this might be something like the Owner ID. This value is unlikely to change, and often represents the person who created an object in Salesforce.

While you can map this value in your sync, it’s unlikely to change and isn’t very useful unless you only care about the relationship between an object and its owner or creator in Customer.io. You’ll get far more value out of syncing relationships than you will by associating a single userID with an object/group.

Reserved traits

We reserve some traits for people and objects. So, when you map your incoming Salesforce data to people or objects, we convert some incoming properties—which are typically capitalized in Salesforce—to our snake-cased format. For example, a contact’s FirstName trait becomes firstName.

Reserved traits for people

Salesforce propertyData Pipelines traitNotes
CreatedDatecreated_atAn epoch timestamp (in seconds) based on CreatedDate. We don’t modify CreatedDate
DescriptiondescriptionAn optional description of the person.
EmailemailThe email address of a user.
FirstNamefirstNameThe first name of a user, contact, or lead.
LastNamelastNameThe last name of a user, contact, or lead.
NamenameFor users, contacts, or leads, this is a concatenation of the FirstName, MiddleName, LastName, and Suffix fields.
PhonephoneThe person’s phone number.
TitletitleThe person’s title, like CFO or CEO.
WebsitewebsiteA person’s website, typically associated with leads.

Reserved traits for objects

Salesforce propertyData Pipelines traitNotes
DescriptiondescriptionAn optional description of the group, like an explanation of an opportunity.
EmailemailThe email address of the group—like the primary email address for an account.
NamenameThe name of the group.
PhonephoneThe primary phone number of the group.
Copied to clipboard!
  Contents
Is this page helpful?