Using Salesforce with Customer.io Journeys
PremiumThis feature is available on our Premium and Enterprise plans. UpdatedWhen you set up a Salesforce source for use with Customer.io Journeys, you’ll need to map your Salesforce data to people, custom objects, or events.
You’ll set up a sync for each kind of data you want to send through your pipeline. In most cases, you’ll want to follow our typical mappings. But the way you map your data to Customer.io depends on what you want to do with it—send messages, use it to trigger messages, or manage relationships!
Typical mappings
Remember, you’ll convert your Salesforce data to people, events, custom objectsNot to be confused with a JSON object, an object in Customer.io is a non-person entity that you can associate with one or more people—like a company, account, or online course. You can use objects to message people based on changes to their company, account, or course itinerary., or relationships. You’ll see our typical mapping suggestions below.
Notice the * next to Leads! Leads fill multiple roles in Salesforce, so you might map them to people, objects, or both. We’ve provided more information about leads below to help you figure out how you want to map them to Customer.io.
| Data Pipelines format | Source call | Typical Salesforce objects |
|---|---|---|
| People | identify | Contacts, Leads* |
| Events | track | Tasks |
| Custom Objects | group | Accounts, Opportunities, Campaigns, Leads* |
| Relationships | group | Account-Contact Relationships, Opportunity-Contact Relationships |
The image below doesn’t show relationships. That’s because relationships aren’t a type of data themselves; rather, they’re a relationship between two data types. You won’t sync relationships unless you have two other data types you need to relate to each other. For example, if you only sync contacts, you won’t need to sync relationships. But if you sync contacts and accounts, you’ll need to sync relationships to relate contacts to accounts! See Relationships: matching people to objects below for more information.
What custom object name do I set for a custom object or relationship?
In most cases, we set this automatically for you. The Custom Object Name is simply an attribute we set in Customer.io that tells us what kind of Salesforce data your object (or relationship) originates from. If you create a new sync and the custom objectNot to be confused with a JSON object, an object in Customer.io is a non-person entity that you can associate with one or more people—like a company, account, or online course. You can use objects to message people based on changes to their company, account, or course itinerary. doesn’t exist yet, don’t worry: you’ll create it in the Destination step when you set up your sync.
Relationship sync identifiers: matching people to objects
Salesforce treats people, custom objects, and the relationships between the two as discrete pieces of information. So, whenever you sync people and a kind of object, you’ll probably want to setup a separate Relationship sync between people and that object.
For example, when you sync accounts and contacts to Customer.io, you’ll also want to sync Account Contact Relationship information to capture relationships between your contacts and accounts. When you do this, you need to associate the ID of a person with the ID of an object. For accounts and contacts:
- The Field Containing Person ID is either the Contact ID or Contact.email
- The Field Containing Object ID is the Account ID
We try to mark important fields for you
When you look at relationship identifiers, we’ll tell you which values are references to a contact, user, object, and so on. We fetch values from your contacts or objects to make setting relationships easier. For example, contact.email isn’t in the Account Contact Relationship sync, but we fetch it from your contacts to make things easier for you!
Relationship attributes
Like people and custom objects, relationships also contain attributesA 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.
These are the things you can bring in on the Fields tab. You’ll see them when you look at a person’s relationships!
| Field mappings | Turn into relationship attributes! |
|---|---|
 |  |
How do I know if data is a person, event, or an object?
We’ve created a little decision tree to help you map data accordingly, but in short:
If you want to send messages to it, or you want to log events it performs, it’s a person.
In Customer.io, people are the basic unit you’ll operate against. People can receive messages and perform events. Objects themselves can’t receive messages or perform events. Think of it this way: an opportunity doesn’t have an email address; you’ll never send a message directly to an opportunity; an account can’t visit a page on your website. Those are things people do!
If something is related to people and the data has a lasting impact, it’s probably an object.
Custom objects are things that people are related to—like an account they belong to, a company they work for, or an opportunity they represent. They’re like people, in that they have attributesA 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. and, unlike events, they’re important long after they initially appear in your workspace.
If something represents people’s activities, it’s probably an event.
Events are things that people do, like when a user visits a page on your website, adds an item to their shopping cart, or watches a video. Events are really useful for responding to people’s activities in an automated way, like sending a calend.ly link to people who want to hear from you about your product.
than one person?} d-->|yes|e(It's an object) c-.->|no|d d-.->|no|f(It's either an event
or you don't need it)
Leads are people in Customer.io
In Salesforce, a Lead represents multiple things: it’s an unqualified contact, an unqualified account, and a potential opportunity. But in Customer.io, the most common use case is to map leads to people so that you can foster your relationship with a person as they move through your sales process and become a qualified contact.
- (Recommended) map leads to people: If you want to send messages to your lead, attempting to qualify and nurture them, then they must be people. This is the most common use case when sending leads to Customer.io Journeys.
- Map leads to objects: If you just want to track the opportunity or company represented by a lead until you have a qualified contact, you can map them to objects. But remember: if you do this, you must have a person that you want to relate the object to!
- Map leads to relationships: If you want to capture a lead as both a person and an object related to that person, you can set up two separate syncs that map leads to both people and objects!
Use email as the lead ID so leads graduate to contacts
A common use case for syncing leads to Customer.io is to send messages to leads to nurture, qualify, and convert them to contacts. But where Salesforce gives a person a lead ID and then a different contact ID when they graduate to a contact, Customer.io expects a single ID for a person throughout their lifecycle. So how do we make sure that a lead and contact in Salesforce resolve to the same person in Customer.io? We identify leads by email address.
When you set up your Leads sync, you’ll set the Lead ID to Email. When you set up your Contacts sync, you’ll identify people by Contact ID and pass the Email field. This means that when we sync leads to Customer.io, they’ll have an email address but no ID. Then when that person graduates to a contact, we’ll see a contact with the same ID as the lead and we’ll update that person with the contact ID and other information from your contacts sync.
& becomes contact a-->>b: Sync contact by ID
with email field note over b: Person now has an email
(from lead) and ID (from contact ID)
Leads become contacts associated with accounts and opportunities
When you qualify a lead in Salesforce, the record splits into those three things: a Contact related to an Account and an Opportunity. If you sync all three data types to Customer.io, then you’ll create or update records when you qualify the lead in Salesforce. So, whether you bring in a lead as a person or an object, it can eventually become a person and two related objects when you process or qualify it.
Remember to identify your Leads by email!
When you sync leads, set the Lead ID to Email so that your leads graduate to contacts in Customer.io. Otherwise, you may have separate entries for your contacts and leads in Customer.io, even though they represent the same person!
ready for you to act on?} d-->|yes|e(Salesforce lead
graduates into:) e-->f(Contact) e-->g(Account) e-->h(Opportunity) d-.->|no|i{Is the lead old, or did they
respond negatively to outreach?} i-->|yes|j(Lead fails
to graduate) i-.->|no, continue
nurturing lead|d
Tasks are often events
In general, we suggest that you map tasks to events because:
- Tasks, like events, are assigned to a single person
- They represent things that people do
- You can use events to trigger campaigns, automating your task Salesforce list
Tasks in Salesforce are basically a single person’s to-do list for leads, accounts, opportunities and so on. While Salesforce doesn’t have a concept of “events,” tasks fit this bill, more or less, by changing states when you mark something off the to-do list.
Think of it this way: You aren’t likely to manage your task list in Customer.io. Instead, you probably want to automate your tasks or respond to changes in your to-do list. You may want to send a message to a contact when their bill is due, or send a message that invites a lead to schedule a meeting with you.
Convert your timestamps
Customer.io and Salesforce use different formats for dates and times. Salesforce uses ISO-8601 timestamps (like 2021-09-01T09:00:00Z) and Customer.io uses Unix timestamps (like 1630512000). This difference can prevent you from using Salesforce date and time values with some Customer.io features.
Luckily, you can automatically convert Salesforce’s timestamps to the format Customer.io expects using settings in your Journeys Workspace destination. Go to Destinations > Journeys Workspace and click Actions. Edit each actionThe source event and data that triggers an API call to your destination. For example, an incoming identify event from your sources adds or updates a person in our Customer.io Journeys destination. and set Convert dates to Unix timestamps setting to true, and we’ll automatically convert incoming timestamps to support Customer.io.
Converting Salesforce timestamps to Customer.io’s Unix format lets you use Salesforce dates and times for things like for date-based conditions in segmentsA group of people who match a series of conditions. People enter and exit the segment automatically when they match or stop matching conditions. or date-triggered campaigns.
You need to convert timestamps again if you send data back to Salesforce
When you send data to Customer.io, you’ll convert dates and times to Unix timestamps. But if you send data from Customer.io to a Salesforce destination—like you might do with message metrics or webhooks—you’ll need to convert those timestamps back to ISO 8601 formatted dates and times.
Using email as an identifier
Customer.io lets you use email addresses as a way to identify people. Unlike Customer.io, Salesforce doesn’t require email addresses to be unique, so you may have multiple contacts with the same email address—which will cause errors in Customer.io.
If you can’t guarantee that email addresses in your Salesforce environment are unique to each contact, you should avoid mapping people to Customer.io by email address. Instead, you should use a unique Salesforce identifier, like the Contact ID.
If you identify people by email address and two contacts have the same email address, they’ll end up representing the same person in Customer.io. This issue can also cause Attribute Update errors in Customer.io as Salesforce attempts to update the ID of the person in Customer.io (which will not work).
